Difference between revisions of "XML Containing objects"

From Winamp Developer Wiki
Jump to: navigation, search
m (Reverted edits by Iseficibuw (Talk) to last version by Pjn123)
m (: Added ontop)
 
Line 36: Line 36:
 
* '''resizable''' - (bool) Can be set to "0" to disable user resizing
 
* '''resizable''' - (bool) Can be set to "0" to disable user resizing
 
* '''scalable''' - (bool) Can be set to "0" to disable user scaling (experimental)
 
* '''scalable''' - (bool) Can be set to "0" to disable user scaling (experimental)
 
+
* '''ontop''' - (bool) Force layout to be always visible
  
 
==<groupdef></groupdef>==
 
==<groupdef></groupdef>==

Latest revision as of 20:18, 9 October 2012

Description

These are the objects, that contain other objects.


<WasabiXML></WasabiXML>

This object contains the whole skin.

  • version - (int) The version of the Freeform Plugin Core the skin is made for. If the Plugin version is less than written, the warning "The skin is too new" will appear. Othervise, the Plugin will read the code according to this value, using backward compability.


<container></container>

  • id - (id) The coder-oriented name of the container. This value is used when appealing to this object.
  • name - (str) The human-oriented name of the container, or the "title" of the "window." This value is used by some other GuiObjects, notably the Wasabi:TitleBar object, to be displayed in the system. It does not display automatically. The special string ":componenttitle" will query the contents of the container to find the first windowholder and replace the name assigned to this container with the name of the object held by the windowholder (if any).
  • default_x - (int) The default x position in screen coordinates.
  • default_y - (int) The default y position in screen coordinates.
  • default_w - (int) The default width in scalable units (1 == 1 pixel, if scale==100%)
  • default_h - (int) The default height in scalable units (1 == 1 pixel, if scale==100%)
  • default_visible - (bool) If true, show this container the first time the skin is ever shown (the system will track this value for the user, thereafter).
  • component - (str) If this parameter is set with a guid or groupid, it indicates to the system that inside this component there lives a wndholder object with the same parameter.
  • dynamic - (bool) If true, this means that when the skin is parsed, the container is not created. "Dynamic" containers are meant to be instantiated at runtime by the coder and act as a template to hold any type of content within them. Winamp3 uses dynamic containers to, for instance, provide outer frames for component windows, message boxes, etc. A dynamic container is instantiated when the coder requests it to be, and deleted when the layout is closed. If false (ie: not dynamic), this container will always be instantiated in the system at runtime, and the coder may only "hide" and "show" it.
  • primaryComponent - (String) Defines the primary comonent that should be hold in this container. Useful for SUI Skins in combination with primaryComponent="guid:player" in order to recieve keyboard/mouse actions in our main window.
  • canclose - (bool) Defines if the container can be closed (true) or not (false).
  • nofocusapponclose - (bool) If this Container is closed the main application (Winamp) can be restored from minimized state (true) or not (false).


<layout></layout>

  • id - (id) The coder-oriented name of the layout. This value is used when appealing to this object.
  • owner - (str) This parameter has the special syntax of "componentid;layoutid" and will cause the OS window this layout represents to always match the current visible state (minimized, restored, etc) of the owning layout.
  • lockto - (str) This parameter has the same syntax as owner, but causes the relative positioning of this window to be locked to the position of the owning layout. If it moves, the owned layout moves along with it.
  • alpha - (int) This 0-255 integer parameter represents the flat alpha to be applied to the entirety of the layout.
  • desktopalpha - (bool) If true, this flag indicates to Wasabi that this layout would like to be drawn with desktop alpha, if that feature is enabled in the system.
  • indesktop - (bool) If true, causes the OS window to be a child of the desktop (under all other OS windows).
  • linkwidth - (str) This string parameter should be the layoutid of a sibling to this layout inside its container. Any changes to the width of this layout will be applied to the linked layout. One use is for a "windowshade" mode that automatically matches width to the "normal" layout.
  • linkheight - (str) Same as linkwidth, but for height. Will allow you to make "vertical" windowshades, should you so desire.
  • taskbar - (bool) This flag causes the layout to have its own taskbar button. (NOT YET IMPLEMENTED!)
  • move - (bool) Can be set to "0" to disable user moving. Useful for maximized mode.
  • resizable - (bool) Can be set to "0" to disable user resizing
  • scalable - (bool) Can be set to "0" to disable user scaling (experimental)
  • ontop - (bool) Force layout to be always visible

<groupdef></groupdef>

Groups are the workhorse of user interface design in Wasabi. Groups allow one to define and place in coordinate space a logical collection of GuiObjects that will live within a given rectangle (the boundary of the Group). They are the display-cases in which one keeps one's interface items tidily available to the user. The XML params specific to all groupdefs are:

  • background - (str) The id of a bitmap element to be stretched as the background of the group (all of the group contents draw on top of this bitmap)
  • drawbackground - (bool) Whether or not to actually draw the background pixels (useful for using the alpha channel of a background bitmap as the drawing region for the group).
  • default_w - (int) The default width for this group, if the group instantiation does not specify what the width should be.
  • default_h - (int) The default height for this group, if the group instantiation does not specify what the height should be.
  • maximum_w - (int) The maximum width for this group, beyond which Wasabi will not allow the group to be resized.
  • maximum_h - (int) The maximum height for this group, beyond which Wasabi will not allow the group to be resized.
  • minimum_w - (int) The minimum width for this group, beyond which Wasabi will not allow the group to be resized.
  • minimum_h - (int) The minimum height for this group, beyond which Wasabi will not allow the group to be resized.
  • propagatesize - (bool) Sends this group's default/minimum/maximum size parameters to the layout which contains the group. ie: if my minimum_h is 200 and my containing layout's minimum_h is 100 and I have my propagatesize flag set, my layout will now have a * minimum_h of 200, etc.
  • lockminmax - (bool) Locks the minimum and maximum size values to the default size value. Makes the group "nonresizable."
  • design_w - (int) The "design width" of this group. The "design" based sizes allow for a conditional layout of GuiObjects within them. These parameters are used in conjunction with the x1/x2/y1/y2/anchor coordinate system, which will be documented with GuiObjects.
  • design_h - (int) The "design height" of this group.
  • name - (str) A human readable string which will be the "Name" of this group, used by various objects in the system when referring the user to this groupdef. For instance, the TabSheet GuiObject contains one group for each displayed tab, and the name parameter of each group is the string displayed within each corresponding tab.
  • autowidthsource - (str) The id of an object contained within this group from which this group should set its width. For instance, the groupdef that defines the contents of the Checkbox GuiObject sets its width based on the size of the text object within it, which itself will be sized at instantiation depending upon the text placed within that particular text object (See: $/studio/studio/Wacs/wasabi.system/ui/guiobjects/xml/checkbox/checkbox.xml).
  • autoheightsource - (str) The id of an object contained within the group from which this group should set its height.
  • register_autopopup - (bool) This flag causes this group to be listed in the Windows submenu of the Wasabi MainMenu context menu. Its name parameter is displayed as the menu item. If that menu item is then selected, this group will be launched as a layout (in other words, in its own window). This is quite useful for the quick debugging of groupdef objects.
  • windowtype - (str) Specifying a groupdef as being a certain windowtype causes the group to automatically be instantiated and added to the collection specified by that windowtype. See below for more information and a list of what windowtypes currently exist in the system.
  • inherit_content - (bool) This parameter is used to be able to override the contents of a group already defined in the system. To go back to the "blueprints" analogy, this is like finding someone's original blueprints and editing them. The id of this groupdef should match the id of the other groupdef that you wish to modify. See below for examples and more information.
  • inherit_group - (str) This parameter is used to be able to copy the contents of a group already defined in the system as the starting point for one's own group definition. To go back to the "blueprints" analogy, this is like photocopying someone else's blueprints as a starting point for one's own. The param is the id of the other groupdef you wish to inherit.
  • inherit_params - (bool) Specifies whether or not to inherit the params of the inherited group as well as its content. Only meaningful with a valid inherit_group param or if overriding a previous groupdef.
  • xuitag - (str) Specifies that this group definition will create a new Xui object into the system with the given tag string. See Extending Wasabi: Creating XuiObjects for more information.
  • embed_xui - (str) Specifies the id of a contained object to which any XML parameters not valid for a group sent to the instantiation of the group (or the xuitag string) should be forwarded. See Extending Wasabi: Creating XuiObjects for more information.

In addition to these parameters, all parameters that apply to a GuiObject may also be placed on a groupdef. This sets them up as default parameters for when the group is used in a group tag, which the skinner may of course override.

Please note, as referenced earlier, the layout object is simply a special type of groupdef object, so all of these parameters also apply to it as well.

Groups are inherently reusable objects, as well. In a process that object oriented programmers should be well familiar with, Groups are first Defined to contain their particular contents and then can be later Instantiated (multiple times, if so desired) within a user interface.

For the non-programmers among our readers, consider the following analogy: Definition consists of making a set of instructions for how to create something, like the blueprints for a house. Instantiation is the process of creating that something based upon its definition: in this case, giving the blueprints to a General Contractor and waiting the requisite indeterminate number of weeks to have them build that house to your specification. Definition makes a concept. Instantiation converts it into a thing.

Now imagine the vast expanse of cookie-cutter housing tracts that have proliferated across American suburbia in the past decades. In a single tract, only a small handful of different blueprints were Defined for building the hundreds of homes to be found, and each Instance of those designs has been personalized by its denizens (subject to the CC&R's for that neighborhood, of course).

In the same way, you may define a Group to contain a specific set of objects with a specific set of parameters (your "instructions"), and then use ("instantiate") that Group over and over again in your user interface with minor tweaks to each usage ("instance").

The XML tag Wasabi uses for Group Definition is the groupdef tag, while the tag used for Group Instantiation is the group tag. This section will deal specifically with the particularities of Group Definition and the parameters of the groupdef tag, while the group tag will be documented in its own section in the next chapter (along with everything else that is meant to live inside of a groupdef tag). Because the simplest form of a groupdef is rather boring, we'll first cover the parameters for groupdefs and then return to creating sample XML snippets somewhat more complicated and useful than the following (which defines "my group" as merely an instantiation of the contents of "othergroup")

<groupdef id="mygroup">
	<group id="othergroup"/>
</groupdef>