PAWS specification
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.
- pawsActionLocationWindow
- pawsActiveMagicWindow
- pawsBankWindow
- pawsBuddyWindow
- pawsButton
- pawsCharBirth
- pawsCharDescription
- pawsCharacterPickerWindow
- pawsChatMenuItem
- pawsChatWindow
- pawsCheckBox
- pawsChildhoodWindow
- pawsComboBox
- pawsConfigChat
- pawsConfigChatBubbles
- pawsConfigChatFilter
- pawsConfigChatTabs
- pawsConfigDetails
- pawsCreationMain
- pawsEditTextBox
- pawsListBox
- pawsMenu
- pawsMessageTextBox
- pawsMultilineEditTextBox
- pawsMultiLineTextBox
- pawsObjectView
- pawsRadioButton
- pawsRadioButtonGroup
- pawsScrollBar
- pawsSeqTreeNode
- pawsTabWindow
- pawsTextBox
- pawsTreeNode
- pawsWidget
- pawsWidgetTreeNode
- pawsWritingWindow
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.