PAWS specification

From PSwiki
Revision as of 22:19, 11 January 2015 by Redhound (talk | contribs) (→‎Unofficial XSD schema definitions)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

This document is about the XML schema, not the source code that manages the XML files.

In PlaneShift, a window in PAWS is defined by an XML file.

Example

Contents of yesno.xml as of 0.4.01. 

<widget_description>
 <widget name="YesNoWindow" factory="pawsYesNoBox" 
       visible="no" savepositions="no" movable="yes"
       resizable="no" >
        
   <frame x="0" y="0" width="644" height="300" border="no" />
   <bgimage resource="YesNo" alpha="0" />

       <widget name="Message Box" factory="pawsMultiLineTextBox">
           <frame x="180" y="80" width="300" height="108" border="no" />
           <font name="/planeshift/data/ttf/LiberationSans-Regular.ttf" r="200" g="200" b="200" size="10" />
       </widget>

       <widget name="YesButton" factory="pawsButton" id="-10" key="Y">
           <frame x="212" y="185" width="80" height="40" border="no"/>
           <font name="/planeshift/data/ttf/cupandtalon.ttf" r="255" g="255" b="255" size="20" />
           <label text="Yes" />
       </widget>

       <widget name="NoButton" factory="pawsButton" id="-20" key="N">
           <frame x="370" y="185" width="50" height="40" border="no"/>
           <font name="/planeshift/data/ttf/cupandtalon.ttf" r="255" g="255" b="255" size="20" />
           <label text="No" />
       </widget>
 </widget>
</widget_description>

Element reference

This section enumerates all of the elements in PAWS.

attr

attach

<attach
  point = { "PROPORTIONAL_LEFT" | "ATTACH_LEFT" |
            "PROPORTIONAL_RIGHT" | "ATTACH_RIGHT" |
            "PROPORTIONAL_TOP" | "ATTACH_TOP" |
            "PROPORTIONAL_BOTTOM" | "ATTACH_BOTTOM" } />

The attach element (which can have any arbitrary name) defines how a widget is bound to its parent widget. The point attribute is required and defines the attachment of one of its borders. It has no child nodes. The ATTACH* items will keep the same spacing on a window resize while the PROPORTIONAL* items will try to keep the same proportional space when the widget is resized. This can cause some issues so it's recommended to use ATTACH.

attachpoints

<attachpoints>
  <!-- Content: attach* -->
</attachpoints>

The attachpoints element contains a list of child nodes defining how the parent widget node is attached to its parent widget node. It contains a list of attach nodes (which can actually be named whatever as per the source code). It has no attributes.

bgcolour

<bgcolour
  r = int
  g = int
  b = int />

The bgcolour element defines the background colour of the widget. Its required attributes r, g, and b are integers within the range [0, 255] and define the red, green, and blue values of the background colour respectively. It has no child nodes.

bgimage

<bgimage
  resource = qname
  alpha = int
  fading = { "true" | "false" } />

The bgimage element defines the background image of the widget. Its required attribute resource defines what resource image to use for this widget's background. It has no child nodes.

The element alpha is an integer in the range [0, 255] that defines the widget's alpha transparency.

buttondown

buttonspecial

buttonup

checkbox

childborders

<childborders>
  <!-- Content: colour{5} -->
</childborders>

The childborders element contains a list of child nodes defining whatever the heck it does. It contains a list of five colour nodes (which can actually be named whatever as per the source code). It has no attributes.

colour

<colour
  r = int
  g = int
  b = int />

The colour element (which can have any arbitrary name) defines something and I have no clue. Its required attributes r, g, and b are integers within the range [0, 255] and define the red, green, and blue values of the border colour respectively. It has no child nodes.

column

columns

distance

Defines a camera zoom mayhap. The more is value, the closer the object. 

<distance 
  value = float />

font

<font
  name = qname
  size = int
  resizetoscreen = { "true" | "false" }
  scalefont = { "true" | "false" }
  r = int
  g = int
  b = int
  sr = int
  sg = int
  sb = int
  shadow = { "true" | "false" } />

The font element is used to define the font of the widget; in the case of a pawsButton it would be the font of the button text. The name attribute specifies the name of the font to use and is required.

form

frame

<frame
  x = int
  y = int
  width = int
  height = int
  border = { "yes" | "no" | "line" }
  justtitle = { "yes" | "no" }
  margin = int />

The frame element is used to define the position, dimensions, borders, and margins of the widget. If the widget has a parent widget, then this element defines the relative position of its parent widget node; else it defines the absolute position. It has no child nodes.

highlight

label

listbox

map

mask

<mask
  resource = qname />

The mask element defines the masking image of the widget, and is specific to "doll" widgets where it defines what parts to clip the rendering of the 3D "podium" world. A practical use is to give the doll widget a rigid non-rectangular border. Its required attribute resource defines what resource image to use for the masking image. It has no child nodes.

maxframe

<maxframe
  width = int
  height = int />

The maxframe element defines the maximum width and height of the widget.

minframe

<minframe
  width = int
  height = int />

The minframe element defines the minimum width and height of the widget.

newtitle

<newtitle
  ??? />

The newtitle element does absolutely nothing because no widget uses it.

nodewidget

publish

<publish
  data = qname />

This element describes the name of the event that will be published. Consider a scroll bar that will update a text box with it's current value. When defining the scroll bar we define a publish name for it: 

 <widget name="My Scroll Bar" factory="pawsScrollBar" direction="horizontal" minValue="0" maxValue="5.0" tickValue="0.1">
       <frame x="6" y="61" width="150" height="11" border="no" />
       <publish data="some_label_name" />
 </widget>

Now whenever this scrollbar sets it's value it will publish this value to all other widgets that subscribe to it by calling the virtual function OnUpdateData() for all subscribed widgets. So continuing our example the text box will be defined as: 

 <widget name="MyTextBox" factory="pawsTextBox">
   <frame x="6" y="61" width="150" height="11" border="no" />
      <subscriptions>
        <subscribe data="some_label_name" />
      </subscriptions>
 </widget>

In this case the OnUpdateData() is already defined for a text box and will set the string for the text box. You can subclass any widget and define your own OnUpdateData handler to handle published data. In the same way you can define what data will be published by your widget.

radio

scrollbar

subscribe

<subscribe
  data = qname />

The subscribe element defines what dynamic game element to subscribe to. The data attribute, if present, must be a valid resource name to subscribe to; for example "TimeOfDayStr" will subscribe to the in-game time.

subscriptions

<subscriptions
  overwrite = { "true" | "false" }
  format = qname>
  <!-- Content: subscribe+ -->
</subscriptions>

The subscriptions element contains a list of child nodes defining dynamic game elements to subscribe to; for example hitpoint values and changes to them. It contains a list of subscribe nodes (which can actually be named whatever as per the source code).

text

title

<title
  text = qname
  resource = qname
  align = { "left" | "center" | "right" }
  close_button = { "yes" | "no" }
  shadow = { "true" | "false" } />

The title element is used to define the title of the widget; particularly for title bars of windows.

widget

<widget
  name = qname
  factory = factoryname
  widget-attributes>
  <!-- Content: (widget*, widget-elements) -->
</widget>

The widget element is used to define a widget in PAWS. The particular widget that is created depends on the value of its required factory attribute. The name attribute specifies the name of the widget and is required.

widget_description

<widget_description
  name = qname>
  <!-- Content: widget+ -->
</widget_description>

The widget_description element is the root element of a PAWS XML file. It contains a list of widget nodes, and expects there to be one, if not more. The name attribute is only used in pawsMenu.

Factory reference

This section enumerates all of the widget factories in PAWS for widget elements.

Appendix

Specification grammar

The following grammar is used to help define these widget elements and is specific to this documentation: 

widget-elements   ::= font?, frame?, title?, newtitle?, childborders?,
                      bgcolour?, bgimage?, mask?, subscriptions?, publish?,
                      attachpoints?, minframe?, maxframe?

widget-attributes ::= style = qname
                      ignore = { "yes" | "no" }
                      visible = { "yes" | "no" }
                      savepositions = { "yes" | "no" }
                      movable = { "yes" | "no" }
                      configurable = { "yes" | "no" }
                      resizable = { "yes" | "no" }
                      resizetoscreen = { "yes" | "no" }
                      keepaspect = { "yes" | "no" }
                      ContextMenu = filename
                      xmlbinding = qname
                      tooltip = qname
                      inheritfont = { "yes" | "no" }

borderlist.xml grammar

The file borderlist.xml is used by something and I have no idea. The following is the DTD for borderlist.xml: 

<!ELEMENT borderlist (border+)>
<!ELEMENT border (topleft,topright,bottomleft,bottomright,leftmiddle,rightmiddle,topmiddle,bottommiddle)>
<!ELEMENT topleft (image)>
<!ELEMENT topright (image)>
<!ELEMENT bottomleft (image)>
<!ELEMENT bottomright (image)>
<!ELEMENT leftmiddle (image)>
<!ELEMENT rightmiddle (image)>
<!ELEMENT topmiddle (image)>
<!ELEMENT bottommiddle (image)>
<!ELEMENT image EMPTY>

<!ATTLIST border name CDATA #REQUIRED>
<!ATTLIST image file CDATA #REQUIRED>
<!ATTLIST image resource CDATA #REQUIRED>

chat_def.xml grammar

The files data/options/chat.xml and data/options/chat_def.xml are used by pawsChatWindow and pawsConfigChat. The latter provides the defaults for data/options/chat.xml in case it's omitted (not to be confused with data/gui/chat.xml which is the chat window itself). This file also contains the data for the badword filter. The following is the DTD for these two: 

<!ELEMENT chat (chatoptions,maintabincludes,flashingoptions,
                flashingoncharoptions,chatcolors,filters,msgfilters)>
<!ELEMENT chatoptions (selecttabstyle,echoscreeninsystem,loose,logAllChat,logSystemChat)>
<!ELEMENT maintabincludes (npc,tell,guild,group,auction,system,systembase,help)>
<!ELEMENT flashgingoptions (main,npc,tell,guild,group,auction,system,help)>
<!ELEMENT flashgingoncharoptions (main,npc,tell,guild,group,auction,system,help)>
<!ELEMENT chatcolors (systemtext,admintext,playernametext,chattext,telltext,shouttext,
                      guildtext,yourtext,grouptext,auctiontext,helptext,gmtext)>
<!ELEMENT filters (badwords)>
<!ELEMENT msgfilters (me*,vicinity*)>

<!ELEMENT selecttabstyle EMPTY>
<!ELEMENT echoscreeninsystem EMPTY>
<!ELEMENT loose EMPTY>
<!ELEMENT logAllChat EMPTY>
<!ELEMENT logSystemChat EMPTY>

<!ELEMENT main EMPTY>
<!ELEMENT npc EMPTY>
<!ELEMENT tell EMPTY>
<!ELEMENT guild EMPTY>
<!ELEMENT group EMPTY>
<!ELEMENT auction EMPTY>
<!ELEMENT system EMPTY>
<!ELEMENT systembase EMPTY>
<!ELEMENT help EMPTY>

<!ELEMENT systemtext EMPTY>
<!ELEMENT admintext EMPTY>
<!ELEMENT playernametext EMPTY>
<!ELEMENT chattext EMPTY>
<!ELEMENT telltext EMPTY>
<!ELEMENT shouttext EMPTY>
<!ELEMENT guildtext EMPTY>
<!ELEMENT yourtext EMPTY>
<!ELEMENT grouptext EMPTY>
<!ELEMENT auctiontext EMPTY>
<!ELEMENT helptext EMPTY>
<!ELEMENT gmtext EMPTY>

<!ELEMENT badwords (#PCDATA,replace*)>

<!ELEMENT me EMPTY>
<!ELEMENT vicinity EMPTY>

<!ATTLIST selecttabstyle value CDATA #REQUIRED>
<!ATTLIST echoscreeninsystem value CDATA #REQUIRED>
<!ATTLIST loose value CDATA #REQUIRED>
<!ATTLIST logAllChat value CDATA #REQUIRED>
<!ATTLIST logSystemChat value CDATA #REQUIRED>

<!ATTLIST main value CDATA #REQUIRED>
<!ATTLIST npc value CDATA #REQUIRED>
<!ATTLIST tell value CDATA #REQUIRED>
<!ATTLIST guild value CDATA #REQUIRED>
<!ATTLIST group value CDATA #REQUIRED>
<!ATTLIST auction value CDATA #REQUIRED>
<!ATTLIST system value CDATA #REQUIRED>
<!ATTLIST systembase value CDATA #REQUIRED>
<!ATTLIST help value CDATA #REQUIRED>

<!ATTLIST systemtext r CDATA #REQUIRED>
<!ATTLIST systemtext g CDATA #REQUIRED>
<!ATTLIST systemtext b CDATA #REQUIRED>
<!ATTLIST admintext r CDATA #REQUIRED>
<!ATTLIST admintext g CDATA #REQUIRED>
<!ATTLIST admintext b CDATA #REQUIRED>
<!ATTLIST playernametext r CDATA #REQUIRED>
<!ATTLIST playernametext g CDATA #REQUIRED>
<!ATTLIST playernametext b CDATA #REQUIRED>
<!ATTLIST chattext r CDATA #REQUIRED>
<!ATTLIST chattext g CDATA #REQUIRED>
<!ATTLIST chattext b CDATA #REQUIRED>
<!ATTLIST telltext r CDATA #REQUIRED>
<!ATTLIST telltext g CDATA #REQUIRED>
<!ATTLIST telltext b CDATA #REQUIRED>
<!ATTLIST shouttext r CDATA #REQUIRED>
<!ATTLIST shouttext g CDATA #REQUIRED>
<!ATTLIST shouttext b CDATA #REQUIRED>
<!ATTLIST guildtext r CDATA #REQUIRED>
<!ATTLIST guildtext g CDATA #REQUIRED>
<!ATTLIST guildtext b CDATA #REQUIRED>
<!ATTLIST yourtext r CDATA #REQUIRED>
<!ATTLIST yourtext g CDATA #REQUIRED>
<!ATTLIST yourtext b CDATA #REQUIRED>
<!ATTLIST grouptext r CDATA #REQUIRED>
<!ATTLIST grouptext g CDATA #REQUIRED>
<!ATTLIST grouptext b CDATA #REQUIRED>
<!ATTLIST auctiontext r CDATA #REQUIRED>
<!ATTLIST auctiontext g CDATA #REQUIRED>
<!ATTLIST auctiontext b CDATA #REQUIRED>
<!ATTLIST helptext r CDATA #REQUIRED>
<!ATTLIST helptext g CDATA #REQUIRED>
<!ATTLIST helptext b CDATA #REQUIRED>
<!ATTLIST gmtext r CDATA #REQUIRED>
<!ATTLIST gmtext g CDATA #REQUIRED>
<!ATTLIST gmtext b CDATA #REQUIRED>

<!ATTLIST replace bad CDATA #REQUIRED>
<!ATTLIST replace good CDATA #REQUIRED>

<!ATTLIST me type CDATA #REQUIRED>
<!ATTLIST me value CDATA #REQUIRED>

<!ATTLIST vicinity type CDATA #REQUIRED>
<!ATTLIST vicinity value CDATA #REQUIRED>

chatbubbles_def.xml grammar

The files data/options/chatbubbles.xml and data/options/chatbubbles_def.xml are used by pawsConfigChatBubbles. The latter provides the defaults for data/options/chatbubbles.xml in case it's omitted. The following is the DTD for these two: 

<!ELEMENT chat_bubbles (chat)> 
<!ELEMENT chat EMPTY>

<!ATTLIST chat_bubbles maxLineLen CDATA #REQUIRED>
<!ATTLIST chat_bubbles shortPhraseCharCount CDATA #REQUIRED>
<!ATTLIST chat_bubbles longPhraseLineCount CDATA #REQUIRED>
<!ATTLIST chat_bubbles enabled CDATA #REQUIRED>

<!ATTLIST chat enabled (yes|no) #REQUIRED>
<!ATTLIST chat colourR CDATA #REQUIRED>
<!ATTLIST chat colourG CDATA #REQUIRED>
<!ATTLIST chat colourB CDATA #REQUIRED>
<!ATTLIST chat shadowR CDATA #REQUIRED>
<!ATTLIST chat shadowG CDATA #REQUIRED>
<!ATTLIST chat shadowB CDATA #REQUIRED>
<!ATTLIST chat outlineR CDATA #IMPLIED>
<!ATTLIST chat outlineG CDATA #IMPLIED>
<!ATTLIST chat outlineB CDATA #IMPLIED>
<!ATTLIST chat align (left|center|right) #REQUIRED>
<!ATTLIST chat effectPrefix CDATA #REQUIRED>

zodiacs.xml grammar

The file zodiacs.xml is used by the pawsCharBirth factory. The following is the DTD for zodiacs.xml: 

<!ELEMENT zodiacs (zodiac+)>
<!ELEMENT zodiac (#PCDATA)>

<!ATTLIST zodiac month CDATA #REQUIRED>
<!ATTLIST zodiac img CDATA #REQUIRED>
<!ATTLIST zodiac name CDATA #REQUIRED>

Unofficial XSD schema definitions

The unofficial, auto-generated XSD v1.0 and v1.1 schema definitions for PAWS are available here.

Retrieved from "https://planeshift.top-ix.org//pswiki/index.php?title=PAWS_specification&oldid=20427"