Menus and Popups
This tutorial assumes you are familiar with the basic buildup of SiteFusion applications, as described in previous tutorials.The Menubar
Menus are handled very differently between platforms. Windows and generally Linux too show menubars inside the window, while Mac has a system menubar that contains the menu of the active application and window:
XUL provides the menubar element, which translates the menu elements underneith it to the native representations of the operating system. The menu element can contain a menupopup element, which in turn contains menuitem, menuseparator and possibly more menu elements.
These elements are represented by the XULMenuBar, XULMenu, XULMenuPopup, XULMenuItem and XULMenuSeparator classes in PHP. For example, a simple menubar with two menus looks like this:
<?php
$menubar = new XULMenuBar(
new XULMenu( 'File',
new XULMenuPopup(
new XULMenuItem( 'Open...' ),
new XULMenuItem( 'Save' ),
new XULMenuSeparator,
new XULMenuItem( 'Close' )
),
),
new XULMenu( 'Edit',
new XULMenuPopup(
new XULMenuItem( 'Cut' ),
new XULMenuItem( 'Copy' ),
new XULMenuItem( 'Paste' ),
new XULMenuSeparator,
new XULMenu( 'Find',
new XULMenuPopup(
new XULMenuItem( 'in this file...' ),
new XULMenuItem( 'in this project...' )
)
)
)
)
);
In Mac OS X, some system default menu items will be added automatically, like this 'Special Characters' item in the Edit menu.
The XULMenuItem constructor can take five parameters, all of them strings. Because of that, if you want to set one of these parameters in the constructor, make sure to supply the ones before it as empty strings:
<?php
// The parameters that you can supply to the constructor are:
// label, value, type, name, image
// Just set the label and image
$item = new XULMenuItem( "I'm an item",
'', '', '', '/app/testapp/image.png' );
// A set of two radio buttons
$item1 = new XULMenuItem( 'Male', 'male', 'radio', 'gender' );
$item2 = new XULMenuItem( 'Female', 'female', 'radio', 'gender' );
// A checkbox item
$checkitem = new XULMenuItem( 'Automatically check for updates',
'', 'checkbox' );
// Make it checked
$checkitem->checked( TRUE );
Menu items can also act as checkboxes or radio buttons, as shown above. This can also be done through the XULMenuItem::type() method which sets the type attribute on the element. The state of these menuitems can be set and retrieved through the XULMenuItem::checked() method. They yield themselves on the command event by default, so that you don't have to set yielding manually.
Menulists
A menulist, or dropdown, is one of the most used input elements. This control is represented by the menulist XUL element, and the XULMenuList class in SiteFusion. A XULMenuList object should always contain a XULMenuPopup element, which represents the popup shown when the control is activated (like in the menu example above). This popup then should contain the XULMenuItem objects representing the various options. As shown above, the XULMenuItem constructor takes a 'value' parameter, which is meant to hold an arbitrary string. When the menulist is yielded, it will contain the value of the selected menuitem in the XULMenuList::$selectedValue property, and a reference to the selected XULMenuItem object in the XULMenuList::$selectedItem property. The XULMenuList::selectItem() method (or its alias XULMenuList::selectedItem()) can be used to set the selected value. This can be done in various ways, as shown below:
<?php
$menulist = new XULMenuList(
new XULMenuPopup(
$item1 = new XULMenuItem( "Item 1", "foo" ),
$item2 = new XULMenuItem( "Item 2", "bar" )
)
);
// Select by item reference
$menulist->selectItem( $item2 );
// Select by value
$menulist->selectItem( 'bar' );
// Select by index
$menulist->selectItem( 1 );
Context menus, popups and tooltips
A context menu is just like any other popup. Popups are represented by the XUL elements menupopup, panel and tooltip. A menupopup is a popup that holds menuitems, while a panel is a more general popup that holds any kind of content. A tooltip is the familiar yellow balloon that is used to explain certain features of an application. If you just want a simple text as a tooltip, you don't need the tooltip element. Just call Node::tooltiptext( $text ). Context menus, popups and tooltips are usually grouped inside a XULPopupSet element, although this is not mandatory anymore. To have these elements appear in the user interface, use the following methods:- Node::context( $popupNode ) - call this method to have the popup in $popupNode appear when the user right-clicks the node that the method is called on.
- Node::tooltip( $popupNode ) - call this method to have the popup in $popupNode appear when the user hovers the node that the method is called on.
- Node::popup( $popupNode ) - call this method to have the popup in $popupNode appear when the user left-clicks the node that the method is called on.