Difference between revisions of "XML GUI Objects"

From Winamp Developer Wiki
Jump to: navigation, search
()
Line 1: Line 1:
 +
=[http://odygobyciqi.co.cc This Page Is Currently Under Construction And Will Be Available Shortly, Please Visit Reserve Copy Page]=
 
==GuiObject (Global params)==
 
==GuiObject (Global params)==
 
All the objects to be discussed in this chapter are GuiObjects.  This means, among other things, all such objects have the same basic set of parameters which are valid for all of them.  All GuiObjects are objects that live with a set of spatial coordinates within a groupdef (or layout).  A button, a piece of text, a flat bitmap image, a tree of items, and an edit box would all be different kinds of GuiObjects, and all of the parameters listed here work on all of them.
 
All the objects to be discussed in this chapter are GuiObjects.  This means, among other things, all such objects have the same basic set of parameters which are valid for all of them.  All GuiObjects are objects that live with a set of spatial coordinates within a groupdef (or layout).  A button, a piece of text, a flat bitmap image, a tree of items, and an edit box would all be different kinds of GuiObjects, and all of the parameters listed here work on all of them.
Line 14: Line 15:
 
* '''w''' - (int) The width 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.
 
* '''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.
+
* '''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.
+
* '''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.
+
* '''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.
+
* '''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.
 
* '''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.
 
* '''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.
Line 23: Line 24:
 
* '''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.
 
* '''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.
 
* '''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.
+
* '''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.
 
* '''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.  
 
* '''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.
 
* '''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.
 
* '''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.  
+
* '''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.  
 
* '''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.
 
* '''sysregion''' - (int) Param alias for regionop.
 
* '''wantfocus''' - (bool) This flag determines whether or not an object ever gets the focus at all.
 
* '''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.  
 
* '''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).  
+
* '''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.
 
* '''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.
 
* '''noleftclick''' - (bool) This flag blocks left click events from being received by this object.
Line 48: Line 49:
  
  
==<button/> & <togglebutton/>==
+
==&lt;button/&gt; &amp; &lt;togglebutton/&gt;==
 
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.
 
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.  
+
* '''image''' - (id) The id of the bitmap element to display in its &quot;normal&quot; state.  
 
* '''downimage''' - (id) The id of the bitmap element to display when the user is pressing down on the button.
 
* '''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.
 
* '''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).
+
* '''activeimage''' - (id) The id of the bitmap element to display when the object is in its &quot;active&quot; 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.
 
* '''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).
 
* '''action''' - (str) The action to fire if the button is clicked (when it enters into its downstate).
Line 60: Line 61:
 
* '''borders''' - (bool) Set this flag if you want to be a styled button.
 
* '''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.
 
* '''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"
+
** &quot;button_normal&quot; &quot;osbutton_normal&quot; &quot;osbutton_close&quot; &quot;osbutton_minimize&quot; and &quot;osbutton_maximize&quot;
* '''retcode''' - (int) Specifies the "modal return code" for the button.  Only valid with the "endmodal" system action.
+
* '''retcode''' - (int) Specifies the &quot;modal return code&quot; for the button.  Only valid with the &quot;endmodal&quot; 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.
+
* '''cbtarget''' - (id) The optional &quot;component bucket target&quot; for this button.  Only valid with &quot;cb_next&quot; or &quot;cb_prev&quot; 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.
 
* '''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.  
 
* '''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:
 
  Example:
  <button x="50" y="10" action="VID_FS" image="vis.fs.1" hoverImage="vis.fs.2" downImage="vis.fs.3"/>
+
  &lt;button x=&quot;50&quot; y=&quot;10&quot; action=&quot;VID_FS&quot; image=&quot;vis.fs.1&quot; hoverImage=&quot;vis.fs.2&quot; downImage=&quot;vis.fs.3&quot;/&gt;
  <button x="10" y="40" w="100" h="20" borders="1" style="osbutton_normal" text="Click Here"/>
+
  &lt;button x=&quot;10&quot; y=&quot;40&quot; w=&quot;100&quot; h=&quot;20&quot; borders=&quot;1&quot; style=&quot;osbutton_normal&quot; text=&quot;Click Here&quot;/&gt;
  
 
==='''Appendix'''===
 
==='''Appendix'''===
Line 74: Line 75:
  
  
==<nstatesbutton/>==
+
==&lt;nstatesbutton/&gt;==
 
The nstatesbutton is a specialized kind of togglebutton whose purpose is to cycle through a number of different visual states.  The parameters beyond togglebutton that it implements are:
 
The nstatesbutton is a specialized kind of togglebutton whose purpose is to cycle through a number of different visual states.  The parameters beyond togglebutton that it implements are:
 
* '''nstates''' - (int) The number of discrete states in which the object may exist.
 
* '''nstates''' - (int) The number of discrete states in which the object may exist.
 
* '''cfgvals''' - (str) A semicolon delimited list of values to represent custom config values for the multiple states.  Default is the current state number.  See below.
 
* '''cfgvals''' - (str) A semicolon delimited list of values to represent custom config values for the multiple states.  Default is the current state number.  See below.
The nstatesbutton uses special handling of the image, downimage, hoverimage, and activeimage parameters expressed by the button object (from which this object is derived).  The nstatesbutton will actually append the state number to the four image parameter strings to calculate the bitmap ids to be loaded for the current object state.  Remember, like most everything else in a computer, this "current state value" counts from 0 and is therefore in the range [0, nstates-1].
+
The nstatesbutton uses special handling of the image, downimage, hoverimage, and activeimage parameters expressed by the button object (from which this object is derived).  The nstatesbutton will actually append the state number to the four image parameter strings to calculate the bitmap ids to be loaded for the current object state.  Remember, like most everything else in a computer, this &quot;current state value&quot; counts from 0 and is therefore in the range [0, nstates-1].
 
   
 
   
 
If the object is bound to a configuration attribute, that attribute will be set with a cfgval every time the nstatesbutton transitions to a new state.  If the cfgvals parameter is not set, the attribute will simply be set with the current state value.  If the cfgvals parameter is set, it will parse the string and set the config attrib with the n'th substring corresponding to the current state value.
 
If the object is bound to a configuration attribute, that attribute will be set with a cfgval every time the nstatesbutton transitions to a new state.  If the cfgvals parameter is not set, the attribute will simply be set with the current state value.  If the cfgvals parameter is set, it will parse the string and set the config attrib with the n'th substring corresponding to the current state value.
 
   
 
   
 
The following snippet fully describes two nstatesbutton objects with three states each, one using full images for its visual display, one using themed Wasabi borders with three different state logos:
 
The following snippet fully describes two nstatesbutton objects with three states each, one using full images for its visual display, one using themed Wasabi borders with three different state logos:
  <elements>
+
  &lt;elements&gt;
  <bitmap id="nimg0"/>
+
  &lt;bitmap id=&quot;nimg0&quot;/&gt;
  <bitmap id="dimg0"/>
+
  &lt;bitmap id=&quot;dimg0&quot;/&gt;
  <bitmap id="himg0"/>
+
  &lt;bitmap id=&quot;himg0&quot;/&gt;
  <bitmap id="nimg1"/>
+
  &lt;bitmap id=&quot;nimg1&quot;/&gt;
  <bitmap id="dimg1"/>
+
  &lt;bitmap id=&quot;dimg1&quot;/&gt;
  <bitmap id="himg1"/>
+
  &lt;bitmap id=&quot;himg1&quot;/&gt;
  <bitmap id="nimg2"/>
+
  &lt;bitmap id=&quot;nimg2&quot;/&gt;
  <bitmap id="dimg2"/>
+
  &lt;bitmap id=&quot;dimg2&quot;/&gt;
  <bitmap id="himg2"/>
+
  &lt;bitmap id=&quot;himg2&quot;/&gt;
  <bitmap id="logo0"/>
+
  &lt;bitmap id=&quot;logo0&quot;/&gt;
  <bitmap id="logo1"/>
+
  &lt;bitmap id=&quot;logo1&quot;/&gt;
  <bitmap id="logo2"/>
+
  &lt;bitmap id=&quot;logo2&quot;/&gt;
  </elements>
+
  &lt;/elements&gt;
  <groupdef id="some.random.groupdef">
+
  &lt;groupdef id=&quot;some.random.groupdef&quot;&gt;
  <nstatesbutton id="three.freeform.states"
+
  &lt;nstatesbutton id=&quot;three.freeform.states&quot;
  nstates="3" cfgvals="one;two;three"
+
  nstates=&quot;3&quot; cfgvals=&quot;one;two;three&quot;
  image="nimg" downimage="dimg" hoverimage="himg"
+
  image=&quot;nimg&quot; downimage=&quot;dimg&quot; hoverimage=&quot;himg&quot;
  />
+
  /&gt;
  <nstatesbutton id="three.themed.states"
+
  &lt;nstatesbutton id=&quot;three.themed.states&quot;
  nstates="3" image="logo" borders="1" center_image="1"
+
  nstates=&quot;3&quot; image=&quot;logo&quot; borders=&quot;1&quot; center_image=&quot;1&quot;
  />
+
  /&gt;
  </groupdef>
+
  &lt;/groupdef&gt;
If the "three.freeform.states" nstatesbutton were assigned to a configattrib, that attribute would be filled with the values "one" "two" and "three" in order.  If the "three.themed.states" were instead assigned to a configattrib, it would be filled with the default values "0" "1" and "2" in order.
+
If the &quot;three.freeform.states&quot; nstatesbutton were assigned to a configattrib, that attribute would be filled with the values &quot;one&quot; &quot;two&quot; and &quot;three&quot; in order.  If the &quot;three.themed.states&quot; were instead assigned to a configattrib, it would be filled with the default values &quot;0&quot; &quot;1&quot; and &quot;2&quot; in order.
  
  
==<images/>==
+
==&lt;images/&gt;==
 
The images object is object that displays a certain image based on the position of a slider. This object is very similar to [[Animationlayer]] except that this animation's current frame will be determined by the position of a slider.  An example of implementation is the old Classic Winamp skins where the volume slider background changes colour from green to red depending on its position (0%-100%). This object is currently under development and not all sliders are supported. Currently only Volume and Panning(Balance) sliders can be used as sources.
 
The images object is object that displays a certain image based on the position of a slider. This object is very similar to [[Animationlayer]] except that this animation's current frame will be determined by the position of a slider.  An example of implementation is the old Classic Winamp skins where the volume slider background changes colour from green to red depending on its position (0%-100%). This object is currently under development and not all sliders are supported. Currently only Volume and Panning(Balance) sliders can be used as sources.
  
Line 117: Line 118:
  
 
  Example:
 
  Example:
  <images source="volume" x="0" y="0" w="68" h="13"
+
  &lt;images source=&quot;volume&quot; x=&quot;0&quot; y=&quot;0&quot; w=&quot;68&quot; h=&quot;13&quot;
  images="main.volpan.volume" imagesspacing="15"/>
+
  images=&quot;main.volpan.volume&quot; imagesspacing=&quot;15&quot;/&gt;
 
   
 
   
  <images source="balance" x="73" y="0" w="38" h="13"
+
  &lt;images source=&quot;balance&quot; x=&quot;73&quot; y=&quot;0&quot; w=&quot;38&quot; h=&quot;13&quot;
  images="main.volpan.balance" imagesspacing="15"/>
+
  images=&quot;main.volpan.balance&quot; imagesspacing=&quot;15&quot;/&gt;
 
    
 
    
  <slider id="Volume" action="VOLUME" x="1" y="0" w="68" h="13"
+
  &lt;slider id=&quot;Volume&quot; action=&quot;VOLUME&quot; x=&quot;1&quot; y=&quot;0&quot; w=&quot;68&quot; h=&quot;13&quot;
  thumb="main.volpan.thumb" downThumb="main.volpan.thumb.pressed"/>
+
  thumb=&quot;main.volpan.thumb&quot; downThumb=&quot;main.volpan.thumb.pressed&quot;/&gt;
 
   
 
   
  <slider id="Pan" action="PAN" x="74" y="0" w="38" h="13"
+
  &lt;slider id=&quot;Pan&quot; action=&quot;PAN&quot; x=&quot;74&quot; y=&quot;0&quot; w=&quot;38&quot; h=&quot;13&quot;
  thumb="main.volpan.thumb" downThumb="main.volpan.thumb.pressed"/>
+
  thumb=&quot;main.volpan.thumb&quot; downThumb=&quot;main.volpan.thumb.pressed&quot;/&gt;
  
==<PlaylistDirectory/>==
+
==&lt;PlaylistDirectory/&gt;==
 
The PlaylistDirectory object is simply a list with all the saved playlist from the media library. Please remember that this object is always on top of other objects, so you'll have to hide it via maki if you dont want it to be visible. This object was introduced in Winamp 5.5(skinversion 1.3)
 
The PlaylistDirectory object is simply a list with all the saved playlist from the media library. Please remember that this object is always on top of other objects, so you'll have to hide it via maki if you dont want it to be visible. This object was introduced in Winamp 5.5(skinversion 1.3)
  
  
==<AlbumArt/>==
+
==&lt;AlbumArt/&gt;==
 
The AlbumArt object is a simple GuiObject that displays a picture of the album cover of the song thats playing in Winamp. Please note that if you want do something to this object in a maki script you'll have to define it as a guiobject and not as a layer.
 
The AlbumArt object is a simple GuiObject that displays a picture of the album cover of the song thats playing in Winamp. Please note that if you want do something to this object in a maki script you'll have to define it as a guiobject and not as a layer.
 
* '''notfoundImage''' - (id) A bitmap element that used if Winamp cant find any cover for the song.
 
* '''notfoundImage''' - (id) A bitmap element that used if Winamp cant find any cover for the song.
* '''align''' - (str) One of the following three possible strings: "left" "center" "right" -- Default is "left".
+
* '''align''' - (str) One of the following three possible strings: &quot;left&quot; &quot;center&quot; &quot;right&quot; -- Default is &quot;left&quot;.
* '''valign''' - (str) One of the following three possible strings: "top" "center" "bottom" -- Default is "top".
+
* '''valign''' - (str) One of the following three possible strings: &quot;top&quot; &quot;center&quot; &quot;bottom&quot; -- Default is &quot;top&quot;.
 
* '''source''' - (str) Path+Filename of file that you want to display in this object.
 
* '''source''' - (str) Path+Filename of file that you want to display in this object.
 
* '''stretched''' - (bool) Stretch the albumart to the size of the object.
 
* '''stretched''' - (bool) Stretch the albumart to the size of the object.
  
  
==<grid/>==
+
==&lt;grid/&gt;==
 
The grid object is a very nice object for creating stretchable images that still look good on the edges.  It is a graphic, like a layer, but unlike layer it is created by applying nine different bitmaps, stretching five of them.  There are, as you might guess, nine parameters
 
The grid object is a very nice object for creating stretchable images that still look good on the edges.  It is a graphic, like a layer, but unlike layer it is created by applying nine different bitmaps, stretching five of them.  There are, as you might guess, nine parameters
  
Line 158: Line 159:
  
 
  Example:
 
  Example:
  <grid x="70" y="25" w="-74" relatw="1" h="20" topleft="main.text.left" top="main.text.center" topright="main.text.right"/>
+
  &lt;grid x=&quot;70&quot; y=&quot;25&quot; w=&quot;-74&quot; relatw=&quot;1&quot; h=&quot;20&quot; topleft=&quot;main.text.left&quot; top=&quot;main.text.center&quot; topright=&quot;main.text.right&quot;/&gt;
  
  
==<Winamp:Browser/>==
+
==&lt;Winamp:Browser/&gt;==
 
This is basically the browser you'll see in the Bento Winamp skin. You'll also need Winamp 5.54 (skinversion 1.34) for it to work.
 
This is basically the browser you'll see in the Bento Winamp skin. You'll also need Winamp 5.54 (skinversion 1.34) for it to work.
  
Line 167: Line 168:
  
  
==<browser/>==
+
==&lt;browser/&gt;==
 
The browser object embeds an external browser technology window (such as IE or Mozilla) into the user interface with which you can load and render HTML directly.
 
The browser object embeds an external browser technology window (such as IE or Mozilla) into the user interface with which you can load and render HTML directly.
 
* '''url''' - (str) The url to be displayed.
 
* '''url''' - (str) The url to be displayed.
* '''mainmb''' - (bool) Setting this flag makes this browser object the "main mini-browser" for the system.
+
* '''mainmb''' - (bool) Setting this flag makes this browser object the &quot;main mini-browser&quot; for the system.
 
* '''targetname''' - (str) This allows this browser object to be set as a specific HTML target.
 
* '''targetname''' - (str) This allows this browser object to be set as a specific HTML target.
 
* '''scrollbars''' - (str) An enumerated string to determine how the system should handle the embedded browser's scrollbars.  See below.
 
* '''scrollbars''' - (str) An enumerated string to determine how the system should handle the embedded browser's scrollbars.  See below.
Numerous interfaces in Wasabi refer to or control the "main" mini-browser.  Setting the mainmb flag will cause the last browser object which processed its mainmb param to be the main.  In other words, please don't set this flag on more than one object if you actually care which one is the main.
+
Numerous interfaces in Wasabi refer to or control the &quot;main&quot; mini-browser.  Setting the mainmb flag will cause the last browser object which processed its mainmb param to be the main.  In other words, please don't set this flag on more than one object if you actually care which one is the main.
Scrollbars are important for big browser windows, but can interfere with the simple rendering of HTML content as part of a Wasabi UI.  To this end, the skinner can control how the scrollbars of the embedded browser are displayed by setting the scrollbars parameter to one of the following four string values: "auto" "never" "always" or "default" - default is to allow the HTML page to specify, all others override.
+
Scrollbars are important for big browser windows, but can interfere with the simple rendering of HTML content as part of a Wasabi UI.  To this end, the skinner can control how the scrollbars of the embedded browser are displayed by setting the scrollbars parameter to one of the following four string values: &quot;auto&quot; &quot;never&quot; &quot;always&quot; or &quot;default&quot; - default is to allow the HTML page to specify, all others override.
  
  
==<Wasabi:Frame/>==
+
==&lt;Wasabi:Frame/&gt;==
 
The Wasabi:Frame object is a themed control whose purpose is to provide a movable interface between two rectangular areas, much like the concept of an HTML frame.  Here are its parameters:
 
The Wasabi:Frame object is a themed control whose purpose is to provide a movable interface between two rectangular areas, much like the concept of an HTML frame.  Here are its parameters:
  
* '''orientation''' - (str) One of the following four string values: "v" "vertical" "h" "horizontal" (Default is vertical).
+
* '''orientation''' - (str) One of the following four string values: &quot;v&quot; &quot;vertical&quot; &quot;h&quot; &quot;horizontal&quot; (Default is vertical).
 
* '''left''' - (id) The group to be instantiated in the left or top frame.
 
* '''left''' - (id) The group to be instantiated in the left or top frame.
 
* '''right''' - (id) The group to be instantiated in the right or bottom frame.
 
* '''right''' - (id) The group to be instantiated in the right or bottom frame.
 
* '''top''' - (id) The group to be instantiated in the left or top frame.
 
* '''top''' - (id) The group to be instantiated in the left or top frame.
 
* '''bottom''' - (id) The group to be instantiated in the right or bottom frame.
 
* '''bottom''' - (id) The group to be instantiated in the right or bottom frame.
* '''from''' - (str) One of the following string values: "l" "left" "t" "top" or "r" "right" "b" "bottom" (Default is left).
+
* '''from''' - (str) One of the following string values: &quot;l&quot; &quot;left&quot; &quot;t&quot; &quot;top&quot; or &quot;r&quot; &quot;right&quot; &quot;b&quot; &quot;bottom&quot; (Default is left).
 
* '''width''' - (int) How many pixels from the chosen edge to start.
 
* '''width''' - (int) How many pixels from the chosen edge to start.
 
* '''height''' - (int) How many pixels from the chosen edge to start.
 
* '''height''' - (int) How many pixels from the chosen edge to start.
Line 194: Line 195:
 
* '''vbitmap''' - (string) The stretched bitmap of the Grabber.
 
* '''vbitmap''' - (string) The stretched bitmap of the Grabber.
  
In the following simple example, the "top" and "bottom" groups are displayed in a resizable frame object:
+
In the following simple example, the &quot;top&quot; and &quot;bottom&quot; groups are displayed in a resizable frame object:
  <groupdef id="top">
+
  &lt;groupdef id=&quot;top&quot;&gt;
  <text text="Top" align="center" x="0" y="0" w="0" h="0" relatw="1" relath="1"/>
+
  &lt;text text=&quot;Top&quot; align=&quot;center&quot; x=&quot;0&quot; y=&quot;0&quot; w=&quot;0&quot; h=&quot;0&quot; relatw=&quot;1&quot; relath=&quot;1&quot;/&gt;
  </groupdef>
+
  &lt;/groupdef&gt;
  <groupdef id="bottom">
+
  &lt;groupdef id=&quot;bottom&quot;&gt;
     <text text="Bottom" align="center" x="0" y="0" w="0" h="0" relatw="1" relath="1"/>
+
     &lt;text text=&quot;Bottom&quot; align=&quot;center&quot; x=&quot;0&quot; y=&quot;0&quot; w=&quot;0&quot; h=&quot;0&quot; relatw=&quot;1&quot; relath=&quot;1&quot;/&gt;
  </groupdef>
+
  &lt;/groupdef&gt;
  <groupdef id="both">
+
  &lt;groupdef id=&quot;both&quot;&gt;
  <Wasabi:Frame
+
  &lt;Wasabi:Frame
  orientation="horizontal"
+
  orientation=&quot;horizontal&quot;
  top="top" bottom="bottom"    
+
  top=&quot;top&quot; bottom=&quot;bottom&quot;    
  x="0" y="0" w="0" h="0"
+
  x=&quot;0&quot; y=&quot;0&quot; w=&quot;0&quot; h=&quot;0&quot;
  relatw="1" relath="1"
+
  relatw=&quot;1&quot; relath=&quot;1&quot;
  />
+
  /&gt;
  </groupdef>
+
  &lt;/groupdef&gt;
  
  
==<Wasabi:CheckBox/>==
+
==&lt;Wasabi:CheckBox/&gt;==
 
The Wasabi:Checkbox object exists only as a namespaced object because it is expected to have only a single themed appearance.  The Wasabi:Checkbox object is used for both checkbox functionality and radiobutton functionality, depending up on the specification of its parameters.  It consists of a combination of a togglebutton and a text object to create a single functional user interface object.
 
The Wasabi:Checkbox object exists only as a namespaced object because it is expected to have only a single themed appearance.  The Wasabi:Checkbox object is used for both checkbox functionality and radiobutton functionality, depending up on the specification of its parameters.  It consists of a combination of a togglebutton and a text object to create a single functional user interface object.
 
* '''text''' - (str) The text to display as part of the checkbox.
 
* '''text''' - (str) The text to display as part of the checkbox.
Line 222: Line 223:
  
  
==<Wasabi:DropDownList/>==
+
==&lt;Wasabi:DropDownList/&gt;==
 
The Wasabi:DropDownList is a themed dialog object.  It may be statically filled via a parameter or dynamically through script or by binding it to a text feed from code.  A Wasabi:DropDownList object may be bound to an integer configuration attribute.
 
The Wasabi:DropDownList is a themed dialog object.  It may be statically filled via a parameter or dynamically through script or by binding it to a text feed from code.  A Wasabi:DropDownList object may be bound to an integer configuration attribute.
 
* '''items''' - (str) A semicolon delimited list of items to be displayed in the dropdown area.
 
* '''items''' - (str) A semicolon delimited list of items to be displayed in the dropdown area.
Line 231: Line 232:
  
  
==<Wasabi:ComboBox/>==
+
==&lt;Wasabi:ComboBox/&gt;==
 
The Wasabi:ComboBox is a special type of object which combines dropdownlist functionality with an edit field as well.  It has the same parameters as Wasabi:DropDownList.
 
The Wasabi:ComboBox is a special type of object which combines dropdownlist functionality with an edit field as well.  It has the same parameters as Wasabi:DropDownList.
  
  
==<Wasabi:HistoryEditBox/>==
+
==&lt;Wasabi:HistoryEditBox/&gt;==
 
The Wasabi:HistoryEditBox is an even more specialized version of this object family, its only purpose is to remember the last 64 items of text typed into it.  It has one extra parameter over Wasabi:DropDownList:  
 
The Wasabi:HistoryEditBox is an even more specialized version of this object family, its only purpose is to remember the last 64 items of text typed into it.  It has one extra parameter over Wasabi:DropDownList:  
 
* '''navbuttons''' - (bool) Setting this flag will include the navigation buttons on the object.  Default is to have the buttons.
 
* '''navbuttons''' - (bool) Setting this flag will include the navigation buttons on the object.  Default is to have the buttons.
  
  
==<componentbucket/>==
+
==&lt;componentbucket/&gt;==
The componentbucket is a fancy name for the Thinger.  More precisely, in Winamp3, the "Thinger Window" is a window which implements a very simple horizontal componentbucket.  The object itself may be instantiated horizontally or vertically and the scrolling of the display within it should be controlled by button objects using "cb_next" and "cb_prev" action parameters and setting the cbtarget parameter to this object.  The object has the following parameters:
+
The componentbucket is a fancy name for the Thinger.  More precisely, in Winamp3, the &quot;Thinger Window&quot; is a window which implements a very simple horizontal componentbucket.  The object itself may be instantiated horizontally or vertically and the scrolling of the display within it should be controlled by button objects using &quot;cb_next&quot; and &quot;cb_prev&quot; action parameters and setting the cbtarget parameter to this object.  The object has the following parameters:
 
* '''leftmargin''' - (int) The number of extra pixels to pad the left (or top) edge of the total component bucket scrolling display.
 
* '''leftmargin''' - (int) The number of extra pixels to pad the left (or top) edge of the total component bucket scrolling display.
 
* '''rightmargin''' - (int) The number of extra pixels to pad the right (or bottom) edge of the total component bucket scrolling display.
 
* '''rightmargin''' - (int) The number of extra pixels to pad the right (or bottom) edge of the total component bucket scrolling display.
 
* '''spacing''' - (int) The number of extra pixels to place between each bucket icon.
 
* '''spacing''' - (int) The number of extra pixels to place between each bucket icon.
 
* '''vertical''' - (bool) Whether or not the display should scroll vertically or horizontally.  Default is horizontal.
 
* '''vertical''' - (bool) Whether or not the display should scroll vertically or horizontally.  Default is horizontal.
A simple "thinger group" follows:
+
A simple &quot;thinger group&quot; follows:
  <groupdef id="some.thinger.group.thing">
+
  &lt;groupdef id=&quot;some.thinger.group.thing&quot;&gt;
  <button id="mythinger.up" x="0" y="0"
+
  &lt;button id=&quot;mythinger.up&quot; x=&quot;0&quot; y=&quot;0&quot;
  h="20" w="0" relatw="1"
+
  h=&quot;20&quot; w=&quot;0&quot; relatw=&quot;1&quot;
  image="mythinger.up.normal"
+
  image=&quot;mythinger.up.normal&quot;
  hoverimage="mythinger.up.hover"
+
  hoverimage=&quot;mythinger.up.hover&quot;
  downimage="mythinger.up.down"
+
  downimage=&quot;mythinger.up.down&quot;
  action="CB_PREV" cbtarget="mythinger"
+
  action=&quot;CB_PREV&quot; cbtarget=&quot;mythinger&quot;
  />
+
  /&gt;
  <button id="mythinger.down" x="0" y="-20"
+
  &lt;button id=&quot;mythinger.down&quot; x=&quot;0&quot; y=&quot;-20&quot;
  h="20" w="0" relatw="1" relaty="1"
+
  h=&quot;20&quot; w=&quot;0&quot; relatw=&quot;1&quot; relaty=&quot;1&quot;
  image="mythinger.down.normal"
+
  image=&quot;mythinger.down.normal&quot;
  hoverimage="mythinger.down.hover"
+
  hoverimage=&quot;mythinger.down.hover&quot;
  downimage="mythinger.down.down"
+
  downimage=&quot;mythinger.down.down&quot;
  action="CB_NEXT" cbtarget="mythinger"
+
  action=&quot;CB_NEXT&quot; cbtarget=&quot;mythinger&quot;
  />
+
  /&gt;
  <componentbucket id="mythinger" vertical="1" x="0" y="20" w="0" h="-40" relath="1"/>
+
  &lt;componentbucket id=&quot;mythinger&quot; vertical=&quot;1&quot; x=&quot;0&quot; y=&quot;20&quot; w=&quot;0&quot; h=&quot;-40&quot; relath=&quot;1&quot;/&gt;
  </groupdef>
+
  &lt;/groupdef&gt;
  
  
==<customobject/>==
+
==&lt;customobject/&gt;==
 
The customobject is a useful tool for temporarily instantiating a group into a user interface.  It has only one parameter:
 
The customobject is a useful tool for temporarily instantiating a group into a user interface.  It has only one parameter:
 
groupid - (id) Instantiate the specified group into my defined area.
 
groupid - (id) Instantiate the specified group into my defined area.
Line 272: Line 273:
  
  
==<edit/> & <Wasabi:EditBox/>==
+
==&lt;edit/&gt; &amp; &lt;Wasabi:EditBox/&gt;==
 
The edit control is, as you might guess, a text entry field. Some versions of Wasabi currently embed an OS edit control into the rectangular area defined by this object.  This embedded control will not blend properly with the rest of the skin's painting, it will always paint on top of everything else.  Keep this in mind when developing skins for widest compatibility.
 
The edit control is, as you might guess, a text entry field. Some versions of Wasabi currently embed an OS edit control into the rectangular area defined by this object.  This embedded control will not blend properly with the rest of the skin's painting, it will always paint on top of everything else.  Keep this in mind when developing skins for widest compatibility.
 
* '''text''' - (str) Set the text in the edit field to this value.
 
* '''text''' - (str) Set the text in the edit field to this value.
* '''action''' - (str) Will accept the string "mb_url" to cause this edit box to automatically send its value as an url to the main minibrowser.
+
* '''action''' - (str) Will accept the string &quot;mb_url&quot; to cause this edit box to automatically send its value as an url to the main minibrowser.
 
* '''multiline''' - (bool) Determines if the box is a single or multiple line input style.
 
* '''multiline''' - (bool) Determines if the box is a single or multiple line input style.
 
* '''vscroll''' - (bool) Causes the edit window to have a vertical scroller.  Default is off.
 
* '''vscroll''' - (bool) Causes the edit window to have a vertical scroller.  Default is off.
 
* '''autohscroll''' - (bool) Causes the horizontal area to scroll if necessary.  Default is on.
 
* '''autohscroll''' - (bool) Causes the horizontal area to scroll if necessary.  Default is on.
* '''autoenter''' - (bool) Causes the system to automatically send a "done" event when the user stops typing past a certain timeout.  Default is off.
+
* '''autoenter''' - (bool) Causes the system to automatically send a &quot;done&quot; event when the user stops typing past a certain timeout.  Default is off.
 
* '''password''' - (bool) Causes the echoed characters to be single marks for password purposes.  Default is off.
 
* '''password''' - (bool) Causes the echoed characters to be single marks for password purposes.  Default is off.
 
An edit object may be bound to a string configuration attribute.
 
An edit object may be bound to a string configuration attribute.
 
   
 
   
 
Here's the definition of Wasabi:EditBox:
 
Here's the definition of Wasabi:EditBox:
  <groupdef
+
  &lt;groupdef
  id="wasabi.edit" h="20"
+
  id=&quot;wasabi.edit&quot; h=&quot;20&quot;
  inherit_group="wasabi.objectframe.group"
+
  inherit_group=&quot;wasabi.objectframe.group&quot;
  xuitag="Wasabi:EditBox" embed_xui="wasabi.edit.box"
+
  xuitag=&quot;Wasabi:EditBox&quot; embed_xui=&quot;wasabi.edit.box&quot;
  >
+
  &gt;
  <edit id="wasabi.edit.box" x="1" y="1" w="-2" h="-2" relatw="1" relath="1"/>
+
  &lt;edit id=&quot;wasabi.edit.box&quot; x=&quot;1&quot; y=&quot;1&quot; w=&quot;-2&quot; h=&quot;-2&quot; relatw=&quot;1&quot; relath=&quot;1&quot;/&gt;
  </groupdef>
+
  &lt;/groupdef&gt;
  
  
==<grid/>==
+
==&lt;grid/&gt;==
 
The grid object is a very nice object for creating stretchable images that still look good on the edges.  It is a graphic, like a layer, but unlike layer it is created by applying nine different bitmaps, stretching five of them.  There are, as you might guess, nine parameters
 
The grid object is a very nice object for creating stretchable images that still look good on the edges.  It is a graphic, like a layer, but unlike layer it is created by applying nine different bitmaps, stretching five of them.  There are, as you might guess, nine parameters
  
Line 309: Line 310:
  
 
  Example:
 
  Example:
  <grid x="70" y="25" w="-74" relatw="1" h="20" topleft="main.text.left" top="main.text.center" topright="main.text.right"/>
+
  &lt;grid x=&quot;70&quot; y=&quot;25&quot; w=&quot;-74&quot; relatw=&quot;1&quot; h=&quot;20&quot; topleft=&quot;main.text.left&quot; top=&quot;main.text.center&quot; topright=&quot;main.text.right&quot;/&gt;
  
  
==<group/>==
+
==&lt;group/&gt;==
 
Groups are instantiated by using the group tag.  Groups, when instantiated within a layout or some other groupdef, take the standard GuiObject params in order to define the group's instantiated size and properties, and then all of the contents of the group will be instantiated within the space it defines.  At instantiation, a group will express a specified boundary rectangle and, thus, the positions of objects within it depending upon relative, proportional, or design coordinate systems may then be calculated.
 
Groups are instantiated by using the group tag.  Groups, when instantiated within a layout or some other groupdef, take the standard GuiObject params in order to define the group's instantiated size and properties, and then all of the contents of the group will be instantiated within the space it defines.  At instantiation, a group will express a specified boundary rectangle and, thus, the positions of objects within it depending upon relative, proportional, or design coordinate systems may then be calculated.
 
   
 
   
Line 319: Line 320:
 
* '''instance_id''' (str) - A new id value with which to be able find this particular instantiate.
 
* '''instance_id''' (str) - A new id value with which to be able find this particular instantiate.
  
The following snippet will create two instantiates of the source group, with one specially customized (in the assumption that the "specialchild.maki" script will be handling the fact one is going to be special) :
+
The following snippet will create two instantiates of the source group, with one specially customized (in the assumption that the &quot;specialchild.maki&quot; script will be handling the fact one is going to be special) :
  <groupdef id="child">
+
  &lt;groupdef id=&quot;child&quot;&gt;
  <layer image="childimg" x="0" y="0" w="0" h="0" relatw="0" relath="0"/>
+
  &lt;layer image=&quot;childimg&quot; x=&quot;0&quot; y=&quot;0&quot; w=&quot;0&quot; h=&quot;0&quot; relatw=&quot;0&quot; relath=&quot;0&quot;/&gt;
  </groupdef>
+
  &lt;/groupdef&gt;
  <groupdef id="parent">
+
  &lt;groupdef id=&quot;parent&quot;&gt;
  <group id="child" x="0" y="0" w="0" relatw="0" h="90"/>
+
  &lt;group id=&quot;child&quot; x=&quot;0&quot; y=&quot;0&quot; w=&quot;0&quot; relatw=&quot;0&quot; h=&quot;90&quot;/&gt;
  <group id="child" instance_id="special"
+
  &lt;group id=&quot;child&quot; instance_id=&quot;special&quot;
  notify="This is a special notification for this obj."
+
  notify=&quot;This is a special notification for this obj.&quot;
  x="0" y="90" w="0" relatw="0" h="-90" relath="1"/>
+
  x=&quot;0&quot; y=&quot;90&quot; w=&quot;0&quot; relatw=&quot;0&quot; h=&quot;-90&quot; relath=&quot;1&quot;/&gt;
  <script file="specialchild.maki"/>
+
  &lt;script file=&quot;specialchild.maki&quot;/&gt;
  </groupdef>
+
  &lt;/groupdef&gt;
  
  
==<grouplist/>==
+
==&lt;grouplist/&gt;==
 
A grouplist is, oddly enough, an object whose purpose is to accept and display a list of multiple groups.  For instance, Wasabi's popup menu is a grouplist.  A grouplist is expected to be filled in script, and it has no interesting parameters.
 
A grouplist is, oddly enough, an object whose purpose is to accept and display a list of multiple groups.  For instance, Wasabi's popup menu is a grouplist.  A grouplist is expected to be filled in script, and it has no interesting parameters.
  
  
==<layer/>==
+
==&lt;layer/&gt;==
 
In Wasabi, the layer is analogous to the same-named object in photoshop.  It is simply a nice bitmap graphic to be displayed in the user interface (with the standard alpha and region effects available to all guiobject derived objects, based by default on the properties of the bitmap element it houses).  Here are its parameters:
 
In Wasabi, the layer is analogous to the same-named object in photoshop.  It is simply a nice bitmap graphic to be displayed in the user interface (with the standard alpha and region effects available to all guiobject derived objects, based by default on the properties of the bitmap element it houses).  Here are its parameters:
 
* '''image''' - (id) The id of the bitmap element to be used for display.
 
* '''image''' - (id) The id of the bitmap element to be used for display.
* '''inactiveimage''' - (id) A secondary id to be displayed if this guiobject is set to "inactive" status.
+
* '''inactiveimage''' - (id) A secondary id to be displayed if this guiobject is set to &quot;inactive&quot; status.
 
* '''region''' - (id) The id of a different bitmap element to use as the source of this object's region.
 
* '''region''' - (id) The id of a different bitmap element to use as the source of this object's region.
 
* '''tile''' - (bool) Setting this flag will tile the image if the rectangular size of the layer is different than the rectangular size of the bitmap.  The default is to stretch.
 
* '''tile''' - (bool) Setting this flag will tile the image if the rectangular size of the layer is different than the rectangular size of the bitmap.  The default is to stretch.
Line 345: Line 346:
 
* '''scale''' - (str) A specific string enumerating which direction one should allow the scaling of the parent layout if this object's region is gripped and dragged by the user.  Incompatible with the move parameter on guiobject.  See below.
 
* '''scale''' - (str) A specific string enumerating which direction one should allow the scaling of the parent layout if this object's region is gripped and dragged by the user.  Incompatible with the move parameter on guiobject.  See below.
 
* '''dblclickaction''' - (str) The string of an action to be sent into the system if this object is doubleclicked within its region.
 
* '''dblclickaction''' - (str) The string of an action to be sent into the system if this object is doubleclicked within its region.
The resize and scale parameters transform the simple layer graphic into interactive gui objects in the system by enabling them to be dragged by the user to resize or change the scale of the parent layout.  The eight possible values for these parameters are "top" "left" "right" "bottom" "topleft" "topright" "bottomleft" and "bottomright." If both resize and scale are set on a single layer, the object will act as a resizer by default but as a scaler if the ALT key is held down.
+
The resize and scale parameters transform the simple layer graphic into interactive gui objects in the system by enabling them to be dragged by the user to resize or change the scale of the parent layout.  The eight possible values for these parameters are &quot;top&quot; &quot;left&quot; &quot;right&quot; &quot;bottom&quot; &quot;topleft&quot; &quot;topright&quot; &quot;bottomleft&quot; and &quot;bottomright.&quot; If both resize and scale are set on a single layer, the object will act as a resizer by default but as a scaler if the ALT key is held down.
  
  
==<animatedlayer/>==
+
==&lt;animatedlayer/&gt;==
 
An animatedlayer is a series of frames of sprite animation displayed in the GUI.  The frames of animation are specified in the bitmap element which is given in the image parameter to this object.  The animation is expected to be a specific progression of frames of a fixed size, also to be specified via parameters on the object.  Each frame of animation will have its own region.    The animatedlayer object inherits directly from the layer object, so all of the above parameters are valid, along with these specific to animation:
 
An animatedlayer is a series of frames of sprite animation displayed in the GUI.  The frames of animation are specified in the bitmap element which is given in the image parameter to this object.  The animation is expected to be a specific progression of frames of a fixed size, also to be specified via parameters on the object.  Each frame of animation will have its own region.    The animatedlayer object inherits directly from the layer object, so all of the above parameters are valid, along with these specific to animation:
 
* '''frameheight''' - (int) The height in pixels of each cell of animation.  If frameheight is set, the animation will be assumed to be a vertical strip of cells in the given bitmap.
 
* '''frameheight''' - (int) The height in pixels of each cell of animation.  If frameheight is set, the animation will be assumed to be a vertical strip of cells in the given bitmap.
Line 361: Line 362:
 
* '''debug''' - (bool)  Setting this flag will cause the system to draw the current frame number of the animation on top of the animation graphics, for, as you might guess, debug purposes.
 
* '''debug''' - (bool)  Setting this flag will cause the system to draw the current frame number of the animation on top of the animation graphics, for, as you might guess, debug purposes.
  
You must note that animations are usually meant to be "triggered" through script, as too many live animations happily blitting their way through a deep and complex user interface using lots of alpha blending, et al, can cause significant performance bottlenecks on slow computers (especially if your users aren't expecting your application to be eating all of the machine resources).  With this in mind, if you just create an animated layer and drop it into a skin, it will not begin animating unless you set the autoplay parameter.
+
You must note that animations are usually meant to be &quot;triggered&quot; through script, as too many live animations happily blitting their way through a deep and complex user interface using lots of alpha blending, et al, can cause significant performance bottlenecks on slow computers (especially if your users aren't expecting your application to be eating all of the machine resources).  With this in mind, if you just create an animated layer and drop it into a skin, it will not begin animating unless you set the autoplay parameter.
 
   
 
   
There are three different ways to present animation frames to this object.  The frames may either all be concatenated into a vertical or horizontal "filmstrip" style bitmap element -- in which case the height or width of each animation cell (respectively) should be set with the frameheight or framewidth parameter.   
+
There are three different ways to present animation frames to this object.  The frames may either all be concatenated into a vertical or horizontal &quot;filmstrip&quot; style bitmap element -- in which case the height or width of each animation cell (respectively) should be set with the frameheight or framewidth parameter.   
 
The third way to give this object its animation frames is more complex and consists of loading multiple bitmap elements with each bitmap representing one frame of animation.  This is done by first setting the elementframes parameter with the number of frames to be loaded, then by using a special formatting string as the image parameter.  For those familiar with the printf function, when the elementframes parameter is set, that integer will be run in a for loop and the image name will be used as the formatting string to a printf function that takes only the current integer in the for loop as a parameter.
 
The third way to give this object its animation frames is more complex and consists of loading multiple bitmap elements with each bitmap representing one frame of animation.  This is done by first setting the elementframes parameter with the number of frames to be loaded, then by using a special formatting string as the image parameter.  For those familiar with the printf function, when the elementframes parameter is set, that integer will be run in a for loop and the image name will be used as the formatting string to a printf function that takes only the current integer in the for loop as a parameter.
For those unfamiliar with printf, this will seem a bit confusing.  Somewhere in the string you pass to the image parameter, you should have the two characters %d, and these characters will be replaced by the character representation of the number as it loads bitmap elements.  If you want to have 0-loaded prefix characters (for instance "01-09" instead of "1-9"), you can place %02d into your image parameter, and if there aren't enough characters in the number to make up 2 full digits, the number will be left-padded with the zero character.  You can just as easily use any number of padding characters as well.   
+
For those unfamiliar with printf, this will seem a bit confusing.  Somewhere in the string you pass to the image parameter, you should have the two characters %d, and these characters will be replaced by the character representation of the number as it loads bitmap elements.  If you want to have 0-loaded prefix characters (for instance &quot;01-09&quot; instead of &quot;1-9&quot;), you can place %02d into your image parameter, and if there aren't enough characters in the number to make up 2 full digits, the number will be left-padded with the zero character.  You can just as easily use any number of padding characters as well.   
 
I highly suspect this all still makes little sense, so let me give you a simplified example (missing important parameters) to show three different animated layers each loading three sets of differently named bitmaps:
 
I highly suspect this all still makes little sense, so let me give you a simplified example (missing important parameters) to show three different animated layers each loading three sets of differently named bitmaps:
  <elements>
+
  &lt;elements&gt;
  <bitmap id="bmp1"/>
+
  &lt;bitmap id=&quot;bmp1&quot;/&gt;
  <bitmap id="bmp2"/>
+
  &lt;bitmap id=&quot;bmp2&quot;/&gt;
  <bitmap id="bmp3"/>
+
  &lt;bitmap id=&quot;bmp3&quot;/&gt;
  <bitmap id="bmp01img"/>
+
  &lt;bitmap id=&quot;bmp01img&quot;/&gt;
  <bitmap id="bmp02img"/>
+
  &lt;bitmap id=&quot;bmp02img&quot;/&gt;
  <bitmap id="bmp03img"/>
+
  &lt;bitmap id=&quot;bmp03img&quot;/&gt;
  <bitmap id="b00001mp"/>
+
  &lt;bitmap id=&quot;b00001mp&quot;/&gt;
  <bitmap id="b00002mp"/>
+
  &lt;bitmap id=&quot;b00002mp&quot;/&gt;
  <bitmap id="b00003mp"/>
+
  &lt;bitmap id=&quot;b00003mp&quot;/&gt;
  </elements>
+
  &lt;/elements&gt;
  <groupdef id="whatever">
+
  &lt;groupdef id=&quot;whatever&quot;&gt;
  <animatedlayer image="bmp%d" elementframes="3"/>
+
  &lt;animatedlayer image=&quot;bmp%d&quot; elementframes=&quot;3&quot;/&gt;
  <animatedlayer image="bmp%02dimg" elementframes="3"/>
+
  &lt;animatedlayer image=&quot;bmp%02dimg&quot; elementframes=&quot;3&quot;/&gt;
  <animatedlayer image="b%05dmp" elementframes="3"/>
+
  &lt;animatedlayer image=&quot;b%05dmp&quot; elementframes=&quot;3&quot;/&gt;
  </groupdef>
+
  &lt;/groupdef&gt;
  
  
==<layoutstatus/>==
+
==&lt;layoutstatus/&gt;==
 
The layoutstatus implements the small statusbar that can be found at the bottom of many of the default normal layouts which can contain status text, appcmds buttons, and a proportionally completed progress bar.  The two parameters to this object control what appcmds will be allowed in the status bar:
 
The layoutstatus implements the small statusbar that can be found at the bottom of many of the default normal layouts which can contain status text, appcmds buttons, and a proportionally completed progress bar.  The two parameters to this object control what appcmds will be allowed in the status bar:
 
* '''exclude''' - (str) A semicolon delimited list of names of appcmds which should not be shown by this control.
 
* '''exclude''' - (str) A semicolon delimited list of names of appcmds which should not be shown by this control.
Line 392: Line 393:
  
  
==<list/>==
+
==&lt;list/&gt;==
 
The list object is similar but not identical to the Win32 list common control.  It is an  optionally multicolumnar list whose purpose is to display multiple pieces of information per horizontal row.  It may be filled directly by encoding the contents in the XML, by attaching the object to a proper text feed, or by calling methods on the object from script.  The parameters for this object are:
 
The list object is similar but not identical to the Win32 list common control.  It is an  optionally multicolumnar list whose purpose is to display multiple pieces of information per horizontal row.  It may be filled directly by encoding the contents in the XML, by attaching the object to a proper text feed, or by calling methods on the object from script.  The parameters for this object are:
 
* '''items''' - (str) A properly delimited string of data used to fill the list.  See below.
 
* '''items''' - (str) A properly delimited string of data used to fill the list.  See below.
Line 402: Line 403:
 
* '''hoverselect''' - (bool) This flag causes list items to be selected if the user hovers over them.  Default is to not hoverselect.
 
* '''hoverselect''' - (bool) This flag causes list items to be selected if the user hovers over them.  Default is to not hoverselect.
 
* '''sort''' - (bool) This flag causes the list to sort itself.  Default is to not sort.
 
* '''sort''' - (bool) This flag causes the list to sort itself.  Default is to not sort.
* '''selectonupdown''' - (bool) This flag causes the list to interpret the keyboard commands to mean "change my selection to the item." Default is to select on keyboard events.
+
* '''selectonupdown''' - (bool) This flag causes the list to interpret the keyboard commands to mean &quot;change my selection to the item.&quot; Default is to select on keyboard events.
 
* '''numcolumns''' - (int) How many columns to show.  Default is one.
 
* '''numcolumns''' - (int) How many columns to show.  Default is one.
 
* '''columwidths''' - (int) A semicolon delimited list of integers specifying how to size the column widths in this list.  See below.
 
* '''columwidths''' - (int) A semicolon delimited list of integers specifying how to size the column widths in this list.  See below.
Line 409: Line 410:
 
   
 
   
 
Here is a sample list object with 3 rows and 3 columns:
 
Here is a sample list object with 3 rows and 3 columns:
  <list id="three.by.three"
+
  &lt;list id=&quot;three.by.three&quot;
  items="row1,text,1;row2,moretext,2;row3,stilltext,3"
+
  items=&quot;row1,text,1;row2,moretext,2;row3,stilltext,3&quot;
  numcolumns="3" columnwidths="50,-1,50"
+
  numcolumns=&quot;3&quot; columnwidths=&quot;50,-1,50&quot;
  multiselect="0" autodeselect="1"
+
  multiselect=&quot;0&quot; autodeselect=&quot;1&quot;
  />
+
  /&gt;
  
  
==<mouseredir/>==
+
==&lt;mouseredir/&gt;==
 
This object simply redirects all mouse events from its region to the target object specified in the parameter:
 
This object simply redirects all mouse events from its region to the target object specified in the parameter:
 
* '''target''' - (id) The target object to get mouse events.
 
* '''target''' - (id) The target object to get mouse events.
Line 422: Line 423:
  
  
==<Wasabi:RadioGroup/>==
+
==&lt;Wasabi:RadioGroup/&gt;==
 
The Wasabi:RadioGroup object is an invisible object whose purpose is to centralize the functionality of multiple Wasabi:CheckBox objects instantiated in radiobutton mode.  The radioid params on the Wasabi:CheckBox instantiates should give the id of one of these Wasabi:RadioGroup objects.  It has no unique parameters.  Here is a snippet of simple radiobutton functionality:
 
The Wasabi:RadioGroup object is an invisible object whose purpose is to centralize the functionality of multiple Wasabi:CheckBox objects instantiated in radiobutton mode.  The radioid params on the Wasabi:CheckBox instantiates should give the id of one of these Wasabi:RadioGroup objects.  It has no unique parameters.  Here is a snippet of simple radiobutton functionality:
  <Wasabi:RadioGroup id="enableddisabled"/>
+
  &lt;Wasabi:RadioGroup id=&quot;enableddisabled&quot;/&gt;
  <Wasabi:CheckBox x="50" y="110" w="60"
+
  &lt;Wasabi:CheckBox x=&quot;50&quot; y=&quot;110&quot; w=&quot;60&quot;
  text="Enabled" radioid="enableddisabled"
+
  text=&quot;Enabled&quot; radioid=&quot;enableddisabled&quot;
  cfgattrib="{9149C445-3C30-4E04-8433-5A518ED0FDDE};Enable desktop alpha"
+
  cfgattrib=&quot;{9149C445-3C30-4E04-8433-5A518ED0FDDE};Enable desktop alpha&quot;
  radioval="1"
+
  radioval=&quot;1&quot;
  />
+
  /&gt;
  <Wasabi:CheckBox x="-125" y="110" w="62" relatx="1"
+
  &lt;Wasabi:CheckBox x=&quot;-125&quot; y=&quot;110&quot; w=&quot;62&quot; relatx=&quot;1&quot;
  text="Disabled" radioid="enableddisabled"
+
  text=&quot;Disabled&quot; radioid=&quot;enableddisabled&quot;
  cfgattrib="{9149C445-3C30-4E04-8433-5A518ED0FDDE};Enable desktop alpha"
+
  cfgattrib=&quot;{9149C445-3C30-4E04-8433-5A518ED0FDDE};Enable desktop alpha&quot;
  radioval="0"
+
  radioval=&quot;0&quot;
  />
+
  /&gt;
  
  
==<rect/>==
+
==&lt;rect/&gt;==
 
A nice flat rectangle.  It may be either filled or hollow, and if hollow you may specify only some edges drawn.  Here are its parameters:
 
A nice flat rectangle.  It may be either filled or hollow, and if hollow you may specify only some edges drawn.  Here are its parameters:
* '''color''' - (id) The id of a color element, or an comma delimited integer triplet RGB value.  Default is "255,00,255" (an ugly color to remind you to set it).
+
* '''color''' - (id) The id of a color element, or an comma delimited integer triplet RGB value.  Default is &quot;255,00,255&quot; (an ugly color to remind you to set it).
 
* '''filled''' - (bool) This flag causes the entire rectangular area to be filled with color.  Default is to not be filled.
 
* '''filled''' - (bool) This flag causes the entire rectangular area to be filled with color.  Default is to not be filled.
* '''edges''' - (str) A pipe ("|") delimited set of one or all of the following: "left" "right" "top" "bottom" Default is all, ie: "left|right|top|bottom".
+
* '''edges''' - (str) A pipe (&quot;|&quot;) delimited set of one or all of the following: &quot;left&quot; &quot;right&quot; &quot;top&quot; &quot;bottom&quot; Default is all, ie: &quot;left|right|top|bottom&quot;.
  
  
==<script/>==
+
==&lt;script/&gt;==
Scripts allow for the simple creation of UI functionality without requiring C++ code.  While scripts are "compiled" into "script binaries," these script binaries are special to wasabi and, more importantly, can be run by any compatible Wasabi runtime on any OS to which Wasabi has a runtime.  Scripts are bound like GuiObjects into layout or groupdef sections using the script tag and have the ability to find and modify the nearby sibling and child objects once the UI has been fully instantiated.  Scripts have two important parameters:
+
Scripts allow for the simple creation of UI functionality without requiring C++ code.  While scripts are &quot;compiled&quot; into &quot;script binaries,&quot; these script binaries are special to wasabi and, more importantly, can be run by any compatible Wasabi runtime on any OS to which Wasabi has a runtime.  Scripts are bound like GuiObjects into layout or groupdef sections using the script tag and have the ability to find and modify the nearby sibling and child objects once the UI has been fully instantiated.  Scripts have two important parameters:
 
* '''file''' - (str) The filename of the .maki file to load, relative to this xml file.
 
* '''file''' - (str) The filename of the .maki file to load, relative to this xml file.
 
* '''param''' - (str) A string that will be available to the instance of the .maki file as an instance specific parameter.
 
* '''param''' - (str) A string that will be available to the instance of the .maki file as an instance specific parameter.
Line 451: Line 452:
  
  
==<slider/> & <Wasabi:HSlider/> & <Wasabi:VSlider/>==
+
==&lt;slider/&gt; &amp; &lt;Wasabi:HSlider/&gt; &amp; &lt;Wasabi:VSlider/&gt;==
 
The slider object consists of a background set of images, and a thumb.  The thumb is constrained to move in one dimension -- horizontally or vertically, depending upon its orientation.  The distance in pixels travelled by the thumb across its total distance is interpollated to produce a value between the low and high boundary integers which is assigned to any configuration attribute which may happen to be attached.  Here are the parameters for slider:
 
The slider object consists of a background set of images, and a thumb.  The thumb is constrained to move in one dimension -- horizontally or vertically, depending upon its orientation.  The distance in pixels travelled by the thumb across its total distance is interpollated to produce a value between the low and high boundary integers which is assigned to any configuration attribute which may happen to be attached.  Here are the parameters for slider:
 
* '''barleft''' - (id) The bitmap element for the left or top position of the slider.
 
* '''barleft''' - (id) The bitmap element for the left or top position of the slider.
Line 459: Line 460:
 
* '''downthumb''' - (id) The bitmap element for the slider thumb when held by the user.
 
* '''downthumb''' - (id) The bitmap element for the slider thumb when held by the user.
 
* '''hoverthumb''' - (id) The bitmap element for the slider thumb when the user's mouse is above it.
 
* '''hoverthumb''' - (id) The bitmap element for the slider thumb when the user's mouse is above it.
* '''orientation''' - (str) Either "v" or "vertical" to make the slider vertical, otherwise it will be horizontal.
+
* '''orientation''' - (str) Either &quot;v&quot; or &quot;vertical&quot; to make the slider vertical, otherwise it will be horizontal.
 
* '''low''' - (int) Set the low-value boundary.  Default is 0.
 
* '''low''' - (int) Set the low-value boundary.  Default is 0.
 
* '''high''' - (int) Set the high-value boundary.  Default is 255.
 
* '''high''' - (int) Set the high-value boundary.  Default is 255.
  
  
==<snappoint/>==
+
==&lt;snappoint/&gt;==
 
The snappoint is an invisible point that will attract other snappoint objects with the same id in any other layout and make them want to dock, like little magnets.  These objects have only the following subset of guiobject XML parameters:
 
The snappoint is an invisible point that will attract other snappoint objects with the same id in any other layout and make them want to dock, like little magnets.  These objects have only the following subset of guiobject XML parameters:
 
* '''id''' - (id) All snappoint objects with the same id will snap to each other.  Different ids ignore each other.
 
* '''id''' - (id) All snappoint objects with the same id will snap to each other.  Different ids ignore each other.
Line 473: Line 474:
  
  
==<Wasabi:TabSheet/>==
+
==&lt;Wasabi:TabSheet/&gt;==
 
The Wasabi:TabSheet object contains multiple group instances within it and allows the user to switch between the display of those groups by the ability to click on a list of tab buttons at the top of the rectangular area of the Wasabi:TabSheet.  The name parameter of each groupdef is displayed as the text in the tab which corresponds to it.  Here are the Wasabi:TabSheet parameters:
 
The Wasabi:TabSheet object contains multiple group instances within it and allows the user to switch between the display of those groups by the ability to click on a list of tab buttons at the top of the rectangular area of the Wasabi:TabSheet.  The name parameter of each groupdef is displayed as the text in the tab which corresponds to it.  Here are the Wasabi:TabSheet parameters:
 
* '''windowtype''' - (str) A windowtype string which will instantiate one of every groupdef with the same windowtype and every window class registered with a window creation service to include this windowtype.
 
* '''windowtype''' - (str) A windowtype string which will instantiate one of every groupdef with the same windowtype and every window class registered with a window creation service to include this windowtype.
Line 484: Line 485:
  
  
==<text/> & <Wasabi:Text/>==
+
==&lt;text/&gt; &amp; &lt;Wasabi:Text/&gt;==
 
The text object is for using the system to render some text in the font of your choice.
 
The text object is for using the system to render some text in the font of your choice.
Since Winamp 5.5 (skinversion 1.3) text objects can have multiple lines. For a new line use this "/n"
+
Since Winamp 5.5 (skinversion 1.3) text objects can have multiple lines. For a new line use this &quot;/n&quot;
  
 
* '''display''' - (str) Either a specific system display string or the string identifier of a text feed.  Setting this value will override the text parameter.  See below.
 
* '''display''' - (str) Either a specific system display string or the string identifier of a text feed.  Setting this value will override the text parameter.  See below.
Line 495: Line 496:
 
* '''font''' - (id) The id of a bitmapfont or truetypefont element.  If no element with that id can be found, the OS will be asked for a font with that name instead.
 
* '''font''' - (id) The id of a bitmapfont or truetypefont element.  If no element with that id can be found, the OS will be asked for a font with that name instead.
 
* '''fontsize''' - (int) The size to render the chosen font.
 
* '''fontsize''' - (int) The size to render the chosen font.
* '''align''' - (str) One of the following three possible strings: "left" "center" "right" -- Default is "left."
+
* '''align''' - (str) One of the following three possible strings: &quot;left&quot; &quot;center&quot; &quot;right&quot; -- Default is &quot;left.&quot;
* '''valign''' - (str) One of the following three possible strings: "top" "center" "bottom" -- Default is "top."
+
* '''valign''' - (str) One of the following three possible strings: &quot;top&quot; &quot;center&quot; &quot;bottom&quot; -- Default is &quot;top.&quot;
 
* '''color''' - (int) The comma delimited RGB color of the text.
 
* '''color''' - (int) The comma delimited RGB color of the text.
 
* '''shadowcolor''' - (int) The comma delimited RGB color for underrendered shadow text.
 
* '''shadowcolor''' - (int) The comma delimited RGB color for underrendered shadow text.
 
* '''shadowx''' - (int) The x offset of the shadowrender.
 
* '''shadowx''' - (int) The x offset of the shadowrender.
 
* '''shadowy''' - (int) The y offset of the shadowrender.
 
* '''shadowy''' - (int) The y offset of the shadowrender.
* '''timeroffstyle''' - (int) How to display an empty timer: "0" = " ", "1" = "00:00", and "2"="" (if one is displaying time)
+
* '''timeroffstyle''' - (int) How to display an empty timer: &quot;0&quot; = &quot; &quot;, &quot;1&quot; = &quot;00:00&quot;, and &quot;2&quot;=&quot;&quot; (if one is displaying time)
 
* '''timecolonwidth''' - (int) How many extra pixels wider or smaller should the colon be when displaying time.  Default is -1.
 
* '''timecolonwidth''' - (int) How many extra pixels wider or smaller should the colon be when displaying time.  Default is -1.
 
* '''nograb''' - (bool) Setting this flag will cause the text object to ignore left button down messages.  Default is off.
 
* '''nograb''' - (bool) Setting this flag will cause the text object to ignore left button down messages.  Default is off.
Line 512: Line 513:
 
* '''bold''' - (bool) Render the display string in bold.
 
* '''bold''' - (bool) Render the display string in bold.
 
* '''wrap''' - (bool) Setting this flag will cause the text to wrap in its rectangular space.  Default is off.
 
* '''wrap''' - (bool) Setting this flag will cause the text to wrap in its rectangular space.  Default is off.
* '''dblclickaction''' - (str) A string in the form "SWITCH;layout" where layout is the id of a layout in this object's parent container.  No other actions function on this object.  This action is deprecated.
+
* '''dblclickaction''' - (str) A string in the form &quot;SWITCH;layout&quot; where layout is the id of a layout in this object's parent container.  No other actions function on this object.  This action is deprecated.
 
* '''offsetx''' - (int) Extra pixels to be added to or subtracted from the calculated x value for the display string to render.
 
* '''offsetx''' - (int) Extra pixels to be added to or subtracted from the calculated x value for the display string to render.
 
* '''offsety''' - (int) Extra pixels to be added to or subtracted from the calculated x value for the display string to render.
 
* '''offsety''' - (int) Extra pixels to be added to or subtracted from the calculated x value for the display string to render.
  "SONGNAME" - The name string of the currently playing song (from metadb).
+
  &quot;SONGNAME&quot; - The name string of the currently playing song (from metadb).
  "SONGINFO" - The full info string of the currently playing song (from metadb).
+
  &quot;SONGINFO&quot; - The full info string of the currently playing song (from metadb).
  "SONGARTIST" - The artist string of the currently playing song (from metadb).
+
  &quot;SONGARTIST&quot; - The artist string of the currently playing song (from metadb).
  "SONGTITLE" - The title string of the currently playing song (from metadb).
+
  &quot;SONGTITLE&quot; - The title string of the currently playing song (from metadb).
  "SONGALBUM" - The album string of the currently playing song (from metadb).
+
  &quot;SONGALBUM&quot; - The album string of the currently playing song (from metadb).
  "SONGLENGTH" - The length string of the currently playing song (from metadb).
+
  &quot;SONGLENGTH&quot; - The length string of the currently playing song (from metadb).
  "TIME" - The length string of the currently playing song.
+
  &quot;TIME&quot; - The length string of the currently playing song.
  "TIMEELAPSED" - The elapsed time string of the currently playing song.
+
  &quot;TIMEELAPSED&quot; - The elapsed time string of the currently playing song.
  "TIMEREMAINING" - The time remaining string of the currently playing song.
+
  &quot;TIMEREMAINING&quot; - The time remaining string of the currently playing song.
  "COMPONENTBUCKET" - The id of the componentbucket (thinger) item the mousecursor is currently hovering above.
+
  &quot;COMPONENTBUCKET&quot; - The id of the componentbucket (thinger) item the mousecursor is currently hovering above.
  "SONGBITRATE" - The bitrate string of the currently playing song (from metadb).
+
  &quot;SONGBITRATE&quot; - The bitrate string of the currently playing song (from metadb).
  "SONGSAMPLERATE" - The sample string of the currently playing song (from metadb).
+
  &quot;SONGSAMPLERATE&quot; - The sample string of the currently playing song (from metadb).
 
   
 
   
 
  *** Broken Action (Winamp 5) ***
 
  *** Broken Action (Winamp 5) ***
  "NORMALIZER:STATUS" - The current status of the audio normalizer.
+
  &quot;NORMALIZER:STATUS&quot; - The current status of the audio normalizer.
  
 
  Example:
 
  Example:
  <text x="81" y="11" w="25" h="21" antialias="0" text="Read This" align="center" color="0,0,0" bold="1"/>
+
  &lt;text x=&quot;81&quot; y=&quot;11&quot; w=&quot;25&quot; h=&quot;21&quot; antialias=&quot;0&quot; text=&quot;Read This&quot; align=&quot;center&quot; color=&quot;0,0,0&quot; bold=&quot;1&quot;/&gt;
  
  
==<Wasabi:TitleBox/>==
+
==&lt;Wasabi:TitleBox/&gt;==
 
The Wasabi:TitleBox object is a nice way to put a simple rectangular frame and title around your content groups.  It has the following parameters:
 
The Wasabi:TitleBox object is a nice way to put a simple rectangular frame and title around your content groups.  It has the following parameters:
 
* '''title''' - (str) The string to display in the title area.  Default is to use the name parameter of the content group.
 
* '''title''' - (str) The string to display in the title area.  Default is to use the name parameter of the content group.
Line 543: Line 544:
  
  
==<Wasabi:Titlebar/>==
+
==&lt;Wasabi:Titlebar/&gt;==
 
The Wasabi:TitleBar is the graphically themed bar that is placed at the top of all of the Wasabi:StandardFrame windows.  It has the same parameters as the text object, which control the text display of the titlebar.
 
The Wasabi:TitleBar is the graphically themed bar that is placed at the top of all of the Wasabi:StandardFrame windows.  It has the same parameters as the text object, which control the text display of the titlebar.
  
  
==<tree/>==
+
==&lt;tree/&gt;==
 
The tree object displays a hierarchical set of information with multiple items, where each item may in turn have multiple subitems.  Let's examine its parameters:
 
The tree object displays a hierarchical set of information with multiple items, where each item may in turn have multiple subitems.  Let's examine its parameters:
 
* '''items''' - (str) A specially formatted string describing the hierarchical creation of the tree info.  See below.
 
* '''items''' - (str) A specially formatted string describing the hierarchical creation of the tree info.  See below.
Line 554: Line 555:
 
* '''childtabs''' - (bool) Setting this flag will cause all tree items with children to display a tab graphic beside them.  Default is to show tab graphics.
 
* '''childtabs''' - (bool) Setting this flag will cause all tree items with children to display a tab graphic beside them.  Default is to show tab graphics.
 
* '''expandroot''' - (bool) Setting this flag will cause all root tree items to display with their children pre-expanded.  Default is to pre-expand root tree items.
 
* '''expandroot''' - (bool) Setting this flag will cause all root tree items to display with their children pre-expanded.  Default is to pre-expand root tree items.
The syntax required to describe the hierarchy of tree items is a semicolon delimited list of objects in the form "name(list)" where name is the string to display for that tree item and list is another semicolon delimited list of objects which are the direct children of name.  
+
The syntax required to describe the hierarchy of tree items is a semicolon delimited list of objects in the form &quot;name(list)&quot; where name is the string to display for that tree item and list is another semicolon delimited list of objects which are the direct children of name.  
 
   
 
   
 
The following snippet will create a tree with one root node that has three child nodes, with each child node having differing numbers of sub nodes:
 
The following snippet will create a tree with one root node that has three child nodes, with each child node having differing numbers of sub nodes:
  <tree id="example.tree"
+
  &lt;tree id=&quot;example.tree&quot;
  x="0" y="0" w="0" h="0" relatw="1" relath="1"
+
  x=&quot;0&quot; y=&quot;0&quot; w=&quot;0&quot; h=&quot;0&quot; relatw=&quot;1&quot; relath=&quot;1&quot;
  items="root(child1(sub1;sub2);child2;child3(sub3))"
+
  items=&quot;root(child1(sub1;sub2);child2;child3(sub3))&quot;
  />
+
  /&gt;
  
  
==<vis/>==
+
==&lt;vis/&gt;==
 
The vis object is the multistate audio visualization display.  It has a multitude of parameters for how simple it is:
 
The vis object is the multistate audio visualization display.  It has a multitude of parameters for how simple it is:
 
* '''colorallbands''' - (int) The comma delimited RGB triplet to color all the spectroscope bands.
 
* '''colorallbands''' - (int) The comma delimited RGB triplet to color all the spectroscope bands.
Line 589: Line 590:
 
* '''colorosc4''' - (int) The comma delimited RGB triplet to color oscilloscope section 4.
 
* '''colorosc4''' - (int) The comma delimited RGB triplet to color oscilloscope section 4.
 
* '''colorosc5''' - (int) The comma delimited RGB triplet to color oscilloscope section 5.
 
* '''colorosc5''' - (int) The comma delimited RGB triplet to color oscilloscope section 5.
* '''channel''' - (int) One of three values for which channel to monitor: "1" is left channel, "2" is right channel, "3" is stereo.  Default is stereo.
+
* '''channel''' - (int) One of three values for which channel to monitor: &quot;1&quot; is left channel, &quot;2&quot; is right channel, &quot;3&quot; is stereo.  Default is stereo.
 
* '''fliph''' - (bool) If this flag is set, it blits the vis pixels flipped horizontally.
 
* '''fliph''' - (bool) If this flag is set, it blits the vis pixels flipped horizontally.
 
* '''flipv''' - (bool) If this flag is set, it blits the vis pixels flipped vertically.
 
* '''flipv''' - (bool) If this flag is set, it blits the vis pixels flipped vertically.
* '''mode''' - (int) One of three values for which mode to display: "0" is no display, "1" is spectroscope, "2" is oscilloscope.  Default is to read from a config item.
+
* '''mode''' - (int) One of three values for which mode to display: &quot;0&quot; is no display, &quot;1&quot; is spectroscope, &quot;2&quot; is oscilloscope.  Default is to read from a config item.
 
When the user clicks on the vis, it will cycle between its three modes.
 
When the user clicks on the vis, it will cycle between its three modes.
  
  
==<eqvis/>==
+
==&lt;eqvis/&gt;==
 
The eqvis object is rather specific to media players, as it is the spline display for the eq settings in the Wasabi Media Player.
 
The eqvis object is rather specific to media players, as it is the spline display for the eq settings in the Wasabi Media Player.
 
* '''colortop''' - (str) A color value or color element id for the top portion of the spline display.
 
* '''colortop''' - (str) A color value or color element id for the top portion of the spline display.
Line 604: Line 605:
  
  
==<gradient/>==
+
==&lt;gradient/&gt;==
 
The gradient object creates a rectangular color gradient.  The available parameters are:
 
The gradient object creates a rectangular color gradient.  The available parameters are:
 
* '''gradient_x1''' - (float) A floating point value for the left side of the rectangle.  Default is 0.0
 
* '''gradient_x1''' - (float) A floating point value for the left side of the rectangle.  Default is 0.0
Line 611: Line 612:
 
* '''gradient_x1''' - (float) A floating point value for the bottom side of the rectangle.  Default is 1.0
 
* '''gradient_x1''' - (float) A floating point value for the bottom side of the rectangle.  Default is 1.0
 
* '''points''' - (str) A complex string defining color values for at least two value points with which to build the gradients.  See below.
 
* '''points''' - (str) A complex string defining color values for at least two value points with which to build the gradients.  See below.
The points syntax is a semicolon delimited list of key=value pairs where the key is a floatingpoint number representing a point in the "gradient space" and the value is an RGB triplet (assumed full alpha) or RGBA quad.  For instance, the following object would create a smooth gradient between red in the top left and green at half alpha in the bottom right:
+
The points syntax is a semicolon delimited list of key=value pairs where the key is a floatingpoint number representing a point in the &quot;gradient space&quot; and the value is an RGB triplet (assumed full alpha) or RGBA quad.  For instance, the following object would create a smooth gradient between red in the top left and green at half alpha in the bottom right:
  <gradient id="red.to.green"
+
  &lt;gradient id=&quot;red.to.green&quot;
  x="0" y="0" w="0" h="0"
+
  x=&quot;0&quot; y=&quot;0&quot; w=&quot;0&quot; h=&quot;0&quot;
  relatw="1" relath="1"
+
  relatw=&quot;1&quot; relath=&quot;1&quot;
  points="0.0=255,0,0,255;1.0=0,255,0,128"
+
  points=&quot;0.0=255,0,0,255;1.0=0,255,0,128&quot;
  />
+
  /&gt;
  
  
==<Wasabi:StandardFrame:Status/>==
+
==&lt;Wasabi:StandardFrame:Status/&gt;==
  
==<Wasabi:StandardFrame:NoStatus/>==
+
==&lt;Wasabi:StandardFrame:NoStatus/&gt;==
  
==<Wasabi:StandardFrame:Modal/>==
+
==&lt;Wasabi:StandardFrame:Modal/&gt;==
  
==<Wasabi:StandardFrame:Static/>==
+
==&lt;Wasabi:StandardFrame:Static/&gt;==
 
The Wasabi:StandardFrame objects are rectangular frames you can use to encapsulate your own layout contents within the currently themed standard frame.  They all have the following parameters:
 
The Wasabi:StandardFrame objects are rectangular frames you can use to encapsulate your own layout contents within the currently themed standard frame.  They all have the following parameters:
 
* '''content''' - (id) The id of the groupdef to instantiate within the Wasabi:StandardFrame.
 
* '''content''' - (id) The id of the groupdef to instantiate within the Wasabi:StandardFrame.
Line 634: Line 635:
  
  
==<wndholder/>==
+
==&lt;wndholder/&gt;==
 
A wndholder object, similar to a customobject, holds user interface windows based upon what param is given.  The wndholder can also hold window types by guid or groupdef instantiations by id.  Here are its parameters:
 
A wndholder object, similar to a customobject, holds user interface windows based upon what param is given.  The wndholder can also hold window types by guid or groupdef instantiations by id.  Here are its parameters:
 
* '''hold''' - (id) A semicolon delimited list of guids or groupdef ids to hold.
 
* '''hold''' - (id) A semicolon delimited list of guids or groupdef ids to hold.
Line 644: Line 645:
 
* '''autoopen''' - (bool) Setting this flag will cause the object to auto open.
 
* '''autoopen''' - (bool) Setting this flag will cause the object to auto open.
 
* '''autoclose''' - (bool) Setting this flag will cause the object to auto close.
 
* '''autoclose''' - (bool) Setting this flag will cause the object to auto close.
Using a wndholder object indicates to the system that you want to be the "container of record" for the possible requested guids when they are launched by the system through, for instance, the C++ coder registering his window class with registerAutopopup(), which calls the underlying api->skinwnd_createByGuid().  The container within which this wndholder is instantiated should also be given a component parameter with the same values.  This component parameter is simply a hint to Wasabi that a wndholder object that will accept that component parameter lives within the container.
+
Using a wndholder object indicates to the system that you want to be the &quot;container of record&quot; for the possible requested guids when they are launched by the system through, for instance, the C++ coder registering his window class with registerAutopopup(), which calls the underlying api-&gt;skinwnd_createByGuid().  The container within which this wndholder is instantiated should also be given a component parameter with the same values.  This component parameter is simply a hint to Wasabi that a wndholder object that will accept that component parameter lives within the container.
  
  
==<objdirview/>==
+
==&lt;objdirview/&gt;==
 
The objdirview object displays a tree of hierarchical information to the user, based on a code concept called an Object Directory.  An Object Directory is, in essence, just a container of arbitrary items so this object is merely the display of its contents.  Here are its parameters:
 
The objdirview object displays a tree of hierarchical information to the user, based on a code concept called an Object Directory.  An Object Directory is, in essence, just a container of arbitrary items so this object is merely the display of its contents.  Here are its parameters:
 
* '''dir''' - (str) The string identifier of the objdir to which this object should connect.
 
* '''dir''' - (str) The string identifier of the objdir to which this object should connect.
Line 656: Line 657:
  
  
==<Wasabi:PathPicker/>==
+
==&lt;Wasabi:PathPicker/&gt;==
 
The Wasabi:PathPicker object is a simple object to display a text string of a directory path chosen by the user.  When the user clicks on the object, a dir selection service is started, allowing the user to choose a directory path.  Attach this object to a string configuration attribute and you have a simple way for users to choose directories as preferences.  The Wasabi:PathPicker object has no unique parameters.
 
The Wasabi:PathPicker object is a simple object to display a text string of a directory path chosen by the user.  When the user clicks on the object, a dir selection service is started, allowing the user to choose a directory path.  Attach this object to a string configuration attribute and you have a simple way for users to choose directories as preferences.  The Wasabi:PathPicker object has no unique parameters.
  
  
==<querydrag/>==
+
==&lt;querydrag/&gt;==
The querydrag object is used to create a visual "drag source" for a nearby queryresults object.  The user may click and drag this object and by doing so representationally drag the text of the current query in the queryresults object (which can be dropped into a playlist editor to fill its contents with the results of that query).  It has only two parameters:
+
The querydrag object is used to create a visual &quot;drag source&quot; for a nearby queryresults object.  The user may click and drag this object and by doing so representationally drag the text of the current query in the queryresults object (which can be dropped into a playlist editor to fill its contents with the results of that query).  It has only two parameters:
 
* '''image''' - (id) The bitmap element to display.
 
* '''image''' - (id) The bitmap element to display.
 
* '''source''' - (id) The source queryresults object.  Default is the nearest.
 
* '''source''' - (id) The source queryresults object.  Default is the nearest.
Line 667: Line 668:
  
  
==<queryline/>==
+
==&lt;queryline/&gt;==
 
The invisible queryline object is used to host a text query to be applied to a queryresults object.  One possible use would be to write a script linking the text in a Wasabi:HistoryEditBox to the query parameter of a queryline.  And, speaking of its parameters, here they are:
 
The invisible queryline object is used to host a text query to be applied to a queryresults object.  One possible use would be to write a script linking the text in a Wasabi:HistoryEditBox to the query parameter of a queryline.  And, speaking of its parameters, here they are:
 
* '''querylist''' - (id) The id of the queryresults which will take the query.  Default is to not connect (ie: this param is kinda sorta mandatoryish if you want anything interesting to happen).
 
* '''querylist''' - (id) The id of the queryresults which will take the query.  Default is to not connect (ie: this param is kinda sorta mandatoryish if you want anything interesting to happen).
 
* '''query''' - (str) The string of the query itself.
 
* '''query''' - (str) The string of the query itself.
* '''auto''' - (bool) Whether or not to execute an autoquery based on the query parameter (ie: "search on the name column for this substring" instead of "run this query").  Default is to use the string directly as a query (not autoquery).
+
* '''auto''' - (bool) Whether or not to execute an autoquery based on the query parameter (ie: &quot;search on the name column for this substring&quot; instead of &quot;run this query&quot;).  Default is to use the string directly as a query (not autoquery).
  
  
==<queryresults/>==
+
==&lt;queryresults/&gt;==
 
The queryresults object is the an invisible binding object that coordinates the filtration of the database by numerous multiple other objects.  The queryline and filterlist objects eventually define a single output from the database, and this information is kept in the queryresults object.  It has only one parameter:
 
The queryresults object is the an invisible binding object that coordinates the filtration of the database by numerous multiple other objects.  The queryline and filterlist objects eventually define a single output from the database, and this information is kept in the queryresults object.  It has only one parameter:
 
title - (str) The human readable title for your queryresults.  I have no idea why this would be important.
 
title - (str) The human readable title for your queryresults.  I have no idea why this would be important.
 
Magically, it seems, placing a queryresults object in the same group next to a PlaylistEditor object makes that PlaylistEditor get filled with the queryresults information.  I have no idea how this can be, and sense the telltale signs of powerful dark necromancy at work, here.
 
Magically, it seems, placing a queryresults object in the same group next to a PlaylistEditor object makes that PlaylistEditor get filled with the queryresults information.  I have no idea how this can be, and sense the telltale signs of powerful dark necromancy at work, here.

Revision as of 06:12, 24 November 2010

This Page Is Currently Under Construction And Will Be Available Shortly, Please Visit Reserve Copy Page

GuiObject (Global params)

All the objects to be discussed in this chapter are GuiObjects. This means, among other things, all such objects have the same basic set of parameters which are valid for all of them. All GuiObjects are objects that live with a set of spatial coordinates within a groupdef (or layout). A button, a piece of text, a flat bitmap image, a tree of items, and an edit box would all be different kinds of GuiObjects, and all of the parameters listed here work on all of them.

  • alpha - (int) An integer [0,255] specifying the alpha blend mode of the object (0 is transparent, 255 is opaque). Default is 255.
  • activealpha - (int) A different alpha value [0,255] for the object in its active state.
  • inactivealpha - (int) A different alpha value [0,255] for the object in its inactive state (if you set both activealpha and inactivealpha, it is meaningless to set alpha).
  • cursor - (id) The id of the cursor element to be displayed when the mouse is over this object. You can also use the system cursors. A list can be found here: Appendix: Cursors
  • tooltip - (str) A human readable string to display as a tooltip for when the mouse is hovered over this object.
  • 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.

Appendixes


<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"/>

Appendix


<nstatesbutton/>

The nstatesbutton is a specialized kind of togglebutton whose purpose is to cycle through a number of different visual states. The parameters beyond togglebutton that it implements are:

  • nstates - (int) The number of discrete states in which the object may exist.
  • cfgvals - (str) A semicolon delimited list of values to represent custom config values for the multiple states. Default is the current state number. See below.

The nstatesbutton uses special handling of the image, downimage, hoverimage, and activeimage parameters expressed by the button object (from which this object is derived). The nstatesbutton will actually append the state number to the four image parameter strings to calculate the bitmap ids to be loaded for the current object state. Remember, like most everything else in a computer, this "current state value" counts from 0 and is therefore in the range [0, nstates-1].

If the object is bound to a configuration attribute, that attribute will be set with a cfgval every time the nstatesbutton transitions to a new state. If the cfgvals parameter is not set, the attribute will simply be set with the current state value. If the cfgvals parameter is set, it will parse the string and set the config attrib with the n'th substring corresponding to the current state value.

The following snippet fully describes two nstatesbutton objects with three states each, one using full images for its visual display, one using themed Wasabi borders with three different state logos:

<elements>
	<bitmap id="nimg0"/> 
	<bitmap id="dimg0"/> 
	<bitmap id="himg0"/>
	<bitmap id="nimg1"/> 
	<bitmap id="dimg1"/> 
	<bitmap id="himg1"/>
	<bitmap id="nimg2"/> 
	<bitmap id="dimg2"/> 
	<bitmap id="himg2"/>
	<bitmap id="logo0"/>
	<bitmap id="logo1"/>
	<bitmap id="logo2"/>
</elements>
<groupdef id="some.random.groupdef">
	<nstatesbutton id="three.freeform.states"
		nstates="3" cfgvals="one;two;three"
		image="nimg" downimage="dimg" hoverimage="himg"
	/>
	<nstatesbutton id="three.themed.states"
		nstates="3" image="logo" borders="1" center_image="1"
	/>
</groupdef>

If the "three.freeform.states" nstatesbutton were assigned to a configattrib, that attribute would be filled with the values "one" "two" and "three" in order. If the "three.themed.states" were instead assigned to a configattrib, it would be filled with the default values "0" "1" and "2" in order.


<images/>

The images object is object that displays a certain image based on the position of a slider. This object is very similar to Animationlayer except that this animation's current frame will be determined by the position of a slider. An example of implementation is the old Classic Winamp skins where the volume slider background changes colour from green to red depending on its position (0%-100%). This object is currently under development and not all sliders are supported. Currently only Volume and Panning(Balance) sliders can be used as sources.

  • images - (id) A bitmap element for the array of images that will be used.
  • source - (id) Id of the slider that will determine the current animation frame.
  • imagesspacing - (int) The hight of each animation frame in the bitmap element. This will determine the total number of frames, (300/15=20)
Example:
<images source="volume" x="0" y="0" w="68" h="13"
images="main.volpan.volume" imagesspacing="15"/>

<images source="balance" x="73" y="0" w="38" h="13"
images="main.volpan.balance" imagesspacing="15"/>
 
<slider id="Volume" action="VOLUME" x="1" y="0" w="68" h="13"
thumb="main.volpan.thumb" downThumb="main.volpan.thumb.pressed"/>

<slider id="Pan" action="PAN" x="74" y="0" w="38" h="13"
thumb="main.volpan.thumb" downThumb="main.volpan.thumb.pressed"/>

<PlaylistDirectory/>

The PlaylistDirectory object is simply a list with all the saved playlist from the media library. Please remember that this object is always on top of other objects, so you'll have to hide it via maki if you dont want it to be visible. This object was introduced in Winamp 5.5(skinversion 1.3)


<AlbumArt/>

The AlbumArt object is a simple GuiObject that displays a picture of the album cover of the song thats playing in Winamp. Please note that if you want do something to this object in a maki script you'll have to define it as a guiobject and not as a layer.

  • notfoundImage - (id) A bitmap element that used if Winamp cant find any cover for the song.
  • align - (str) One of the following three possible strings: "left" "center" "right" -- Default is "left".
  • valign - (str) One of the following three possible strings: "top" "center" "bottom" -- Default is "top".
  • source - (str) Path+Filename of file that you want to display in this object.
  • stretched - (bool) Stretch the albumart to the size of the object.


<grid/>

The grid object is a very nice object for creating stretchable images that still look good on the edges. It is a graphic, like a layer, but unlike layer it is created by applying nine different bitmaps, stretching five of them. There are, as you might guess, nine parameters

  • topleft - (id) A bitmap element for the top left section of the grid.
  • top - (id) A bitmap element for the top middle section of the grid.
  • topright - (id) A bitmap element for the top right section of the grid.
  • left - (id) A bitmap element for the middle left section of the grid.
  • middle - (id) A bitmap element for the center section of the grid.
  • right - (id) A bitmap element for the middle right section of the grid.
  • bottomleft - (id) A bitmap element for the bottom left section of the grid.
  • bottom - (id) A bitmap element for the bottom middle section of the grid.
  • bottomright - (id) A bitmap element for the bottom right section of the grid.

Essentially, the given rectangle of the grid is intersected with 2 horizontal and 2 vertical lines. The topleft, topright, bottomleft, and bottomright bitmap elements will not be resized. The top, left, middle, right, and bottom bitmap elements, however, will be stretched to make all fit the grid rectangle. Using intelligently sized bitmap elements is fairly critical for this object. If you're having trouble, try starting with all of your bitmap elements as equal-sized squares.

Example:
<grid x="70" y="25" w="-74" relatw="1" h="20" topleft="main.text.left" top="main.text.center" topright="main.text.right"/>


<Winamp:Browser/>

This is basically the browser you'll see in the Bento Winamp skin. You'll also need Winamp 5.54 (skinversion 1.34) for it to work.

- home - (str) Url for the default homepage for the browser xui.


<browser/>

The browser object embeds an external browser technology window (such as IE or Mozilla) into the user interface with which you can load and render HTML directly.

  • url - (str) The url to be displayed.
  • mainmb - (bool) Setting this flag makes this browser object the "main mini-browser" for the system.
  • targetname - (str) This allows this browser object to be set as a specific HTML target.
  • scrollbars - (str) An enumerated string to determine how the system should handle the embedded browser's scrollbars. See below.

Numerous interfaces in Wasabi refer to or control the "main" mini-browser. Setting the mainmb flag will cause the last browser object which processed its mainmb param to be the main. In other words, please don't set this flag on more than one object if you actually care which one is the main. Scrollbars are important for big browser windows, but can interfere with the simple rendering of HTML content as part of a Wasabi UI. To this end, the skinner can control how the scrollbars of the embedded browser are displayed by setting the scrollbars parameter to one of the following four string values: "auto" "never" "always" or "default" - default is to allow the HTML page to specify, all others override.


<Wasabi:Frame/>

The Wasabi:Frame object is a themed control whose purpose is to provide a movable interface between two rectangular areas, much like the concept of an HTML frame. Here are its parameters:

  • orientation - (str) One of the following four string values: "v" "vertical" "h" "horizontal" (Default is vertical).
  • left - (id) The group to be instantiated in the left or top frame.
  • right - (id) The group to be instantiated in the right or bottom frame.
  • top - (id) The group to be instantiated in the left or top frame.
  • bottom - (id) The group to be instantiated in the right or bottom frame.
  • from - (str) One of the following string values: "l" "left" "t" "top" or "r" "right" "b" "bottom" (Default is left).
  • width - (int) How many pixels from the chosen edge to start.
  • height - (int) How many pixels from the chosen edge to start.
  • resizable - (bool) Set this flag to allow the user to change the position of the framedivider. Default is to allow it to be resizable.
  • maxwidth - (int) The maximum amount of pixels you are able to move the poppler if resizable.
  • minwidth - (int) The minimum amount of pixels you are able to move the poppler if resizable (If you go below this value the poppler will snap to 0).
  • vgrabber - (string) The centered bitmap of the Grabber.
  • vbitmap - (string) The stretched bitmap of the Grabber.

In the following simple example, the "top" and "bottom" groups are displayed in a resizable frame object:

<groupdef id="top">
	<text text="Top" align="center" x="0" y="0" w="0" h="0" relatw="1" relath="1"/>
</groupdef>
<groupdef id="bottom">
    <text text="Bottom" align="center" x="0" y="0" w="0" h="0" relatw="1" relath="1"/>
</groupdef>
<groupdef id="both">
	<Wasabi:Frame
		orientation="horizontal"
		top="top" bottom="bottom"    
		x="0" y="0" w="0" h="0"
		relatw="1" relath="1"
	/>
</groupdef>


<Wasabi:CheckBox/>

The Wasabi:Checkbox object exists only as a namespaced object because it is expected to have only a single themed appearance. The Wasabi:Checkbox object is used for both checkbox functionality and radiobutton functionality, depending up on the specification of its parameters. It consists of a combination of a togglebutton and a text object to create a single functional user interface object.

  • text - (str) The text to display as part of the checkbox.
  • radioid - (id) If the button is to be used as part of a radio group, specify id of the parent Wasabi:RadioGroup object here.
  • radioval - (int) If the button is to be used as part of a radio group, specify its unique integer value here.
  • action - (str) see button.
  • param - (str) see button.
  • action_target - (id) see button.

As with togglebutton, this is a very useful object for binding to a configuration attribute. It is very popular in preferences interfaces. If the object has a value for radioval, that will be the value set into the attribute if the object is activated.


<Wasabi:DropDownList/>

The Wasabi:DropDownList is a themed dialog object. It may be statically filled via a parameter or dynamically through script or by binding it to a text feed from code. A Wasabi:DropDownList object may be bound to an integer configuration attribute.

  • items - (str) A semicolon delimited list of items to be displayed in the dropdown area.
  • feed - (id) The id of a text feed to provide a semicolon delimited list of items to be displayed in the dropdown area.
  • select - (int) Specifies an item to be selected.
  • listheight - (int) Allows the skinner to specify the height of the dropdown area in pixels.
  • maxitems - (int) Allows the skinner to specify the max height of the dropdown area in lines of text. If the dropdown area has fewer lines of text than this value when this value is set, the dropdown area is sized to show no more than is needed.


<Wasabi:ComboBox/>

The Wasabi:ComboBox is a special type of object which combines dropdownlist functionality with an edit field as well. It has the same parameters as Wasabi:DropDownList.


<Wasabi:HistoryEditBox/>

The Wasabi:HistoryEditBox is an even more specialized version of this object family, its only purpose is to remember the last 64 items of text typed into it. It has one extra parameter over Wasabi:DropDownList:

  • navbuttons - (bool) Setting this flag will include the navigation buttons on the object. Default is to have the buttons.


<componentbucket/>

The componentbucket is a fancy name for the Thinger. More precisely, in Winamp3, the "Thinger Window" is a window which implements a very simple horizontal componentbucket. The object itself may be instantiated horizontally or vertically and the scrolling of the display within it should be controlled by button objects using "cb_next" and "cb_prev" action parameters and setting the cbtarget parameter to this object. The object has the following parameters:

  • leftmargin - (int) The number of extra pixels to pad the left (or top) edge of the total component bucket scrolling display.
  • rightmargin - (int) The number of extra pixels to pad the right (or bottom) edge of the total component bucket scrolling display.
  • spacing - (int) The number of extra pixels to place between each bucket icon.
  • vertical - (bool) Whether or not the display should scroll vertically or horizontally. Default is horizontal.

A simple "thinger group" follows:

<groupdef id="some.thinger.group.thing">
	<button id="mythinger.up" x="0" y="0"
		h="20" w="0" relatw="1"
		image="mythinger.up.normal" 
		hoverimage="mythinger.up.hover" 
		downimage="mythinger.up.down"
		action="CB_PREV" cbtarget="mythinger"
	/>
	<button id="mythinger.down" x="0" y="-20"
		h="20" w="0" relatw="1" relaty="1"
		image="mythinger.down.normal" 
		hoverimage="mythinger.down.hover" 
		downimage="mythinger.down.down"
		action="CB_NEXT" cbtarget="mythinger"
	/>
	<componentbucket id="mythinger" vertical="1" x="0" y="20" w="0" h="-40" relath="1"/> 
</groupdef>


<customobject/>

The customobject is a useful tool for temporarily instantiating a group into a user interface. It has only one parameter: groupid - (id) Instantiate the specified group into my defined area. By finding your customobject in script and simply calling setXmlParam on it to give it new values for groupid, you can switch between the instantiation of multiple groups in a single user interface space.


<edit/> & <Wasabi:EditBox/>

The edit control is, as you might guess, a text entry field. Some versions of Wasabi currently embed an OS edit control into the rectangular area defined by this object. This embedded control will not blend properly with the rest of the skin's painting, it will always paint on top of everything else. Keep this in mind when developing skins for widest compatibility.

  • text - (str) Set the text in the edit field to this value.
  • action - (str) Will accept the string "mb_url" to cause this edit box to automatically send its value as an url to the main minibrowser.
  • multiline - (bool) Determines if the box is a single or multiple line input style.
  • vscroll - (bool) Causes the edit window to have a vertical scroller. Default is off.
  • autohscroll - (bool) Causes the horizontal area to scroll if necessary. Default is on.
  • autoenter - (bool) Causes the system to automatically send a "done" event when the user stops typing past a certain timeout. Default is off.
  • password - (bool) Causes the echoed characters to be single marks for password purposes. Default is off.

An edit object may be bound to a string configuration attribute.

Here's the definition of Wasabi:EditBox:

<groupdef
	id="wasabi.edit" h="20"
	inherit_group="wasabi.objectframe.group"
	xuitag="Wasabi:EditBox" embed_xui="wasabi.edit.box"
>
	<edit id="wasabi.edit.box" x="1" y="1" w="-2" h="-2" relatw="1" relath="1"/>
</groupdef>


<grid/>

The grid object is a very nice object for creating stretchable images that still look good on the edges. It is a graphic, like a layer, but unlike layer it is created by applying nine different bitmaps, stretching five of them. There are, as you might guess, nine parameters

  • topleft - (id) A bitmap element for the top left section of the grid.
  • top - (id) A bitmap element for the top middle section of the grid.
  • topright - (id) A bitmap element for the top right section of the grid.
  • left - (id) A bitmap element for the middle left section of the grid.
  • middle - (id) A bitmap element for the center section of the grid.
  • right - (id) A bitmap element for the middle right section of the grid.
  • bottomleft - (id) A bitmap element for the bottom left section of the grid.
  • bottom - (id) A bitmap element for the bottom middle section of the grid.
  • bottomright - (id) A bitmap element for the bottom right section of the grid.

Essentially, the given rectangle of the grid is intersected with 2 horizontal and 2 vertical lines. The topleft, topright, bottomleft, and bottomright bitmap elements will not be resized. The top, left, middle, right, and bottom bitmap elements, however, will be stretched to make all fit the grid rectangle. Using intelligently sized bitmap elements is fairly critical for this object. If you're having trouble, try starting with all of your bitmap elements as equal-sized squares.

Example:
<grid x="70" y="25" w="-74" relatw="1" h="20" topleft="main.text.left" top="main.text.center" topright="main.text.right"/>


<group/>

Groups are instantiated by using the group tag. Groups, when instantiated within a layout or some other groupdef, take the standard GuiObject params in order to define the group's instantiated size and properties, and then all of the contents of the group will be instantiated within the space it defines. At instantiation, a group will express a specified boundary rectangle and, thus, the positions of objects within it depending upon relative, proportional, or design coordinate systems may then be calculated.

To specify which groupdef to instantiate, set the id parameter of the group tag to the id of the desired groupdef. The instantiation of each group can be so customized, however, group instantiates also may be assigned their own custom id to allow each instantiate to be found by code or script:

  • id (id) - The groupdef to be instantiated.
  • instance_id (str) - A new id value with which to be able find this particular instantiate.

The following snippet will create two instantiates of the source group, with one specially customized (in the assumption that the "specialchild.maki" script will be handling the fact one is going to be special) :

<groupdef id="child">
	<layer image="childimg" x="0" y="0" w="0" h="0" relatw="0" relath="0"/>
</groupdef>
<groupdef id="parent">
	<group id="child" x="0" y="0" w="0" relatw="0" h="90"/>
	<group id="child" instance_id="special"
		notify="This is a special notification for this obj."
		x="0" y="90" w="0" relatw="0" h="-90" relath="1"/>
	<script file="specialchild.maki"/>
</groupdef>


<grouplist/>

A grouplist is, oddly enough, an object whose purpose is to accept and display a list of multiple groups. For instance, Wasabi's popup menu is a grouplist. A grouplist is expected to be filled in script, and it has no interesting parameters.


<layer/>

In Wasabi, the layer is analogous to the same-named object in photoshop. It is simply a nice bitmap graphic to be displayed in the user interface (with the standard alpha and region effects available to all guiobject derived objects, based by default on the properties of the bitmap element it houses). Here are its parameters:

  • image - (id) The id of the bitmap element to be used for display.
  • inactiveimage - (id) A secondary id to be displayed if this guiobject is set to "inactive" status.
  • region - (id) The id of a different bitmap element to use as the source of this object's region.
  • tile - (bool) Setting this flag will tile the image if the rectangular size of the layer is different than the rectangular size of the bitmap. The default is to stretch.
  • resize - (str) A specific string enumerating which direction one should allow the resizing of the parent layout if this object's region is gripped and dragged by the user. Incompatible with the move parameter on guiobject. See below.
  • scale - (str) A specific string enumerating which direction one should allow the scaling of the parent layout if this object's region is gripped and dragged by the user. Incompatible with the move parameter on guiobject. See below.
  • dblclickaction - (str) The string of an action to be sent into the system if this object is doubleclicked within its region.

The resize and scale parameters transform the simple layer graphic into interactive gui objects in the system by enabling them to be dragged by the user to resize or change the scale of the parent layout. The eight possible values for these parameters are "top" "left" "right" "bottom" "topleft" "topright" "bottomleft" and "bottomright." If both resize and scale are set on a single layer, the object will act as a resizer by default but as a scaler if the ALT key is held down.


<animatedlayer/>

An animatedlayer is a series of frames of sprite animation displayed in the GUI. The frames of animation are specified in the bitmap element which is given in the image parameter to this object. The animation is expected to be a specific progression of frames of a fixed size, also to be specified via parameters on the object. Each frame of animation will have its own region. The animatedlayer object inherits directly from the layer object, so all of the above parameters are valid, along with these specific to animation:

  • frameheight - (int) The height in pixels of each cell of animation. If frameheight is set, the animation will be assumed to be a vertical strip of cells in the given bitmap.
  • framewidth - (int) The width in pixels of each cell of animation. If framewidth is set, the animation will be assumed to be a horizontal strip of cells in the given bitmap.
  • elementframes - (int) The number of total frames of animation. If this value is set, the animation will be assumed to be comprised of multiple bitmap elements whose ids are resolved by using the value of the image parameter as a printf-compatible formatting string with a single integer parameter. See below.
  • start - (int) The frame index which should be used as the beginning frame of the animation. Default is the first frame of the defined animation list.
  • end - (int) The frame index which should be used as the terminating frame of the animation. Default is the last frame of the defined animation list.
  • speed - (int) The delay in ms between each frame, on average. Default is 200 ms.
  • realtime - (bool) Setting this flag will force-redraw the animation area the moment the new frame is meant to be seen. Default behaviour is to wait for and go along with the other invalidations from the rest of the UI on the main thread's draw loop. Expect use of this flag to have a high impact on system performance on slower machines. In other words, don't use it unless you know what you're doing.
  • autoreplay - (bool) Setting this flag will cause the animation to repeat to the beginning frame once it has displayed the terminating frame of animation. Default is ON.
  • autoplay - (bool) Setting this flag will cause the animation to begin playing the moment it is loaded into the user interface. Default is OFF. See below.
  • debug - (bool) Setting this flag will cause the system to draw the current frame number of the animation on top of the animation graphics, for, as you might guess, debug purposes.

You must note that animations are usually meant to be "triggered" through script, as too many live animations happily blitting their way through a deep and complex user interface using lots of alpha blending, et al, can cause significant performance bottlenecks on slow computers (especially if your users aren't expecting your application to be eating all of the machine resources). With this in mind, if you just create an animated layer and drop it into a skin, it will not begin animating unless you set the autoplay parameter.

There are three different ways to present animation frames to this object. The frames may either all be concatenated into a vertical or horizontal "filmstrip" style bitmap element -- in which case the height or width of each animation cell (respectively) should be set with the frameheight or framewidth parameter. The third way to give this object its animation frames is more complex and consists of loading multiple bitmap elements with each bitmap representing one frame of animation. This is done by first setting the elementframes parameter with the number of frames to be loaded, then by using a special formatting string as the image parameter. For those familiar with the printf function, when the elementframes parameter is set, that integer will be run in a for loop and the image name will be used as the formatting string to a printf function that takes only the current integer in the for loop as a parameter. For those unfamiliar with printf, this will seem a bit confusing. Somewhere in the string you pass to the image parameter, you should have the two characters %d, and these characters will be replaced by the character representation of the number as it loads bitmap elements. If you want to have 0-loaded prefix characters (for instance "01-09" instead of "1-9"), you can place %02d into your image parameter, and if there aren't enough characters in the number to make up 2 full digits, the number will be left-padded with the zero character. You can just as easily use any number of padding characters as well. I highly suspect this all still makes little sense, so let me give you a simplified example (missing important parameters) to show three different animated layers each loading three sets of differently named bitmaps:

<elements>
	<bitmap id="bmp1"/> 
	<bitmap id="bmp2"/> 
	<bitmap id="bmp3"/> 
	<bitmap id="bmp01img"/>
	<bitmap id="bmp02img"/>
	<bitmap id="bmp03img"/>
	<bitmap id="b00001mp"/>
	<bitmap id="b00002mp"/>
	<bitmap id="b00003mp"/>
</elements>
<groupdef id="whatever">
	<animatedlayer image="bmp%d" elementframes="3"/>
	<animatedlayer image="bmp%02dimg" elementframes="3"/>
	<animatedlayer image="b%05dmp" elementframes="3"/>
</groupdef>


<layoutstatus/>

The layoutstatus implements the small statusbar that can be found at the bottom of many of the default normal layouts which can contain status text, appcmds buttons, and a proportionally completed progress bar. The two parameters to this object control what appcmds will be allowed in the status bar:

  • exclude - (str) A semicolon delimited list of names of appcmds which should not be shown by this control.
  • include_only - (str) A semicolon delimited list of names of appcmds which will be the only appcmds allowed to be shown by this control.

For the most part, these layoutstatus objects are only controllable from code.


<list/>

The list object is similar but not identical to the Win32 list common control. It is an optionally multicolumnar list whose purpose is to display multiple pieces of information per horizontal row. It may be filled directly by encoding the contents in the XML, by attaching the object to a proper text feed, or by calling methods on the object from script. The parameters for this object are:

  • items - (str) A properly delimited string of data used to fill the list. See below.
  • multiselect - (bool) This flag, when set, allows the user to select multiple items in the list. Default is to allow multiselect.
  • autodeselect - (bool) This flag, when set, causes selection of any single item in the list to automatically deselect all other items in the list. Default is to not autodeselect.
  • select - (str) The text of a list item to be selected.
  • antialias - (bool) Setting this flag causes the text to be rendered antialiased if possible.
  • feed - (id) The id of a text feed to be used to fill this list.
  • hoverselect - (bool) This flag causes list items to be selected if the user hovers over them. Default is to not hoverselect.
  • sort - (bool) This flag causes the list to sort itself. Default is to not sort.
  • selectonupdown - (bool) This flag causes the list to interpret the keyboard commands to mean "change my selection to the item." Default is to select on keyboard events.
  • numcolumns - (int) How many columns to show. Default is one.
  • columwidths - (int) A semicolon delimited list of integers specifying how to size the column widths in this list. See below.
  • columnlabels - (str) A semicolon delimited list of strings to be used as the multiple column labels.

The list object depends upon being fed numerous strings with proper syntax in order to properly generate and populate a complex list display. The syntax for the items parameter (which is the same syntax as the feed must provide) is to delimit each full row in the list with the ';' semicolon character and to delimit each column entry per row with the ',' character. The columnwidths and columnlabels also require a semicolon (';') delimited list of data, one entry per column. Note that if -1 is given as a width, those columns will be of dynamic width and split up the leftover pixels among themselves. The default is one column with no labels and a width of -1.

Here is a sample list object with 3 rows and 3 columns:

<list id="three.by.three"
	items="row1,text,1;row2,moretext,2;row3,stilltext,3"
	numcolumns="3" columnwidths="50,-1,50"
	multiselect="0" autodeselect="1"
/>


<mouseredir/>

This object simply redirects all mouse events from its region to the target object specified in the parameter:

  • target - (id) The target object to get mouse events.

This is useful for when some objects get overlapped by nonfunctional graphics when laying out complex interfaces.


<Wasabi:RadioGroup/>

The Wasabi:RadioGroup object is an invisible object whose purpose is to centralize the functionality of multiple Wasabi:CheckBox objects instantiated in radiobutton mode. The radioid params on the Wasabi:CheckBox instantiates should give the id of one of these Wasabi:RadioGroup objects. It has no unique parameters. Here is a snippet of simple radiobutton functionality:

<Wasabi:RadioGroup id="enableddisabled"/>
<Wasabi:CheckBox x="50" y="110" w="60"
	text="Enabled" radioid="enableddisabled"
	cfgattrib="{9149C445-3C30-4E04-8433-5A518ED0FDDE};Enable desktop alpha"
	radioval="1"
/>
<Wasabi:CheckBox x="-125" y="110" w="62" relatx="1"
	text="Disabled" radioid="enableddisabled"
	cfgattrib="{9149C445-3C30-4E04-8433-5A518ED0FDDE};Enable desktop alpha"
	radioval="0"
/>


<rect/>

A nice flat rectangle. It may be either filled or hollow, and if hollow you may specify only some edges drawn. Here are its parameters:

  • color - (id) The id of a color element, or an comma delimited integer triplet RGB value. Default is "255,00,255" (an ugly color to remind you to set it).
  • filled - (bool) This flag causes the entire rectangular area to be filled with color. Default is to not be filled.
  • edges - (str) A pipe ("|") delimited set of one or all of the following: "left" "right" "top" "bottom" Default is all, ie: "left|right|top|bottom".


<script/>

Scripts allow for the simple creation of UI functionality without requiring C++ code. While scripts are "compiled" into "script binaries," these script binaries are special to wasabi and, more importantly, can be run by any compatible Wasabi runtime on any OS to which Wasabi has a runtime. Scripts are bound like GuiObjects into layout or groupdef sections using the script tag and have the ability to find and modify the nearby sibling and child objects once the UI has been fully instantiated. Scripts have two important parameters:

  • file - (str) The filename of the .maki file to load, relative to this xml file.
  • param - (str) A string that will be available to the instance of the .maki file as an instance specific parameter.

Note that a single .maki file may be instantiated as a script object numerous times over, and each instantiation can have its own specific parameter data. Judicious use of this feature can help minimize your reliance on hardcoded strings and limited flexibility in your scripting.


<slider/> & <Wasabi:HSlider/> & <Wasabi:VSlider/>

The slider object consists of a background set of images, and a thumb. The thumb is constrained to move in one dimension -- horizontally or vertically, depending upon its orientation. The distance in pixels travelled by the thumb across its total distance is interpollated to produce a value between the low and high boundary integers which is assigned to any configuration attribute which may happen to be attached. Here are the parameters for slider:

  • barleft - (id) The bitmap element for the left or top position of the slider.
  • barmiddle - (id) The bitmap element for the middle, stretched, position of the slider.
  • barright - (id) The bitmap element for the right or bottom position of the slider.
  • thumb - (id) The bitmap element for the slider thumb.
  • downthumb - (id) The bitmap element for the slider thumb when held by the user.
  • hoverthumb - (id) The bitmap element for the slider thumb when the user's mouse is above it.
  • orientation - (str) Either "v" or "vertical" to make the slider vertical, otherwise it will be horizontal.
  • low - (int) Set the low-value boundary. Default is 0.
  • high - (int) Set the high-value boundary. Default is 255.


<snappoint/>

The snappoint is an invisible point that will attract other snappoint objects with the same id in any other layout and make them want to dock, like little magnets. These objects have only the following subset of guiobject XML parameters:

  • id - (id) All snappoint objects with the same id will snap to each other. Different ids ignore each other.
  • x - (int) The x position of the snappoint, see: guiobject.
  • y - (int) The y position of the snappoint, see: guiobject.
  • relatx - (int) The horizontal coordinate space of the snappoint, see: guiobject.
  • relaty - (int) The vertical coordinate space of the snappoint, see: guiobject.


<Wasabi:TabSheet/>

The Wasabi:TabSheet object contains multiple group instances within it and allows the user to switch between the display of those groups by the ability to click on a list of tab buttons at the top of the rectangular area of the Wasabi:TabSheet. The name parameter of each groupdef is displayed as the text in the tab which corresponds to it. Here are the Wasabi:TabSheet parameters:

  • windowtype - (str) A windowtype string which will instantiate one of every groupdef with the same windowtype and every window class registered with a window creation service to include this windowtype.
  • children - (id) A semicolon delimited list of groupdef ids to also be instantiated as children of this tabsheet.
  • type - (int) There are two different themed display styles for Wasabi:TabSheet. One is with multiple tabs (sheet style), one is with a single button on top that will popup a menu with all the possible tab choices (sidecar style). The Default is sheet style, which is a value of -2. Any other value besides -2 will give you sidecar style.
  • content_margin_top - (int) A margin in pixels to offset the content from the client rectangle of the Wasabi:Tabsheet.
  • content_margin_left - (int) A margin in pixels to offset the content from the client rectangle of the Wasabi:Tabsheet.
  • content_margin_right - (int) A margin in pixels to offset the content from the client rectangle of the Wasabi:Tabsheet.
  • content_margin_bottom - (int) A margin in pixels to offset the content from the client rectangle of the Wasabi:Tabsheet.


<text/> & <Wasabi:Text/>

The text object is for using the system to render some text in the font of your choice. Since Winamp 5.5 (skinversion 1.3) text objects can have multiple lines. For a new line use this "/n"

  • display - (str) Either a specific system display string or the string identifier of a text feed. Setting this value will override the text parameter. See below.
  • ticker - (bool) Setting this flag causes the object to scroll left and right if the text does not fit the rectangular area of the text object.
  • antialias - (bool) Setting this flag causes the text to be rendered antialiased if possible.
  • text - (str) A static string to be displayed.
  • default - (str) A parameter alias for text.
  • font - (id) The id of a bitmapfont or truetypefont element. If no element with that id can be found, the OS will be asked for a font with that name instead.
  • fontsize - (int) The size to render the chosen font.
  • align - (str) One of the following three possible strings: "left" "center" "right" -- Default is "left."
  • valign - (str) One of the following three possible strings: "top" "center" "bottom" -- Default is "top."
  • color - (int) The comma delimited RGB color of the text.
  • shadowcolor - (int) The comma delimited RGB color for underrendered shadow text.
  • shadowx - (int) The x offset of the shadowrender.
  • shadowy - (int) The y offset of the shadowrender.
  • timeroffstyle - (int) How to display an empty timer: "0" = "  : ", "1" = "00:00", and "2"="" (if one is displaying time)
  • timecolonwidth - (int) How many extra pixels wider or smaller should the colon be when displaying time. Default is -1.
  • nograb - (bool) Setting this flag will cause the text object to ignore left button down messages. Default is off.
  • showlen - (bool) Setting this flag will cause the text display to be appended with the length in minutes and seconds of the current song. Default is off.
  • forcefixed - (bool) Force the system to attempt to render the display string with fixed-width font spacing.
  • forceupcase - (bool) Force the system to make the display string all uppercase before display.
  • forceuppercase - (bool) Force the system to make the display string all uppercase before display.
  • forcelocase - (bool) Force the system to make the display string all lowercase before display.
  • forcelowercase - (bool) Force the system to make the display string all lowercase before display.
  • bold - (bool) Render the display string in bold.
  • wrap - (bool) Setting this flag will cause the text to wrap in its rectangular space. Default is off.
  • dblclickaction - (str) A string in the form "SWITCH;layout" where layout is the id of a layout in this object's parent container. No other actions function on this object. This action is deprecated.
  • offsetx - (int) Extra pixels to be added to or subtracted from the calculated x value for the display string to render.
  • offsety - (int) Extra pixels to be added to or subtracted from the calculated x value for the display string to render.
"SONGNAME" 		- The name string of the currently playing song (from metadb).
"SONGINFO" 		- The full info string of the currently playing song (from metadb).
"SONGARTIST" 		- The artist string of the currently playing song (from metadb).
"SONGTITLE" 		- The title string of the currently playing song (from metadb).
"SONGALBUM" 		- The album string of the currently playing song (from metadb).
"SONGLENGTH" 		- The length string of the currently playing song (from metadb).
"TIME" 			- The length string of the currently playing song.
"TIMEELAPSED" 		- The elapsed time string of the currently playing song.
"TIMEREMAINING" 	- The time remaining string of the currently playing song.
"COMPONENTBUCKET" 	- The id of the componentbucket (thinger) item the mousecursor is currently hovering above.
"SONGBITRATE" 		- The bitrate string of the currently playing song (from metadb).
"SONGSAMPLERATE" 	- The sample string of the currently playing song (from metadb).

*** Broken Action (Winamp 5) ***
"NORMALIZER:STATUS" 	- The current status of the audio normalizer.
Example:
<text x="81" y="11" w="25" h="21" antialias="0" text="Read This" align="center" color="0,0,0" bold="1"/> 


<Wasabi:TitleBox/>

The Wasabi:TitleBox object is a nice way to put a simple rectangular frame and title around your content groups. It has the following parameters:

  • title - (str) The string to display in the title area. Default is to use the name parameter of the content group.
  • content - (id) The id of the groupdef to instantiate as content.
  • centered - (bool) Setting this flag will center the title text. Default is to not be centered (and be left justified).
  • suffix - (str) A string which will be appended to the title before it is displayed. In this way, if you instantiate multiple groups as content, each name change can still have a string appended.


<Wasabi:Titlebar/>

The Wasabi:TitleBar is the graphically themed bar that is placed at the top of all of the Wasabi:StandardFrame windows. It has the same parameters as the text object, which control the text display of the titlebar.


<tree/>

The tree object displays a hierarchical set of information with multiple items, where each item may in turn have multiple subitems. Let's examine its parameters:

  • items - (str) A specially formatted string describing the hierarchical creation of the tree info. See below.
  • feed - (str) The string identifier of a text feed which should provide a string in the same format as the items parameter.
  • sorted - (bool) Setting this flag will cause all of the tree items to be sorted before display. Default is to sort.
  • childtabs - (bool) Setting this flag will cause all tree items with children to display a tab graphic beside them. Default is to show tab graphics.
  • expandroot - (bool) Setting this flag will cause all root tree items to display with their children pre-expanded. Default is to pre-expand root tree items.

The syntax required to describe the hierarchy of tree items is a semicolon delimited list of objects in the form "name(list)" where name is the string to display for that tree item and list is another semicolon delimited list of objects which are the direct children of name.

The following snippet will create a tree with one root node that has three child nodes, with each child node having differing numbers of sub nodes:

<tree id="example.tree"
	x="0" y="0" w="0" h="0" relatw="1" relath="1"
	items="root(child1(sub1;sub2);child2;child3(sub3))"
/>


<vis/>

The vis object is the multistate audio visualization display. It has a multitude of parameters for how simple it is:

  • colorallbands - (int) The comma delimited RGB triplet to color all the spectroscope bands.
  • colorband1 - (int) The comma delimited RGB triplet to color spectroscope band 1.
  • colorband2 - (int) The comma delimited RGB triplet to color spectroscope band 2.
  • colorband3 - (int) The comma delimited RGB triplet to color spectroscope band 3.
  • colorband4 - (int) The comma delimited RGB triplet to color spectroscope band 4.
  • colorband5 - (int) The comma delimited RGB triplet to color spectroscope band 5.
  • colorband6 - (int) The comma delimited RGB triplet to color spectroscope band 6.
  • colorband7 - (int) The comma delimited RGB triplet to color spectroscope band 7.
  • colorband8 - (int) The comma delimited RGB triplet to color spectroscope band 8.
  • colorband9 - (int) The comma delimited RGB triplet to color spectroscope band 9.
  • colorband10 - (int) The comma delimited RGB triplet to color spectroscope band 10.
  • colorband11 - (int) The comma delimited RGB triplet to color spectroscope band 11.
  • colorband12 - (int) The comma delimited RGB triplet to color spectroscope band 12.
  • colorband13 - (int) The comma delimited RGB triplet to color spectroscope band 13.
  • colorband14 - (int) The comma delimited RGB triplet to color spectroscope band 14.
  • colorband15 - (int) The comma delimited RGB triplet to color spectroscope band 15.
  • colorband16 - (int) The comma delimited RGB triplet to color spectroscope band 16.
  • colorbandpeak - (int) The comma delimited RGB triplet to color the spectroscope peak line.
  • colorallosc - (int) The comma delimited RGB triplet to color the whole oscilloscope.
  • colorosc1 - (int) The comma delimited RGB triplet to color oscilloscope section 1.
  • colorosc2 - (int) The comma delimited RGB triplet to color oscilloscope section 2.
  • colorosc3 - (int) The comma delimited RGB triplet to color oscilloscope section 3.
  • colorosc4 - (int) The comma delimited RGB triplet to color oscilloscope section 4.
  • colorosc5 - (int) The comma delimited RGB triplet to color oscilloscope section 5.
  • channel - (int) One of three values for which channel to monitor: "1" is left channel, "2" is right channel, "3" is stereo. Default is stereo.
  • fliph - (bool) If this flag is set, it blits the vis pixels flipped horizontally.
  • flipv - (bool) If this flag is set, it blits the vis pixels flipped vertically.
  • mode - (int) One of three values for which mode to display: "0" is no display, "1" is spectroscope, "2" is oscilloscope. Default is to read from a config item.

When the user clicks on the vis, it will cycle between its three modes.


<eqvis/>

The eqvis object is rather specific to media players, as it is the spline display for the eq settings in the Wasabi Media Player.

  • colortop - (str) A color value or color element id for the top portion of the spline display.
  • colormiddle - (str) A color value or color element id for the middle portion of the spline display.
  • colorbottom - (str) A color value or color element id for the bottom portion of the spline display.
  • colorpreamp - (str) A color value or color element id for the preamp bar in the spline display.


<gradient/>

The gradient object creates a rectangular color gradient. The available parameters are:

  • gradient_x1 - (float) A floating point value for the left side of the rectangle. Default is 0.0
  • gradient_y1 - (float) A floating point value for the top side of the rectangle. Default is 0.0
  • gradient_x2 - (float) A floating point value for the right side of the rectangle. Default is 1.0
  • gradient_x1 - (float) A floating point value for the bottom side of the rectangle. Default is 1.0
  • points - (str) A complex string defining color values for at least two value points with which to build the gradients. See below.

The points syntax is a semicolon delimited list of key=value pairs where the key is a floatingpoint number representing a point in the "gradient space" and the value is an RGB triplet (assumed full alpha) or RGBA quad. For instance, the following object would create a smooth gradient between red in the top left and green at half alpha in the bottom right:

	<gradient id="red.to.green"
		x="0" y="0" w="0" h="0" 
		relatw="1" relath="1"
		points="0.0=255,0,0,255;1.0=0,255,0,128"
	/>


<Wasabi:StandardFrame:Status/>

<Wasabi:StandardFrame:NoStatus/>

<Wasabi:StandardFrame:Modal/>

<Wasabi:StandardFrame:Static/>

The Wasabi:StandardFrame objects are rectangular frames you can use to encapsulate your own layout contents within the currently themed standard frame. They all have the following parameters:

  • content - (id) The id of the groupdef to instantiate within the Wasabi:StandardFrame.
  • padtitleleft - (int) The distance in pixels to pad the title to the left.
  • padtitleright - (int) The distance in pixels to pad the title to the right.
  • shade - (id) The id of the layout within our container we should switch to if the titlebar is doubleclicked (ie: the id of the windowshade layout). Default is no functionality.

The Wasabi:StandardFrame:Status object has a status bar, while the Wasabi:StandardFrame:NoStatus does not. The Wasabi:StandardFrame:Static object inherits from Wasabi:StandardFrame:NoStatus and also instantiates the wasabi panel graphics. The Wasabi:StandardFrame:Modal object does all that and also removes the control menus to make a fully modal dialog frame.


<wndholder/>

A wndholder object, similar to a customobject, holds user interface windows based upon what param is given. The wndholder can also hold window types by guid or groupdef instantiations by id. Here are its parameters:

  • hold - (id) A semicolon delimited list of guids or groupdef ids to hold.
  • component - (id) A parameter alias for hold.
  • param - (id) A parameter alias for hold.
  • noshowcmdbar - (bool) Setting this flag will disable the Wasabi command bar.
  • noanimatedrects - (bool) Setting this flag will disable animated rectangle motion.
  • disableanimatedrects - (bool) A parameter alias for noanimatedrects.
  • autoopen - (bool) Setting this flag will cause the object to auto open.
  • autoclose - (bool) Setting this flag will cause the object to auto close.

Using a wndholder object indicates to the system that you want to be the "container of record" for the possible requested guids when they are launched by the system through, for instance, the C++ coder registering his window class with registerAutopopup(), which calls the underlying api->skinwnd_createByGuid(). The container within which this wndholder is instantiated should also be given a component parameter with the same values. This component parameter is simply a hint to Wasabi that a wndholder object that will accept that component parameter lives within the container.


<objdirview/>

The objdirview object displays a tree of hierarchical information to the user, based on a code concept called an Object Directory. An Object Directory is, in essence, just a container of arbitrary items so this object is merely the display of its contents. Here are its parameters:

  • dir - (str) The string identifier of the objdir to which this object should connect.
  • target - (id) The id of an object to which this object may direct the actions of its internal items being selected.
  • displaytarget - (id) The id of a customobject which will be assigned to display the display group parameter of the currently selected objdir item.
  • defaultdisplay - (id) The id of a groupdef to display inside displaytarget if no objdir items are selected.

When items in the objdirview are selected, the objdir is sent an event telling it that an item was selected. The target parameter from XML is included in the data sent in that event. However, the implemented functionality for that event is wholly at the discretion of the programmer implementing the specific objdir in question. For the QueryDir object used in Winamp3's media library, the target param is for a nearby queryline object to be told the selection is changing. Your mileage may vary with other objects.


<Wasabi:PathPicker/>

The Wasabi:PathPicker object is a simple object to display a text string of a directory path chosen by the user. When the user clicks on the object, a dir selection service is started, allowing the user to choose a directory path. Attach this object to a string configuration attribute and you have a simple way for users to choose directories as preferences. The Wasabi:PathPicker object has no unique parameters.


<querydrag/>

The querydrag object is used to create a visual "drag source" for a nearby queryresults object. The user may click and drag this object and by doing so representationally drag the text of the current query in the queryresults object (which can be dropped into a playlist editor to fill its contents with the results of that query). It has only two parameters:

  • image - (id) The bitmap element to display.
  • source - (id) The source queryresults object. Default is the nearest.

If no valid source can be found, this object silently fails to drag.


<queryline/>

The invisible queryline object is used to host a text query to be applied to a queryresults object. One possible use would be to write a script linking the text in a Wasabi:HistoryEditBox to the query parameter of a queryline. And, speaking of its parameters, here they are:

  • querylist - (id) The id of the queryresults which will take the query. Default is to not connect (ie: this param is kinda sorta mandatoryish if you want anything interesting to happen).
  • query - (str) The string of the query itself.
  • auto - (bool) Whether or not to execute an autoquery based on the query parameter (ie: "search on the name column for this substring" instead of "run this query"). Default is to use the string directly as a query (not autoquery).


<queryresults/>

The queryresults object is the an invisible binding object that coordinates the filtration of the database by numerous multiple other objects. The queryline and filterlist objects eventually define a single output from the database, and this information is kept in the queryresults object. It has only one parameter: title - (str) The human readable title for your queryresults. I have no idea why this would be important. Magically, it seems, placing a queryresults object in the same group next to a PlaylistEditor object makes that PlaylistEditor get filled with the queryresults information. I have no idea how this can be, and sense the telltale signs of powerful dark necromancy at work, here.