XML User Interface

NOTE: If you have any problems with creating interface skins, please be aware that as with all our XML features, we do not provide personal assistance. We highly recommend that you not even attempt to make your own skin unless you already have the knowledge necessary to use the tools we provided.

If you encounter any bugs, please report them using the /appeal system (our CSRs cannot help with custom UI questions or problems, and will not respond to any appeals on the topic, so please file a bug appeal only). Someone will look at the situation. You can also send a feedback form. You won't get an answer, but it will be passed on.

How To Use the XML User Interface



1. Overview & Definitions

With Trials of Atlantis, we are introducing a new user interface system. When we sat down during the design phase, we talked about the limitations of our original, somewhat static system, and features our technologically savvy players might enjoy. (Please note that as with our other XML features, we will not be able to provide any individual assistance. Please do not attempt to do a custom mod if you aren't completely comfortable with these explanations and instructions.) The end result was a new system that is partially data driven in XML and highly configurable.

For the remainder of this document we use the following terms:

  • A window is a single pane in the UI, usually displaying some data or having some control widgets that has been converted to the new system.
  • A panel is a window in the old system that has not been converted (see the Continuing Work section for more details)
  • A control is a ... well, a widget! It could be a button, icon, image, etc. A window can also be described as a collection of controls.
  • A skin is a set of texture data that redefines the graphical look of the interface. This includes repositioning data within a window.
  • A mod is a rearrangement of the data and controls on one or more windows to suit a particular need. Functionality added to the interface through the system can also be a mod.
  • An adapter is a piece of data used by the interface to control or display a given thing on one or more windows. All adapters are named.
  • A control template is the data needed to draw a given control common to all controls of that type.
  • A control definition is the specifics for a single control as that control is used in a particular window.
  • A window template is the set of control definitions and window attributes that let the system create that window.

1.1 Data Storage & Adapters

One of the biggest differences between the new and the old systems are how they deal with data. For the new system, all of the 'live' data for the interface is stored in a place conveniently named the 'data store'. The data store is basically a set of data that can be used to populate any number of different controls that make up the interface. Examples of the data stored here are: the name of the object being crafted on the timer window, the lines in the chat buffer, the color of each message type for the Chat Window, and the NPC dialog in the Interact Window.

Each piece of data is stored in an adapter. An adapter is a piece of data used by the interface to control or display a given thing on one or more windows. Every adapter has a name and can be accessed by a user mod. Furthermore, there are no hidden adapters in the UI, i.e., every adapter is available to users. The same adapter can be referenced any number of times by any number of controls on any window.

Adapters come in the following types distinguished by the type of data they contain:

  • Scalar adapters contain numerical data, e.g., a character's strength, the percentage of a timer bar, or the icon number for the right-click Mini-info Window.
  • Text adapters contain text data that is either single line or multi-line. Examples of text adapters are the title of the Timer Window when crafting and the data in the NPC Interact Window.
  • A color adapter is RGBA color data that determines the color of something, usually text. Examples of these are the message colors in the Chat Window and the title color for the right-click Mini-info Window.
  • A list box adapter is an adapter for a list box control that may or may not contain icons. Examples of these are the wares on the Merchant Window, the 'Additional Info' area of the character Stats Window, and the Concentration Window data.
  • A special type of scalar adapter is the time of day adapter that runs the clock.

Certain controls can bind to certain types of adapters in the XML data. A control's display will change to reflect changes in the adapter(s) it is bound to. Hence, a hitpoint bar will move when the target takes damage. For the specifics of which controls can be bound to which adapters, see Reference Section 4.

1.3 Control Templates

A control template can be thought of as the pattern on how to make a specific flavor of a given type of control. This usually (but not always) contains font assignments, texture coordinates, sizes and offsets. Control templates never contain adapter bindings. The control template is what the system uses to draw each control that makes up a window. In general, most control types (buttons, image areas, status bars) have multiple templates to vary the look and feel of these controls in the interface.

1.4 Window Templates

A window template is the pattern on how to make a specific window. Windows, unlike controls, cannot be duplicated. The data in a window template includes a set of window attributes like width and height, and a list of the controls that it contains in the form of control definitions.

1.5 Control Definitions

A control definition is the specific instance data that is needed to put a control on a given window. Control definitions always live in a window template in the XML data. Control definitions always contain position information and can also include size data, font names, and adapter bindings.

1.6 Events

The ToA UI is partially event driven. This means that when a button is clicked it sometimes fires off an event to the appropriate game subsystem to affect the game in some way. This can be data driven which is handy for modding since it means that event driven functionality can be duplicated over multiple windows. Only certain controls can generate events and not all events in the game are data driven. For a listing of data-drivable events, see Reference Section 4.

1.7 Panels & Skinning

Because the entire UI has not yet been converted to the new system, to make a completely new skin has a few extra steps. The old style panels have their own set of textures that they share that live in the data directory in the Atlantis folder. To skin panels, create versions of the appropriate textures and put them in the appropriate directory. Note that the positions of controls cannot be changed on panels. For a listing of which panels use which graphics, see the Reference Section.

1.8 Data Format

In general, any XML data file can contain any set of window or control templates in any order. In practice, most of the control templates are gathered into styles.xml and each window lives in its own xml file, e.g., chat_window.xml. Control definitions must exist as children of a window template otherwise they cannot be properly bound to a window.

Keywords in the XML data are not case sensitive but are spelling sensitive. Name bindings for templates and assets are also not case sensitive. Adapter names are case sensitive. Templates and assets can be arranged in any order in any file. All the XML data is loaded before any windows are instantiated to avoid unnecessary data dependencies. There is a special XML element that can be used to include other XML files. See the Reference section for Details.

Texture data can be in either BMP or TGA format. If transparencies are needed, a format with an alpha channel should be used. Font data has its own specific format (this will be explained in section 4). A note to Photoshop 7 users: there is a bug with early versions that prevents Photoshop to save TGA files correctly which will cause texture data to be improperly displayed in the interface.

Any file in the interface can be modified except uimain.xml which lives in the root ui folder (usually Mythic/Atlantis/ui/uimain.xml). This is a file that will be patched which controls which other files are loaded into the UI. This allows us to add new windows without requiring mod authors to make changes every time we patch. This has some caveats however, please refer to section 3.1: Getting Started for more details.

1.9 The Loading Process

When the ToA interface starts up it looks for the uimain.xml file in the root UI directory (usually Mythic/Atlantis/ui/uimain.xml). This file contains a listing of which other files to read and allows us to add new windows without breaking a lot of mods. Each file listed in uimain.xml is loaded each containing some subset of the interface's template and definition data.

If ever a file can't be found, the system looks in the Atlantis folder for it. Note that because of this, only those files that need to be modified need be included in the custom directory that holds the custom skin. Barring all else, the system prints an error to ui.log in the root Atlantis directory if it still can't find a file.

All XML data files are loaded before any windows are brought up.

1.10 Continuing Work

At the time of the creation of this document, not all of the UI has been converted to the new system due to time constraints. Work is continuing to convert the interface to the new system but it is a time consuming project.



How-To

This section contains some hands-on information with more of the specifics of how to do certain things. A general overview of the system can be found in section 2 and a reference for most of the system can be found in section 4.

2.1 Getting Started

Before creating a custom skin, do the following:

  1. Create a directory named 'custom' in the ToA UI directory (usually Mythic/Atlantis/ui)
  2. Create a directory named 'oldstyle' in the new custom directory
  3. Select the 'Custom' skin in the options menu

All changes made to the interface need to reside in the custom folder otherwise those changes will be overwritten the next time you log into the game (since it will patch them). Under no circumstances should the file Mythic/atlantis/ui/uimain.xml be modified - as we said before, this file can and will be changed by our patch process.

If no other changes are made and the game is started, the interface should look exactly like the Atlantis skin. This is because if the system can't find a file, it defaults to look for it in the Atlantis folder. The 'oldstyle' directory is for the textures used for old style panels. Again, if these files do not exist, the system will default to the Atlantis skin versions of these that live in Mythic/data/Atlantis.

It is highly recommended that one of the Atlantis or realm-specific skins be used as the basis for custom skins especially given that the system defaults to the Atlantis directory if it can't find something. The templates for the Transparent, Isles, and Classic skins are very different. Furthermore, to avoid a lot of extra mod work when we convert or add a new window, it is recommended that template names not be changed. We will use the old set of templates.

Other helpful hints:

  • get a good XML editor; it will make the modding process much easier
  • keep backups of your files to avoid losing changes
  • check the patch notes to see if any panels have been converted to windows or any windows have been added

2.2 Adding New Templates

There isn't anything tricky about adding a new template. New templates exist at the top level and can exist in any file. There are no ordering dependencies between templates since all XML data is loaded before any window is instantiated. Note that if a new template is added that has the same name as another template that has already been added, the system will discard the first one and keep the second one.

For ease of maintenance and development, the following things are recommended:

  • put custom templates in their own file to avoid confusion
  • keep the base templates around to avoid lots of rework when new windows are added

2.3 Adding Controls to Windows

Adding new controls to windows is as simple as adding a new control definition to an existing window template. Make sure if you assign a control ID to the new control that it isn't one of the ones that the window binds to in code. A listing of these is available in the reference section. Also, note that while it is possible to have controls that are outside the bounds of the window, these controls cannot be interacted with since interaction events only occur inside the bounds of a window.

One potential pitfall to adding controls to windows is that the order that they are listed in the window template is the order in which they are drawn. This is one of the only places in the new interface that ordering is important. Hence, if your background image is last in the window template, no other controls will be shown since the background will overdraw.

Common errors with adding new controls are:

  • ordering issues can cause controls to not be seen
  • ordering issues can cause controls to not receive events
  • most errors are naming erors

2.4 Changing Textures

Adding new textures to the interface is a four step process (assuming that the assets already exists):

  1. Copy the textures to the custom directory for controls and windows
  2. Copy the old style textures to the custom/oldstyle directory for panels
  3. Modify the file assets.xml to load the textures in the custom directory (the old style stuff doesn't need to be included here)
  4. Modify the appropriate control templates to use the new textures

Texture coordinates start at (0, 0) from the top left corner. Negative texture coordinates and texture coordinates that are off the edge of the texture page are undefined. Texture coordinates are integers and always map 1:1 pixel for pixel in the interface (i.e., stretching textures is not supported).

2.5 Changing Icons

Icons in the game can be changed. An icon sheet is a 10x10 page containing 100 icons. Icon sheets should be bitmaps and have two resolutions: one that has 16x16 pixel icons and one that has 32x32 pixel icons. The names of the icon sheets are hard coded and can be found in the reference section.

Until all the old style panels are converted to windows, modified icons need to be copied to both the custom directory and the old style directory.

2.6 Adding a New Font

Fonts have their own very specific graphical requirements. Fonts must have an alpha channel. In the alpha channel, each character needs to be underlined precisely with a one pixel tall row of pure white. In the first pixel column on the left hand side, one pixel must denote where the rows of underlines are. It is important that all the rows on a given line be lined up exactly. It also helps if the distance between the single pixels is the same horizontally.

What all these special lines and pixels are doing is denoting where each character is in the file. The single pixels in the left hand column are denoting the line heights. If the line heights are different between the rows, the tallest one is used as the height of the font. The rows are denoting each character in the font. If there's a break in the line it will try to count the character as two. If there's a line missing, that character will be missing in the font. Each character must be present in the precise order that the other fonts are in or the font will display garbled text.

Data can be put in the RGB channels but color data will distort when changing font colors in game. Once the graphic files are prepared, a new Font must be added to the assets that the game loads. The file assets.xml has examples of this.

Note that the names 'arial9', 'arial11', and 'arial14' are used for the resize font selectable in the front end UI. If they are not present, the game may not function properly.



Reference


3.1 Top Level Tokens

These are the top level tokens understood by the XML parser and brief descriptions about what they are/mean. This list is subject to change.

  • Include: specifies another XML data file to parse
  • Font: specifies a font
  • Texture: specifies a texture asset
  • Canvas: specifies a canvas asset
  • ButtonTemplate: specifies a control template
  • VerticalResizeImageTemplate: specifies a control template
  • HorizontalResizeImageTemplate: specifies a control template
  • FullResizeImageTemplate: specifies a control template
  • VerticalScrollbarTemplate: specifies a control template
  • MenuTemplate: specifies a control template
  • ComboBoxTemplate: specifies a control template
  • ListBoxTemplate: specifies a control template
  • TextAreaTemplate: specifies a control template
  • StatusBarTemplate: specifies a control template
  • ImageAreaTemplate: specifies a control template
  • StatusIconTemplate: specifies a control template
  • IconTemplate: specifies a control template
  • ChatControlTemplate: specifies a control template
  • CheckBoxTemplate: specifies a control template
  • VerticalStatusBarTemplate: specifies a control template
  • CompassControlTemplate: specifies a control template
  • WindowTemplate: specifies a window template

3.2 Adapter Reference

The following adapters and types are available.

  • timer_text text adapter
  • interact_text text adapter
  • interact_title text adapter
  • quest_text text adapter
  • info_text text adapter
  • info_title text adapter
  • mini_friends_text text adapter
  • group_name0 - group_name7 text adapter
  • group_class0 - group_class7 text adapter
  • group_power0 - group_power7 scalar adapter
  • group_status0 - group_status7 scalar adapter
  • group_health0 - group_health7 scalar adapter
  • group_color0 - group_color7 color adapter
  • group_level0 - group_level7 scalar adapter
  • group_0icon0 - group_7icon0 scalar adapter
  • group_0icon1 - group_7icon1 scalar adapter
  • group_0icon2 - group_7icon2 scalar adapter
  • group_0icon3 - group_7icon3 scalar adapter
  • group_0icon4 - group_7icon4 scalar adapter
  • group_0icon5 - group_7icon5 scalar adapter
  • group_number scalar adapter
  • group_mode scalar adapter
  • mini_craft_title text adapter
  • mini_info_string0 - 7 text adapter
  • mini_info_title_color scalar adapter
  • mini_info_icon scalar adapter
  • concentration scalar adapter
  • conc_list icon list adapter
  • chat_tab0 - chat_tab4 text adapter
  • chat_entry text adapter
  • chat0_color - chat63_color color adapter
  • system0_color - system63_color color adapter
  • chat_config_title text adapter
  • chat_config_channel0 - 15 text adapter
  • chat_config_current_output text adapter
  • chat_config_output_label text adapter
  • train_skills two column list adapter
  • train_realm two column list adapter
  • train_skill_points text adapter
  • train_realm_skill_points text adapter
  • compass_heading scalar adapter
  • merchant_page0 - 4 icon list adapter
  • merchant_title text adapter
  • merchant_max_pages scalar adapter
  • merchant_page_display text adapter
  • merchant_mithril text adapter
  • merchant_platinum text adapter
  • merchant_gold text adapter
  • merchant_silver text adapter
  • merchant_copper text adapter
  • merchant_quantity text adapter
  • summary_title text adapter
  • summary_target text adapter
  • summary_target_color color adapter
  • summary_player_hits scalar adapter
  • summary_player_end scalar adapter
  • summary_player_power scalar adapter
  • summary_exp_fine scalar adapter
  • summary_exp_coarse scalar adapter
  • summary_target_hits scalar adapter
  • summary_hit_label text adapter
  • stats_name text adapter
  • stats_level scalar adapter
  • stats_realm_points scalar adapter
  • stats_race text adapter
  • stats_base_class text adapter
  • stats_profession text adapter
  • stats_title text adapter
  • stats_weapon_damage scalar adapter
  • stats_weapon_skill scalar adapter
  • stats_hitpoints scalar adapter
  • stats_armor_factor scalar adapter
  • stats_strength scalar adapter
  • stats_strength_color color adapter
  • stats_constitution scalar adapter
  • stats_constitution_color color adapter
  • stats_dexterity scalar adapter
  • stats_dexterity_color color adapter
  • stats_quickness scalar adapter
  • stats_quickness_color color adapter
  • stats_empathy scalar adapter
  • stats_empathy_color color adapter
  • stats_piety scalar adapter
  • stats_piety_color color adapter
  • stats_intelligence scalar adapter
  • stats_intelligence_color color adapter
  • stats_charisma scalar adapter
  • stats_charisma_color color adapter
  • stats_additional_info two column list adapter
  • craft_title text adapter
  • guild_name text adapter
  • guild_rank text adapter
  • realm_title text adapter
  • realm_rank text adapter
  • realm_rank scalar adapter
  • realm_level scalar adapter
  • realm_skillpoints scalar adapter
  • bounty_points scalar adapter
  • house_lot scalar adapter
  • max_encumberance scalar adapter
  • cur_encumberance scalar adapter
  • realm_exp_fine scalar adapter
  • realm_exp_coarse scalar adapter
  • siege_title text adapter
  • siege_ammo icon list adapter
  • performance_meter scalar adapter
  • lag_meter scalar adapter
  • framerate_meter scalar adapter
  • master_exp scalar adapter
  • master_rp scalar adapter
  • master_rank scalar adapter
  • master_list text adapter
  • master_title text adapter
  • mini_pet_title text adapter
  • mini_pet_effect0 - 5 scalar adapter
  • mini_pet_life scalar adapter
  • mini_pet_combat0 scalar adapter
  • mini_pet_combat1 scalar adapter
  • mini_pet_combat2 scalar adapter
  • mini_pet_movement0 scalar adapter
  • mini_pet_movement1 scalar adapter
  • mini_pet_movement2 scalar adapter
  • mini_pet_movement3 scalar adapter
  • new_quest_opt_reward_state0-7
  • alb_low_pop_rp_bonus text adapter
  • mid_low_pop_rp_bonus text adapter
  • hib_low_pop_rp_bonus text adapter

3.3 Control Templates

This is a listing of every option in every control template. Also included is a brief description of what the control is for.

Many templates contain one or more of the following compound types. These are also used for definitions.

Bool
Boolean values can be either 'true' or 'false'. All other values are parsed as 'false'.

Color
R: 0-255 value for the red component of the color
G: 0-255 value for the green component of the color
B: 0-255 value for the blue component of the color
A: 0-255 value for the alpha component of the color

TextureCoordinate
X: x-value of the upper left hand corner of the texture coordinate
Y: y-value of the upper left hand corner of the texture coordinate

Size
X: x-value of the size (must be positive)
Y: y-value of the size (must be positive)

Point
X: x-value of the point (can be negative)
Y: y-value of the point (can be negative)

Alignment
Alignment flags determine how a component deals with resizing and how to interpret its position. Multiple alignment flags can be specified but some are conflicting. The behavior of conflicting alignment flags is undefined. The values for alignment flags are either 'true' or 'false'.
TopLeft: default alignment, sticks to top left
CenterHorizontally: attempt to center horizontally
CenterVertically: attempt to center vertically
OffsetBottom: y-coordinate is offset from the bottom of the window
OffsetRight: x-coordinate is offset from the right of the window
GrowWidth: control will resize horizontally with the window
GrowHeight: control will resize vertically with the window

The following are the control templates. The type of the element is marked with parenthesis. Note that when a 'name' is supplied as the type, it denotes that it corresponds to an asset or a template. Names must be 31 characters or less. Note that where multiple texture coordinates are specified for a control, they must come out of the same texture page.

ButtonTemplate
This is the template for a button control. Buttons have five states: normal, highlit, pressed, pressed & highlit, and disabled.
Name: (name) the name of this template
Size: (size) the size of the button
Font
Name: (name) the name of the font
ColorNormal: (color) the color of the font in the normal state
ColorPressed: (color) the color of the font in the pressed state
ColorHighlit: (color) the color of the font in the highlit state (normal &pressed)
ColorDisabled: (color) the color of the font in the disabled state
Texture
TextureName: (name) the name of the texture asset
Normal: (texture coord) the coordinate for the normal state texture
Pressed: (texture coord) the coordinate for the pressed state texture
NormalHighlit: (texture coord) the coordinate for the normal highlit state texture
PressedHighlit: (texture coord) the coordinate for the pressed highlit state texture
Disabled: (texture coord) the coordinate for the disabled state texture

VerticalResizeImageTemplate
This is the template for an image that can resize vertically. These are used for scrollbars and vertical status bars. The image is constructed by adding the top piece and tiling/repeating/truncating the repeating piece until the bottom piece can be added. The top and bottom pieces are always present and never truncated or repeated.
Name: (name) the name of this template
Width: (number) width of the image in pixels
TopHeight: (number) height of the top piece in pixels
RepeatHeight: (number) height of the repeat piece in pixels
BottomHeight: (number) height of the bottom piece in pixels
Texture
TextureName: (name) the name of the texture asset
Top: (texture coord) the coordinate of the top piece
Repeat: (texture coord) the coordinate of the repeating piece
Bottom: (texture coord) the coordinate of the bottom piece

HorizontalResizeImageTemplate
This is the template for an image that can resize horizontally. These are used primarily for status bars. The image is constructed by adding the left piece and tiling/repeating/truncating the repeating piece until the right piece can be added. The left and right pieces are always present and never truncated or repeated.
Name: (name) the name of this template
Height: (number) height of the image in pixels
LeftWidth: (number) width of the left piece in pixels
RepeatWidth: (number) width of the repeating piece in pixels
RightWidth: (number) width of the right piece in pixels
Texture
TextureName: (name) the name of the texture asset
Left: (texture coord) the coordinate of the left piece
Repeat: (texture coord) the coordinate of the repeating piece
Right: (texture coord) the coordinate of the right piece

FullResizeImageTemplate
This is the template for an image that can resize in both directions. These are used for backgrounds and insets. The image is constructed from the upper left corner and each of the middle/center pieces are tiled until the right hand side, bottom, and bottom right corner can be placed. The upper left and bottom right pieces are never tiled or truncated. The top and bottom middle pieces are tiled horizontally and the left and right side middle pieces are tiled vertically.
Name: (name) the name of this template
TopHeight: (number) the height of the top row of images in pixels
MiddleHeight: (number) the height of the repeating pieces in pixels
BottomHeight: (number) the height of the bottom row of images in pixels
LeftWidth: (number) the width of the leftmost column of images in pixels
MiddleWidth: (number) the width of the middle pieces in pixels
RightWidth: (number) the width of the rightmost column of images in pixels
Texture
TextureName: (name) the name of the texture asset
TopLeft: (texture coord) the upper left corner coordinate
TopMiddle: (texture coord)
TopRight: (texture coord)
MiddleLeft: (texture coord)
MiddleMiddle: (texture coord)
MiddleRight: (texture coord)
BottomLeft: (texture coord)
BottomMiddle: (texture coord)
BottomRight: (texture coord)

VerticalScrollbarTemplate
This is the template for vertical scrollbars. Vertical scrollbars are often subcomponents of other controls like list boxes and text areas. The active zone is the area outside the scrollbar that it continues to scroll when dragging. Outside this zone, the scrollbar will not drag.
Name: (name) the name of this template
ThumbVResizeTemplate: (name) the name of the slider template (vertical resize image)
UpButtonTemplate: (name) the name of the up button template
DownButtonTemplate: (name) the name of the down button template
GutterVResizeTemplate: (name) the name of the gutter template (vertical resize image)
Width: (number) the width of the scrollbar in pixels
UpButtonOffset: (size) offset in pixels from top left of the up button
DownButtonOffset: (size) offset in pixels from the bottom left of the down button
ThumbOffset: (size) offset in pixels from the top left of the thumb
ActiveZoneOffset: (size) size of the active zone outside the area of the scrollbar

ListBoxTemplate
This is the template for a list box. A list box is a multi-column multi-row control that shows a list of data. Examples of this are the additional info area of the character stats window and the icon list for a merchant's wares.
Name: (name) the name of this template
LinePadding: (number) blank rows of pixels between rows
CellPadding: (number) blank columns of pixels between columns
LabelLength: (number) number of characters per label
ScrollbarTemplate: (name) the name of the scrollbar template
ScrollbarTopOffset: (number) offset from the top of the list box to the scrollbar
ScrollbarBottomOffset: (number) offset from the bottom of the list box to the scrollbar
ScrollbarRightOffset: (number) offset from the right of the list box to the scrollbar
BackgroundTemplate: (name) background image (full resize image)
TextFont
Name: (name) name of the font
ColorNormal: (color) color of the font in normal mode
ColorHighlit: (color) color of the font in highlit mode
ColorGreyed: (color) color of the font in greyed mode
TextLeftOffset: (number) offset of the first column from the left
TextTopOffset: (number) offset of the first row from the top
TextBottomOffset:(number) offset of the last row from the bottom
LineOffset: (number) offset down in the row of the text

TextAreaTemplate
A text area is a multi-line text display. Text areas support the bracketed text in the Help Window and the NPC Interact Window. The active text is denoted with the active color specified in the template.
Name: (name) the name of this template
ScrollbarTemplate: (name) the name of the scrollbar template
LinePadding: (number) blank rows of pixels between rows
BackgroundTemplate: (name) the name of the background image (full resize image)
Font
Name: (name) name of the font asset
ColorNormal: (color) normal color of the text
ColorActive: (color) color of the active bracketed text
TextOffset: (size) offset both top and bottom of the text in the control
ScrollbarOffset: (point) offset from the top left corner of the scrollbar
ScrollbarSizeOffset: (point) added to the size of the scrollbar when resizing

StatusBarTemplate
A status bar is a horizontal bar indicator used for showing hit points, power, and other scalar data.
Name: (name) the name of this template
BackgroundHResizeTemplate: (name) the name of the background (empty) template ForegroundHResizeTemplate: (name) the name of the foreground (full) template
Height: (number) the height of the status bar in pixels
ForegroundOffset: (size) offset from the top left of the foreground image

ImageAreaTemplate
An image area is basically a decal drawn from a texture page.
Name: (name) the name of this template
TextureName: (name) the name of the texture asset
Size: (size) the size of the image in pixels
TopLeft: (texture coord) the location of the decal in the texture

StatusIconTemplate
A status icon is a statically-sized control that changes its appearance based on a scalar value. Examples of this are the power indicator on the Mini-Group Window and the Performance Meter. Status icons must have their frames next to each other in the texture and must go from lowest to highest. They can be arranged horizontally or vertically in the texture.
Name: (name) the name of this template
TextureName: (name) the name of the texture
Width: (number) width of the status icon in pixels
Height: (number) height of the status icon in pixels
MaxLevels: (number) number of frames in the status icon
Horizontal: (bool) true if the frames are arranged horizontally in the texture
TextureStart: (texture coord) location of the first frame in the texture

IconTemplate
An icon is a 16x16 or 32x32 image that is used to represent a spell, style, ability, or effect. Other sizes are not supported.
Name: (name) the name of this template
Size: (size) the size of this icon
FontName: (name) the name of the font
FontColor: (color) the color of the font
IconSize: (number) 0 if 16x16, 32x32 otherwise

ChatControlTemplate
The chat control makes the Chat Window work.
Name: (name) the name of this template
FontName: (name) the name of the font
BackgroundTemplate: (name) the name of the background template (full resize image)
ScrollbarTemplate: (name) the name of the scrollbar template

CheckBoxTemplate
A check box is an on or off button.
Name: (name) the name of this template
Size: (size) the size of the button area of the control in pixels
Font
Name: (name) the name of the font
ColorNormal: (color) normal color of the text
ColorPressed: (color) pressed color of the text
ColorHighlit: (color) highlit color of the text
ColorDisabled: (color) disabled color of the text
TextOffset: (size) offset of the text to the right of the button area
TextAlignment: (alignment) alignment of the text
ChangeFontColor: (bool) if true, the font color changes with the state
Texture
TexturName: (name) the name of the texture asset
Normal: (texture coord) location of the normal texture data
Pressed: (texture coord) location of the pressed texture data
NormalHighlit: (texture coord) location of the normal highlit texture data
PressedHighlit: (texture coord) location of the pressed highlit texture data
Disabled: (texture coord) location of the disabled texture data

VerticalStatusBarTemplate
A vertical status bar is a vertical version of the horizontal status bar used to show scalar data.
Name: (name) the name of this template
BackgroundImage: (name) the name of the background (empty) template ForegroundImage: (name) the name of the foreground (full) template
Width: (number) the width of the control in pixels
ForegroundOffset: (size) offset from the top left of the foreground image

CompassControlTemplate
This control works the compass. Note that the texture needs to be its own separate file with no dead space.
Name: (name) the name of this template
Texture: (name) the name of the texture

3.4 Control Definitions

This is a listing of every option in every control definition. This list is subject to change.

Every control definition shares the following attributes:
controlId: (id) an identifier for the control
position: (point) position relative to the top left corner of the parent window
alignment: (alignment) alignment of the control relative to the window

ButtonDef
templateName: (name) name of the template
label: (string) label on the button (if any)
onClickEvent: (event) event that fires when the button is not disabled and clicked

InvisibleButtonDef
Invisible buttons are buttons that have no visual components. These are used in places where only an active area is needed or where certain controls are not active and cannot generate an event to the window.
onClickEvent: (event) event that fires when the button is not disabled and clicked
width: (number) width of the control in pixels
height: (number) height of the control in pixels

ComboBoxDef
templateName: (name) name of the template
onChangeEvent: (event) name of the event generated when the selection changes
adapterName: (name) name of the adapter that the combo box reads from

ListBoxDef
templateName: (name) name of the template
adapterName: (name) name of the list box adapter this control uses
sorting: (bool) not used
columns: (number) number of columns supported by the list box
width: (number) width of the control in pixels
height: (number) height of the control in pixels

StaticFileImageDef
A static file image is an image that does not exist in a normal texture sheet. Static file images use an image file of unrestricted dimensions and displays the entire image. These controls are deprecated and not used by the ToA UI but may be useful in modding.
canvasName: (name) name of the canvas asset to use

StatusBarDef
The scalar adapter used by a status bar must have a range from 0 to 100.
templateName: (name) name of the template
adapterName: (name) name of the scalar adapter used by this control
width: (number) width of the control in pixels

LabelDef
Labels are single line text labels displaying string data. Note that labels cannot display scalar data. Use a scalar label for that.
fontName: (name) name of the font asset used by this label
adapter: (name) name of the text adapter used by this label
colorAdapter: (name) name of the color adapter used by this label
width: (number) width of the label in pixels
height: (number) height of the label in pixels
maxCharacters: (number) max number of characters the label can contain
color: (color) color used by this label if no color adapter is specified
data: (string) text displayed in this label unless a text adapter is specified
endAligned: (bool) true if the text should be right side aligned

FullResizeImageDef
templateName: (name) template used by this control
width: (number) width of the control in pixels
height: (number) height of the control in pixels

TextAreaDef
See the text area template description for more details on hotspots and active areas.
templateName: (name) template used by this control
adapterName: (name) text adapter used by this control
hasHotspots: (bool) true if the active areas on the text area should be lit
maxCharacters: (number) the max number of characters that the text area can hold
width: (number) width of the control in pixels
height: (number) height of the control in pixels

ImageAreaDef
templateName: (name) template used by this control

StatusIconDef
The scalar adapter used by a status icon must have a range from 0 to 100.
templateName: (name) template used by this control
adapterName: (name) scalar adapter used by this control

IconDef
iconId: (number) id of the icon to display if no scalar adapter is specified
data: (string) text to display
templateName: (name) template used by this control
adapterName: (name) scalar adapter for the id of the icon to display

ChatControlDef
Chat controls use one of two special chat adapters named 'chat' and 'system'.
templateName: (name) template used by this control
linePadding: (number) blank pixel rows between lines
bufferName: (name) name of the chat adapter
textOffset: (point) offset from the left column for where the text starts
width: (number) width of the control in pixels
height: (number) height of the control in pixels

HorizontalResizeImageDef
templateName: (name) template used by this control
width: (number) width of the control in pixels

CheckBoxDef
templateName: (name) template used by this control
adapterName: (name) scalar adapter used for the value (0 or 1 for off or on)
textAdapterName: (name) text adapter used for the label
data: (name) default data used for the label if no text adapter is specified
labelWidth: (name) max characters of storage for the label

VerticalStatusBarDef
Scalar adapters used for vertical status bar must have a range from 0 to 100.
templateName: (name) template used by this control
adapterName: (name) name of the scalar adapter used by this control
height: (number) height of the status bar in pixels

CompassControlDef
templateName: (name) template used by this control
adapterName: (name) scalar adapter used for heading
height: (number) height of the control in pixels
width: (number) width of the control in pixels

ScalarLabelDef
Scalar labels are single line text labels displaying a single number. Single line text data should be showing through a label.
fontName: (name) name of the font asset used for this label
adapter: (name) scalar adapter this control displays
colorAdapter: (name) color adapter for the text
width: (number) width of this control in pixels
height: (number) height of this control in pixels
maxCharacters: (number) max character storage for this control
color: (color) color of the string if no color adapter is specified
data: (string) default display for the label
endAligned: (bool) true if the text should be right side aligned

3.5 Window Templates

The following is a list of the options available in window templates and their purpose in game. This list is subject to change.

Windows are allowed to have any number and any combination of control definitions. Controls are drawn in order from first to last with the last drawn controls displaying on top. Window template tokens are not case sensitive.

Name
This is the name of the window. Names are typically all lowercase with words separated by underscores. These are what the interface uses to find the template data for a given window. These are not case sensitive.

CloseButton (bool)
This Boolean specifies whether the close button should be present or not. If this element is not present, the button is not present. The close button always goes into the upper right hand corner of the window.

MoveButton (bool)
This Boolean specifies whether the move button should be present or not. If this element is not present, the button is not present. The move button always goes into the upper left hand corner of the window.

TopRightResizeButton (bool)
This Boolean specifies whether the upper right resize button should be present or not. If this element is not present, the button is not present. The upper right resize button always goes into the upper right hand corner of the window. The close button and top right resize button cannot coexist peacefully.

BottomRightResizeButton (bool)
This Boolean specifies whether the bottom right resize button should be present or not. If this element is not present, the button is not present. The bottom right resize button always goes into the lower right hand corner of the window. This option supersedes resizeable two way width and height.

BottomLeftResizeButton (bool)
This Boolean specifies whether the bottom left resize button should be present or not. If this element is not present, the button is not present. The bottom left resize button always goes into the bottom left hand corner of the window. This option supersedes resizeable two way width and height.

ResizeButtonOffsetX (number)
This number specifies the X offset in pixels of the bottom left and bottom right resize buttons (but not the upper right resize button). For the bottom left resize button, the offset is from the left. For the bottom right resize button, the offset is from the right.

ResizeButtonOffsetY (number)
This number specifies the Y offset in pixels of the bottom left and bottom right resize buttons (but not the upper right resize button). For both buttons it is the offset from the bottom.

Width (number)
This is the width of the window in pixels.

Height (number)
This is the height of the window in pixels.

TitleWidth (number)
This is the width of the title area in pixels. The title area works the same way as the move button. If title area dragging is not desired, either the title height or title width can be set to 0 to disable the feature.

TitleHeight (number)
This is the height of the title area in pixels. The title area works the same way as the move button. If title area dragging is not desired, either the title height or title width can be set to 0 to disable the feature.

ResizeableWidth (number)
This is the width in pixels to make a window resizable in the X direction (i.e. left and right). Note that for the background to change width, it must have the alignment flag GrowWidth specified.

ResizeableHeight (number)
This is the height in pixels to make a window resizable in the Y direction (i.e. up and down). Note that for the background to change height, it must have the alignment flag GrowHeight specified.

ResizeableTwoWayWidth (number)
This number is the width in pixels of the corner areas that resize in two dimensions. This functionality has been replaced by the left and right bottom resize buttons.

ResizeableTwoWayHeight (number)
This number is the height in pixels of the corner areas that resize in two dimensions. This functionality ha been replaced by the left and right bottom resize buttons.

WindowId (id)
This is the window id. Many windows have constants for them but many do not. At the time of this writing, it is used only for debugging.

MinWidth (number)
This is the minimum width of a window in pixels. Strange visual errors can be had if the minimum width of a window is set too small. The minimum width of a window is computed as the minimum width of the most interior resize element plus the difference between the width of the window and the width of the element. A resize element in this case would be those controls that can resize horizontally (e.g. status bars and full resize images). The minimum width of a control that can be resized is the left width plus the right width.

MinHeight (number)
This is the minimum height of a window in pixels. Strange visual errors can be had if the minimum height of a window is set too small. The minimum height of a window is computed as the minimum height of the most interior resize element plus the difference between the height of the window and the height of the element. A resize element in this case would be those controls that can resize vertically (e.g. vertical scroll bars and full resize images). The minimum height of a control that can be resized is the top height plus the bottom height.

3.6 Event Reference

The following is a list of the events available in the ToA interface and their purpose in game. Many of these events require additional data that may not be settable by the UI. Where possible this is indicated in the comments. This list is subject to change.

Command Window Events
ToggleAttackMode Toggles player attack mode
Realm Shows the /realm display
Sprint Toggles sprint mode
ToggleSitting Toggles sitting mode
Task Toggles task display
Follow Toggles auto-follow mode
Stick Toggles auto-stick mode
Afk Toggles AFK mode
Face Toggles auto-face mode
Anon Toggles anon mode
Pray Issues the /pray command
Help Shows the Help Window
Release Issues the /release command
Relic Shows the /relic display
Bonuses Shows the /bonus display (resists)
ShowKeyboardConfig Shows the keyboard configuration display
Journal Shows the Quest Journal Window
Friends Shows the Mini-Friends Window
Bind Issues the /bind command
ToggleCompass Toggles compass mode between off, small, and large
Quit Issues the /quit command

Interact Window Events
Interact Issues an interact event given the clickedhotspot; requires extra data

Group and Mini-Group Window Events
SelectGroupMember0 Selects the group leader (first group member)
SelectGroupMember1 Selects the second group member
SelectGroupMember2 Selects the third group member
SelectGroupMember3 Selects the fourth group member
SelectGroupMember4 Selects the fifth group member
SelectGroupMember5 Selects the sixth group member
SelectGroupMember6 Selects the seventh group member
SelectGroupMember7 Selects the last group member (eighth)
GroupQuerySolo Sends a 'looking for group' query as a solo player to the server
GroupQueryGroup Sends a 'looking for group' query as a group leader to the server
GroupSoloSeeking Sets a solo player's 'looking for group' flag on the server
GroupSoloNotSeeking Removes a solo player's 'looking for group' flag on the server
GroupSeekingNone Sets a group's 'seeking members' flag to none
GroupSeekingAll Sets a group's 'seeking members' flag to all
GroupSeekingFighter Sets a group's 'seeking members' flag to fighter
GroupSeekingMage Sets a group's 'seeking members' flag to mage
GroupSeekingHealer Sets a group's 'seeking members' flag to healer
GroupSeekingRogue Sets a group's 'seeking members' flag to rogue
GroupInvite Issues the /invite command
GroupDisband Issues the /disband command

Mini-Craft Window Events
Repair Issues the /repair command
Craft Issues the /craft command
Salvage Issues the /salvage command

Concentration Window Events
RemoveConc Removes the specified concentration buff (requires the knowledge of which buff is selected)
ConcQuickDesc Displays the Mini-Info Window for a concentration buff (requires the knowledge of which buff is selected)

Train Window Events
Train Trains the selected skill or realm ability (requires the knowledge of which skill or realm ability is selected)
TrainInfo Gets info on the selected skill or realm ability (requires the knowledge of which skill or realm ability is selected)

Merchant Window Events
MerchantBuy Buys the selected item (requires the knowledge of which item is selected)
MerchantSell Sells the selected object from a player's inventory
MerchantAppraise Appraises the selected object from a player's inventory
MerchantQuickDesc Displays the Mini-Info Window for the currently selected merchant item (requires knowledge of which item is selected)

Chat Window Events
ChatChannelsChanged Issues a command to the server to filter chat channels

Siege Window Events
SiegeArm Issues a siege arm command
SiegeLoad Issues a siege load command (uses currently selected ammo in the Siege Window or the first one if none are selected)
SiegeAim Issues a siege aim command
SiegeFire Issues a siege fire command

Pet Window Events
PetSetMoveState Sets pet move state to the current state (requires knowledge of the current value)
PetSetCombatState Sets pet combat state to the current state (requires knowledge of the current state)
PetAttack Issues the attack command to the pet
PetRelease Issues the release pet command
PetTarget Issues the target pet command

Random Events
ShowWindow
HideWindow
ToggleWindow

3.7 Old Style Panel Texture Assets

The following is the listing of old style textures and the panel(s) that they are used on. The data used for the ToA versions of these panels is located in Atlantis/data/ and Atlantis/phousing/data/. List is subject to change.

vault.bmp Bank
dialog_sm.bmp Dialog
emblempick.bmp Emblem picker
npctalk.bmp Group picker (looking for group window), Help, Housing big dialog
leftbot.bmp Alpha picker, Value picker (coin, alpha), Housing interior rotation
options.bmp Options, Housing internal/external options, market query, market results, friend permissions, housing friend list
hbar_horz.bmp Quickbar
hbar_min.bmp Quickbar
hbar_vert.bmp Quickbar
pperdoll.bmp Inventory
hldbrite.bmp Inventory
sacks.bmp Inventory
magicsheet.bmp Spells
combstylesheet.bmp Styles
skillsheet.bmp Abilities
trade.bmp Trade
interact.bmp Tradeskills
edit_box.bmp Housing market query
garden.bmp Housing garden placement
consignment.bmp Housing player merchant
minipet.bmp Housing money selector
scrlbtns.bmp All old style scroll buttons
listicon1.bmp All old style checkboxes (located in Atlantis/data)
buttons.bmp Old style buttons
buttons2.bmp Old style buttons
buttons3.bmp Old style buttons



Final Note

If you have any problems with creating interface skins, please be aware that as with all our XML features, we do not provide personal assistance. We highly recommend that you not even attempt to make your own skin unless you already have the knowledge necessary to use the tools we provided.

If you encounter any bugs, please report them using the /appeal system (our XML User CSRs cannot help with custom UI questions or problems, and will not respond to any appeals on the topic, so please file a bug appeal only). Someone will look at the situation. You can also send a feedback form (user interface category).

full