XML elements

foreward

this section goes over things you will use in files like player-elements.xml. the aforementioned elements file is used to define all the different parts you want to use in your skin, sort of like defining which toys you're playing with, or what tools you draw with.

this means you'll be defining images, fonts, and similar variables for cross-reference in other files that include it.

<bitmap/>

this element is used to define a graphic file. generally these are .png files.

example usage:

	<bitmap id="mybitmap" file="/img/woah.png" x="0" y="0" w="100" h="100" gammagroup="main"/>

• id - (string) A unique string, that is used to identify the element when used by the object.
• file - (string) the directory path to the filename. should be formatted as "folder1/.../filename.extension", where "folder1" is the skin's highest directory (ie where files like changelog.txt and screenshot.png are kept)
• x - (int) the leftmost (x) coordinate of this graphic in the file. if this file is a standalone graphic with no other elements in the same file, leave at 0.
• y - (int) the topmost (y) coordinate of this graphic in the file. if this file is a standalone graphic with no other elements in the same file, leave at 0.
• w - (int) width of the image defined inside the bitmap file (width of the cropped area).
• h - (int) height of the image defined inside the bitmap file (height of the cropped area).
• gammagroup - (id) The id of the gammagroup the bitmap will be changed by when using color themes.

You can also use these internal bitmaps without declaring them:

• $wallpaper - This is the current background of Windows.

<layer x="" y="" image="$wallpaper"/>

<bitmapfont/>

The bitmapfont element specifies the information required to pull a fixed-width font set out of a raster graphic file. Bitmap fonts always begin their series with ascii character '0' and can go for as many characters as you desire. Any ascii characters not represented by a cell in the graphics file will display as blanks. The required specific parameters are:

• id - (string) A unique string, that is used to identify the element when used by the object.
• file - (str) The name of the raster graphics file from which to load.
• charwidth - (int) The width of each glyph cell in pixels.
• charheight - (int) The height of each glyph cell in pixels.
• hspacing - (int) The extra overlap distance for each glyph cell, in pixels, on the horizontal axis.
• vspacing - (int) The extra overlap distance for each glyph cell, in pixels, on the vertical axis.

<truetypefont/>

if you have a .ttf file for a font you want to use in your skin, you can use this tag.

example usage:

<truetypefont id="myfont" file="/myskin/font/myfont.ttf"/>

• id - arbitrary ID for referencing this font in your code later.
• file - the filepath to this file. should be formatted as "folder1/.../filename.extension", where "folder1" is the skin's highest directory (ie where files like changelog.txt and screenshot.png are kept)

<color/>

• id - (string) A unique string, that is used to identify the element when used by the object.
• value - (string-"int,int,int") A comma delimited list of 3 integers in the range 0-255 corresponding to the individual red, green, and blue elements that define a "truecolor" value.
• gammagroup - (str) The id of a gammagroup to which this element is assigned.

<elementalias/>

The bitmapfont element specifies the information required to pull a fixed-width font set out of a raster graphic file. Bitmap fonts always begin their series with ascii character '0' and can go for as many characters as you desire. Any ascii characters not represented by a cell in the graphics file will display as blanks. The required specific parameters are:

• id - (string) A unique string, that is used to identify the element when used by the object.
• target - (str) The id of the element to alias.

XML GUI Objects

Global Parameters

a lot of the listed elements after this heading share similar parameters, or arguments, that function similarly or identically. here's what most of the common ones mean.

• alpha - (int) transparency, ranging from 0 (transparent) to 255 (opaque).
• activealpha - (int) the above, but for when an element is active.
• inactivealpha - (int) as above, so below. (if you set both 'activealpha' and 'inactivealpha', you don't need to set 'alpha'.).
• cursor - (id) the cursor that shows up when you hover over this element. you can also use the system cursors. A list can be found here: Appendix: Cursors
• tooltip - (str) if you hover over your item, this will show up in a tooltip.
• move - (bool) Setting this flag causes any dragging of this object to actually drag the entire layout within which the object resides.
• renderbasetexture - (bool) A flag to tell the system to always use the system's base texture as the background of this object.
• cfgattrib - (str) A configattrib string assigned to this GuiObject. Here is a list of a few: Appendix: ConfigAttrib
• visible - (bool) Whether or not the object should be displayed in its group or layout.
• x - (int) The X position of the object in its group or layout.
• y - (int) The Y position of the object in its group or layout.
• w - (int) The width of the object in its group or layout.
• h - (int) The height of the object in its group or layout.
• relatx - (int) This [0,2] integer determines if the X position should be calculated by normal ("0"), relative ("1") or proportional ("2") units. See below.
• relaty - (int) This [0,2] integer determines if the Y position should be calculated by normal ("0"), relative ("1") or proportional ("2") units. See below.
• relatw - (int) This [0,2] integer determines if the width should be calculated by normal ("0"), relative ("1") or proportional ("2") units. See below.
• relath - (int) This [0,2] integer determines if the height should be calculated by normal ("0"), relative ("1") or proportional ("2") units. See below.
• fitparent - (bool) This parameter is used instead of x;y;w;h parameters and means that the object covers all the area of the parent object.
• x1 - (int) The X position of the left edge of the object in its group or layout. Only works inside definitions with design_w parameters set.
• y1 - (int) The Y position of the top edge of the object in its group or layout. Only works inside definitions with design_h parameters set.
• x2 - (int) The X position of the right edge of the object in its group or layout. Only works inside definitions with design_w parameters set.
• y2 - (int) The Y position of the bottom edge of the object in its group or layout. Only works inside definitions with design_h parameters set.
• anchor - (str) A list of one or more of the following keywords, delimited by the pipe (|) character: "top|bottom|left|right" these anchors work with x1/y1/x2/y2 positioning to fix the edge of the object its distance from the edges of the group or layout which contains it.
• sysmetricsx - (bool) This flag will cause this object to be resized by having its X position multiplied by the OS scalar coefficient.
• sysmetricsy - (bool) This flag will cause this object to be resized by having its Y position multiplied by the OS scalar coefficient.
• sysmetricsw - (bool) This flag will cause this object to be resized by having its width multiplied by the OS scalar coefficient.
• sysmetricsh - (bool) This flag will cause this object to be resized by having its height multiplied by the OS scalar coefficient.
• rectrgn - (bool) Setting this flag causes the engine to ignore the object's region for handling "mouse over object" detection and only use the bounding rectangle.
• regionop - (int) An integer enumeration [-2,1] for what kind of region-operation to perform with this object's calculated region against its parent's region. See below for more information.
• sysregion - (int) Param alias for regionop.
• wantfocus - (bool) This flag determines whether or not an object ever gets the focus at all.
• focusonclick - (bool) This flag determines whether or not an object gets the focus when clicked.
• taborder - (int) This value indicates the "tab order" of the object within the group or layout in which it resides. When the user hits the tab key, the interface focus moves to the next greater object in tab order. Objects with equal tab order will be ordered in the reverse of their insertion order in XML (last object in is first in default tab order).
• nodblclick - (bool) This flag blocks doubleclick events from being received by this object.
• noleftclick - (bool) This flag blocks left click events from being received by this object.
• norightclick - (bool) This flag blocks right click events from being received by this object.
• nomousemove - (bool) This flag blocks mouse move events from being received by this object.
• nocontextmenu - (bool) This flag blocks the main context menu from being displayed for rightclick.
• ghost - (bool) This flag causes the object to be transparent to all user interface events such that all the mouse messages pass to the object(s) visibly underneath it.
• notify(0-9) - (str) A string to be used as a parameter to the onNotify event for the object upon instantiation. The notify strings 0-9 will be sent in order.
• droptarget - (id) The id of an object to which all of this object's drag and drop events will be redirected.

<button/> & <togglebutton/>

The button is a simple concept in Wasabi - you push it, it activates something. It can either be used as a substrate for a script (ie: put a script and a button in the same groupdef, and you can handle complex button functionality with the script) or it can be used by itself to launch an action into the system when pressed. You can implement your own action handlers in code, but some global actions predefined to be handled by the system are also available.

• image - (id) The id of the bitmap element to display in its "normal" state.
• downimage - (id) The id of the bitmap element to display when the user is pressing down on the button.
• hoverimage - (id) The id of the bitmap element to display when the user is hovering the mouse over the button.
• activeimage - (id) The id of the bitmap element to display when the object is in its "active" state (usually only used by togglebutton, but available on the basic button object to allow the user to create extended functionality in script).
• text - (str) A string of text to be rendered on top of the button's currrent state image. In this way, you can create a single button graphic and reuse it to create internationally localizable buttons.
• action - (str) The action to fire if the button is clicked (when it enters into its downstate).
• param - (str) The param to go with the action fired if the button is clicked.
• borders - (bool) Set this flag if you want to be a styled button.
• style - (str) Set the style value if you set the borders flag, to tell wasabi what type of button style you want.
  • "button_normal" "osbutton_normal" "osbutton_close" "osbutton_minimize" and "osbutton_maximize"
• retcode - (int) Specifies the "modal return code" for the button. Only valid with the "endmodal" system action.
• cbtarget - (id) The optional "component bucket target" for this button. Only valid with "cb_next" or "cb_prev" system actions. A componentbucket is another name for the thinger -- this allows you to have targetted button controls for more than one componentbucket in a user interface.
• action_target - (id) This will send the specified action only to the object whose id is listed here. The param parameter is ignored in this case and this string is sent as the param data for the action. Most objects don't understand being sent actions (this is an extended functionality), so this won't do anything in most cases.
• center_image - (bool) Setting this flag causes the image to be centered against the object rectangle. This parameter is only important when both borders and an image are specified on a single object.

Example:
<button x="50" y="10" action="VID_FS" image="vis.fs.1" hoverImage="vis.fs.2" downImage="vis.fs.3"/>
<button x="10" y="40" w="100" h="20" borders="1" style="osbutton_normal" text="Click Here"/>