[[DockScreen Talk Page|Discuss this page]].
=====Summary=====
  * <DockScreen>
    * **unid=**
    * **name=**
      * "={code}" Runs TLisp code. Must return a string
    * **desc=**
    * **type=**
      * "canvas"
      * "itemPicker"
      * "deviceSelector"
      * "weaponsSelector"
      * "armorSelector"
      * "miscSelector"
      * "customItemPicker"
      * "customPicker"
      * "subjugateMinigame"
    * **inherit=**
    * **backgroundID=**
      * UNID
      * "hero"
      * "image"
      * "none"
      * "object"
      * "schematic"
    * **nestedScreen=**
    * Zero or one <ListOptions> or <List>
      * **dataFrom=**
        * "player"
        * "source"
        * "station"
        * "={code}"
      * **criteria=**
      * **list=**
      * **initialItem=**
        * index of an item as it appears in the list
        * "={code}"
      * **rowHeight=**
      * **noArmorSpeedDisplay=**
      * **slotName=**
      * **noEmptySlots=**
      * **posX=**
      * **posY=**
      * **width=**
      * **height=**
      * Code: Returns a list of entries, each with the following elements
        * Title
        * Icon
        * Description
        * [Extra]
    * Zero or one <OnScreenInit> or <OnInit>
      * **gScreen**
      * **gSource**
      * **gData**
    * Zero or one <InitialPane>
      * **gScreen**
      * **gSource**
      * **gData**
    * Zero or one <OnScreenUpdate>
    * Zero or one <Display>
      * **display=**
      * **animate=**
      * **type=** Same as <DockScreen> **type**.
      * **dataFrom=**
      * Zero or one <OnDisplayInit>
      * Zero or more <Group>
        * **left=**
        * **top=**
        * **width=**
        * **height=**
        * **center=**
        * **vcenter=**
      * Zero or more <Text>
        * **id=**
        * **left=**
        * **right=**
        * **top=**
        * **bottom=**
        * **font=**
        * **color=**
        * **align=**
      * Zero or more <Image>
        * **left=**
        * **right=**
        * **top=**
        * **bottom=**
        * **align=** Horizontal alignment. Defaults to the left
          * "left"
          * "center"
          * "right"
        * **valign=** Vertical alignment. Defaults to the top
          * "top"
          * "center"
          * "bottom"
        * **transparent=**
        * Returns: An image desc
      * <Canvas>
        * **left=**
        * **right=**
        * **top=**
        * **bottom=**
    * One <Panes>
      * One <Default>. The first pane that appears by default when the screen is shown.
        * **layout=**
          * "bottomBar"
          * "left"
          * "right"
        * **desc=**
        * **noListNavigation=**
        * **showCounter=**
          * "true" Creates a <Counter> control element with **id="counter"** and **style="default"**
        * **showTextInput=**
          * "true" Creates a <TextInput> control element with **id="textInput"** and **style="default"**
        * Zero or one <OnPaneInit> or <Initialize>
        * <Controls>
          * <Counter>
            * **id=**
            * **style=**
              * "default"
              * "warning"
          * <ItemDisplay>
            * **id=**
            * **style=**
          * <ItemListDisplay>
            * **id=**
            * **style=**
          * <Text>
            * **id=**
            * **style=**
          * <TextInput>
          * **id=**
          * **style=**
        * <Actions>
          * One or more <Action>
            * **name=**
              * "[{key}]{text}" Binds {key}. Possible values are the same as those of **key**. If {key} is a letter or number, then it shows up as part of the name with a yellow color.
              * "*{text}" Same as **default="true"**
              * "^{text}" Same as **cancel="true"**
              * ">{text}" Same as **nextKey="1"**
              * "<{text}" Same as **prevKey="1"**
            * **id=** The **id** of the <Language>'s <Text> element that provides this action's name. The <Text> must return a string in the same format as **name**.
            * **descID=**
            * **prevKey=** Binds Up/Left arrow keys
              * "1"
              * "0"
            * **nextKey=** Binds Down/Right arrow keys
              * "1"
              * "0"
            * **default=** Binds the Enter key. Same as **key="Enter"**
              * "1"
              * "0"
            * **cancel=** Binds the Escape key. Same as **key="Escape"**
              * "1"
              * "0"
            * **key=** Binds the specified key to the action
              * "1"
              * "2"
              * "3"
              * "4"
              * "5"
              * "6"
              * "7"
              * "8"
              * "9"
              * "0"
              * "A"
              * "B"
              * "C"
              * "D"
              * "E"
              * "F"
              * "G"
              * "H"
              * "I"
              * "J"
              * "K"
              * "L"
              * "M"
              * "N"
              * "O"
              * "P"
              * "Q"
              * "R"
              * "S"
              * "T"
              * "U"
              * "V"
              * "W"
              * "X"
              * "Y"
              * "Z"
              * "Down"
              * "Right"
              * "Left"
              * "Up"
              * "Escape"
              * "Enter" or "Return"
              * "PageUp"
              * "PageDown"
            * **minor=**
            * Zero or one <Exit>
            * Zero or one <Navigate>
              * **screen=**
            * Zero or one <ShowPane>
              * **pane=**
            * Code
      * Zero or more additional panes

[[https://github.com/kronosaur/Transcendence/blob/f334d321dbbea5bebd47524391211ac4f0c158ef/Transcendence/CGameKeys.cpp#L87]]
[[https://github.com/kronosaur/Transcendence/blob/60651293d51ac1f0decd219828b458c0555fe866/Transcendence/CDockScreenActions.cpp#L815]]
====Rich Text Formatting====


FIXME Please correct any inaccuracies.

===<DockScreen>===

Dockscreens are powerful tools which can be used to display information to the player. When you dock with a station or wreck, what you are seeing is a dockscreen. Dockscreens can be used to play out a story, show data, and allow the player to trigger scripted events.

From the [[http://xelerus.de/index.php?s=mod&id=324|XML'd elementDocument]]
<code XML>
<DockScreen Attributes="UNID,name,type,backgroundID,desc" >
	<InitialPane></InitialPane>
	<ListOptions Attributes="dataFrom,list,initialItem"></ListOption>
	<OnInit></OnInit>
	<Panes>
		<* Attributes="desc,noListNavigation,showCounter,showTextInput" >
			<Actions>
				<Action Attributes="name,key,default,cancel,nextKey,prevKey" >
					<Exit/>
					<Navigate Attributes="screen" />
					<ShowPane Attributes="pane" />
				</Action>
			</Actions>
		<*/>
	</Panes>
</DockScreen>
</code>
A dockscreen's code looks something like this: 
<code XML>	
<DockScreen UNID="&dsPlanetRefuseDock;"	name= "=(objGetName gSource)">
			
	<Panes>
		<InitialPane desc= "If you attempted to land on a planet without re-entry equipment, you would burn up and/or crash. Both result in death.">
			<Actions>
				<Action name="Continue" imageID="&rsItemListScreen;" imageIndex="0" cancel="1" key="C">
					<Exit/>
				</Action>
			</Actions>
		</InitialPane>
	</Panes>
</DockScreen>
</code>

That code is from [[..:users:Schilcote|Schilcote's]] [[http://xelerus.de/index.php?s=mod&id=124|Dockable Planets]] mod.

[[modding:xml:dockscreen]] desc="">, the name of the pane is InitialPane. The desc="" is the text you see when you view the pane. Then, inside the pane's tags, you have the Action tag. Actions are the little pieces of text which run script when clicked on, or their key is pressed. The name="" of an action is the text displayed. The cancel="" is a boolean value which decides whether the action is triggered when the user presses ESC, and the key="" decides what keyboard key should choose this action.

The <[[Initialize]]> element is evaluated: \\
1. Whenever the pane is displayed (e.g., ([[..:functions:scrShowPane]]) or something). \\
2. Whenever the player moves the cursor in the list.

===Sub elements, attributes and globals===

The following are temporary [[..:functions:globals]] available within the DockScreen element.

  * gBuyCriteria
  * gCost
  * gItem
  * gMargin

Example

Here we see gMargin used within the ListOptions element in the dockscreen dsExchangeBuy from Transcendence.xml

<code xml>      <ListOptions
            dataFrom=   "station"
            list=      "*"
            >
         (switch
            (not gMargin)
               (scrSetListFilter gScreen intComputeSellPrice)

            (isfunction gMargin)
               (scrSetListFilter gScreen gMargin)

            (scrSetListFilter gScreen "*")
            )
      </ListOptions></code>

  * gPrevScreen
  * gPrevPane
  * gBonus
=== List Options ===
[[modding/xml/listoptions|List Options]] This is how you build custom dockscreens and what they have on the left side of the screen.
Go back to list of [[..:XML|tags]]