Say Hello ▶

New Toolbar and ToolbarButton Components

May 3, 09

If you are planning on creating any applications for amoebaOS, we've just finalized four two interface elements that will be available to you in the release (another 2 will be announced soon). These two components are both inherited from the Panel component, so their basic structures are very similar. First, let's explore the Toolbar component.
The Toolbar component is a stylized block-level interface element used for holding the most important menu items at the top of an application's interface. Be default, a Toolbar is a drag-able surface that spans the width of the window and allows the user to move the window around their desktop. If not explicitly set, the Toolbar's height will automatically adjust to fit it's contents. The object accepts one parameter, which specifies the the size of all contained ToolbarButton icons - either "large" (the default), "medium" or "small". These sizes are defined by the window theme and should not be hard coded. It is important to note that all applications should be able to accommodate both large and small Toolbars, because the size you define can be overridden by the user's global setting if they choose. In creating the Toolbar object, we wanted to duplicate the simplicity of adding child components that is already available through Panels, so the method for adding a component to any Toolbar would be:

var toolbar = new app.Controls.Toolbar();
app.Controls.Add( toolbar );

var button = new app.Controls.ToolbarButton();
toolbar.Controls.Add( button );

Or, if you prefer:

var toolbar = new app.Controls.Toolbar();
var button = new app.Controls.ToolbarButton();

app.Controls.Add( toolbar );
toolbar.Controls.Add( button );

As with all controls, the consecutive (first) method is inherently more optimized than the stacked (second) method. The size of a Toolbar (ie, the size of all contained icons) can be changed after creation using the .setSize() method, and can be retrieved using the .getSize() method (these methods accept and return the same three values from the size parameter).

As you can see above, another new component has been introduced with the new Toolbar - the ToolbarButton. This control is a specialized Button that allows you to specify both an icon and text, and is included in order to keep toolbars clean and quickly readable. Here is a basic overview of the ToolbarButton object:
  • Parameters
    • String :: label
      • The text to display below a button's icon
    • String :: icon
      • The URL of an icon - remember to use System.Resource(filename) for all images
    • Function :: onload  or  Array :: onload
      • A function (or an array of functions) to execute when the icon loads successfully. The function(s) will be called in this form:
        • onload( ToolbarButton::control , Boolean::loaded , String::iconUrl )
      • Note: All functions are called as methods of the ToolbarButton object, so the "this" keyword refers to the control itself.
    • Function :: onerror  or  Array :: onerror
      • A function (or an array of functions) to execute if the icon fails to load. The form is identical to the onload function.
      • Note: The onload and onerror functions can be the same. You can use the second parameter to determine which has been called.
      • Note: All functions are called as methods of the ToolbarButton object, so the "this" keyword refers to the control itself.
  • Methods:
    • setText or setLabel
      • parameter:  String::text
      • Sets the text for the button label
    • getText or getLabel
      • Returns the button's label text
    • setIcon or setImage
      • parameter:  String::iconUrl
      • Change the URL of the icon. Remember to use System.Resource(filename) for all images
        • Note: All onload and onerror functions for the ToolbarButton remain active and will be fired when the icon loads or fails to load. This includes both functions you can define when you create the object.
    • getIcon or getImage
      • Returns the button's icon URL
  • Properties:
    • String :: text
      • The current button label text. Use getText() or getLabel() instead.
    • String :: src
      • The current button icon URL. Use getIcon() or getImage() instead.
    • Bool :: loaded
      • true if the most recent icon change loaded successfully, false if it generated an error.
    • Bool :: error
      • true if the most recent icon change generated an error, false if it loaded successfully.
  • Event Registries:
    • Note: Event Registries are just standard arrays. You can add and remove event handlers from these arrays using Array.push() and Array.splice().
    • Array :: onload [ function( ToolbarButton::this ){} ]
      • Functions to execute when icon loads
    • Array :: onerror [ function( ToolbarButton::this ){} ]
      • Functions to execute when icon fails to load
    • Array :: onclick [ Bool::function( Event::e , ToolbarButton::this ){} ]
    • Array :: onmousedown [ Bool::function( Event::e , ToolbarButton::this ){} ]
    • Array :: onmouseup [ Bool::function( Event::e , ToolbarButton::this ){} ]
    • Array :: onmousemove [ Bool::function( Event::e , ToolbarButton::this ){} ]
    • Array :: onmouseover [ Bool::function( Event::e , ToolbarButton::this ){} ]
    • Array :: onmouseout [ Bool::function( Event::e , ToolbarButton::this ){} ]
      • Event handlers for the click, mousedown, mouseup, mousemove, mouseover and mouseout events. The "e" parameter is a standard JavaScript event object.
      • All mouse events are triggered when the corresponding action is performed anywhere within the ToolbarButton's bounding box.
      • A return value of false will prevent the event from bubbling up to parent Controls, and will override all global events.

So there you have it. Toolbar and ToolbarButtons are now available in amoebaOS apps.

About :

Leave a Comment

Post Comment