Dockscreens come in two forms- stand alone elements and child elements of other objects (stations). A dockscreen that is a child of another object cannot be called from other objects, I believe. I mostly use stand alone screens that can be opened from any object.
In objects, <Dockscreens> is used and any screens can be named. This format inherits the UNID of the object, and so does not require a UNID="" in the elements.
The stand alone dockscreen element is easy to learn, let's look at the basic structure:
Code: Select all
<DockScreen UNID="&dsMyFirstDockscreen;"
name= "Screen Title"
backgroundID= "none"
>
<Panes>
<Default
desc="You are viewing an empty screen."
>
<Actions>
<Action name="Done" key="D" cancel="1">
<Exit/>
</Action>
</Actions>
</Default>
</Panes>
</DockScreen>
<Dockscreen>
All stand alone dockscreens are wrapped in a <Dockscreen *> </Dockscreen> tag. Inside of <Dockscreen> you must place a UNID to identify the screen, and you can add some other attributes:
name = "[string or function]" this attribute places the title for the screen. You can put string in there, such as "My Title" or you can put a function in there- such as "=(objGetName gSource)" Functions must be prefixed with a = to be recognized, otherwise your title would end up "(myFunction)". Trust me when I say that that is an embarrassing title to see! (Almost as bad as a "nil" when the function doesn't work right!)
backgroundID="[UNID]" simply points to a graphic resource- you can use this to set the 600 x 400 left portion of the screen to anything you like there.
Obviously, in the sample above the default background is used. You can keep the default background by placing "none" as the backgroundID.
type="[string]" this attribute can be placed in <Dockscreen > to control the type of screen you are using. There are several types. The default type (or absence of type attribute) is just the background image or lack thereof, but for other screens you can set type to be:
type= "itemPicker" This gives you a item list screen which is used for many purposes in the game. The item list also requires that the backgroundID be set to backgroundID= "&rsItemListScreen;" for best presentation.
The Item list is also controlled by a child element <ListOptions *> which I will explain below.
type= "customPicker" can be used to display a list of options or data. The custom list also requires that the backgroundID be set to backgroundID= "&rsItemListScreen;" for best presentation.
The Custom list is also controlled by a child element <List> which I will explain below.
Child Elements List
Here is a short list of the elements I have found in screens:
<Panes>
<InitialPane>
<OnInit>
<ListOptions>
<List>
<Display> (new!)
<ListOptions>
ListOptions is a very small element that simply declared where the Item list is being drawn from- the object that has the items. It can also be used to filter for specific item types and modifiers. Here is an example:
Code: Select all
<ListOptions
dataFrom= "station"
list= "*U"
/>
list= "[criteria]" accepts the standard search filters for items:
Code: Select all
* all categories
a armor
d device (weapon, shield, drive, etc.)
f fuel
l launcher weapon only
m missile
r reactor
s shields
t miscellaneous
u useful (armor coating, ROM, etc.)
v drive
w weapon (including launchers)
I is installed
D is damaged
N is not damaged
S is useable
U is not installed
modifiers:
+ must have this modifier
- must not have this modifier
<List>
List is used by the customPicker type of screen to display a custom list instead of items. The list is created by scripting, and can be very dynamic.
The list prepared requires a certain format to be displayed as an item: (list [Title] (list [Image]) [Description])
On the other hand, you can also just put in (list "This" "Is" "A" "List")
Here is an example of making an itemPicker style list:
Code: Select all
<List>
(block (showList)
;this list will look like an item screen
(setq showList (list
(list "Title One" "NoImageForThis" "Description One")
(list "Title Two" "NoImageHereEither" "Description Two")
))
)
</List>
I am a big fan of the customPicker screen.
<OnInit>
The <OnInit> element is designed to allow some scripting to set up the screen- for instance, when you dock at a station <OnInit> is the element that determines of you have to see the radiation contamination screen or if you get to go to the default screen. This element is used to perform many kinds of preparation for a dockscreen data that allows the screen to adjust to the conditions it finds.
OnInit is the place to perform some code when you first open a dockscreen.
<InitialPane>
InitialPane functions much like OnInit, except that whatever code is run there must return the name of a pane to be viewed.
<Display>
This is a great new feature in the game added in version 0.99. This allows you to do some very simple design-level controlling of the Display section of the screen. The display is the 600 x 400 left area where the background and item list normally reside. I wouldn't recommend trying to use display and an item list screen together. Use the display element to layer images and text on top of the background.
This element is used in the Korolov screens to great effect.
<Display> takes two types of child elements:
<Text>
<Image>
...
<Panes>
Panes are the most important part of the screens- every dockscreen uses at least one pane.
Panes have named child elements such as <MyPane>, although I think adding the <Default> pane is important.
These named child elements are what you see and navigate between in dockscreens and take the attributes for description text (right panel) and some special pane features such as the text entry box and the number entry box.
Pane Child Elements have two very useful and critical child elements of thier own:
<Actions>
<Initialize>
<Initialize> takes code blocks and can be used to alter the description, get the data on something, and other uses.
<Actions> requires child elements <Action> and is dedicated to the control of the right panel menu options.
(more to come on these!)