Class MacaoMenu

The class MacaoMenu is used to display a number of buttons to the user. A button can consist of an image and/or text.

Adding a Menu

Create a MacaoMenu object to add a menu to your page. Because the class MacaoMenu is inherited from MacaoObject, you can use the methods of MacaoObject for example to manipulate the position of the menu and to send events to the menu.

Adding Menu Items

Menu items can be created by adding objects of the Type MacaoMenuItem using the method addMenuItem(). Each menu item needs to have a unique name within a menu. You can use the method getMenuItem() to get a menu item by its name.

When you create a menu item, you need to define an event. When the user clicks on the menu item, the event is executed.

Menu Item Types

Menu items can be set as toggle items or as radio items.

A toggle item is activated or deactivated, when the user clicks the item. You can display the different activation status of the item by providing a special image or CSS style for the active state of the item. Use MacaoMenuItem.setActivation() to set the item as toggle item. Use the method MacaoMenuItem.isActivation() to test, if the item is a toggle item. Use the method MacaoMenuItem.setActive() to change the state of the item.

A radio item is similar to a toggle item. But if one radio item is set to active, all other radio items of the menu are set to inactive. There can only be one radio item set at a menu. Use MacaoMenuItem.setActivation() to set an item as radio item. Use the method MacaoMenuItem.isRadio() to test, if an item is a radio item. Use the method MacaoMenuItem.setActive() to change the state of the item.

When an item is activated or deactivated, the event, which has been defined for the item, is send. But for the parameters of the event, there is send only one Boolean parameter. The parameter is true, if the item has been activated and false, if the item has been deactivated.

Positioning Menu Items

All menu items are added to an HTML table in the menu item object. The shape of the table can be defined by calling the method setMenuCharacteristics(). The parameter maxColumnCount defines the number of columns of the table. Setting this parameter to 1 will place all items in a column. Setting this parameter to a large value like 100 will place all items in a row.

Currently you cannot remove a single menu item. You can only hide it using the method setMenuItemVisibility(). If you have placed all items in one row or one column, hiding one item will collapse the table cell. But when you use a table of two or more rows or columns, the menu items in another row or column may prevent the cell with the hidden content from being collapsed.

You can call the method MacaoMenuItem.setAbsolutePosition() to place a menu item to an absolute position at the page. If you place all menu items to an absolute position, the enclosing table will still be there, but it will be empty.

Defining the Item Style

You can define a different view for a menu item, which is displayed when the user moves the mouse over the item or when the item is activated. Use the constructor MacaoMenuItem() or the method MacaoMenuItem.setImageSource() to define different images. The cascading style sheet classes are named automatically. So you can define the styles for the menu items in a HTML style element in your page or in an external CSS file. The CSS class names, which are assigned to the menu and the menu items are the following: MenuNameMenu: For the HTML elements of the menu, which are not belonging to menu items. This is the table of the menu, consisting of the HTML elements table, tr and td.
MenuNameMenuItem: For an not activated menu item, when the mouse is not over the menu item.
MenuNameMenuItemActive: For an activated menu item or a menu item, which is currently clicked.
MenuNameMenuItemMouseOver: For a menu item while the user moves the mouse over the menu item.
Replace MenuName by the name of the menu object. Each menu item is enclosed in a div HTML element. The text of a menu item is enclosed in a span HTML element. The image is an img HTML element. You can use these elements to define the CSS style for a specific part of a menu item.

The example shows a CSS style definition for a menu, which is named MyMenu.

<style>
.MyMenu {
	background-color: black;
}

.MyMenuItem,
.MyMenuItemActive,
.MyMenuItemMouseOver {
	font-family: Comic Sans MS, Arial, Helvetica, sans-serif;
	font-size: 10pt;
	font-weight: bold;
	color: white;
}

div.MyMenuItem,
div.MyMenuItemActive,
div.MyMenuItemMouseOver {
	padding: 2px;
	text-align: center;
}
div.MyMenuItemMouseOver {
	background-color:green;
}
</style>

The example defines the styles in a style element, which can be put to an HTML page. For the entire menu the background color is set to black. The menu items use the same font regardless, if they are activated or moused. The padding, which is the distance between the content of the item and its box, is only defined for the div element of the menu items. If it would be defined for all elements of that CSS class, the image and the text of the menu item would get an extra distance. When the mouse is moved over a menu item, the background color changes to green. I experienced, that it is causing slower performance to change the background color than to change the image. So for a better performance, I recommend to provide an additional image rather than changing the background color. See the description of the MacaoMenuItem to see the structure of the menus HTML.

A Menu Example

The following example creates an application using a frameset with two frames. The content frame contains a character with the name Hero. The frame 'controllers' contains a menu with the name MyMenu. The menu has the items Hello and Bye. They are sending the event hearEvent to the car with the parameters "Hello" and "Bye" as trigger events. There are added MacaoTalkItem objects to the Hero, which are responding to the trigger events.

This is the source code for the content page:

// create the hero
var hero = new MacaoObject("Hero", "Arnold", 200, 200)

// set the image of the hero
hero.setImage("examples/menu/hero.gif", 32, 32)

// add the talk items that are triggered by the menu items
hero.createTalkItem("Hero_Hello", "Hello", "Hello world!")
hero.createTalkItem("Hero_Bye", "Bye", "Good bye.")

This is the source code for the menu page:

// create the menu
var menu = new MacaoMenu("MyMenu", null, 20, 20)

// set two columns, hide images, show text
menu.setMenuCharacteristics(2, false, true)
	
// add the menu items with the events
menu.addMenuItem(
	new MacaoMenuItem(
		"Hello", "Hello",
		null, null, null,
		"hearEvent", ["Hello"], "Hero"
	)
)
menu.addMenuItem(
	new MacaoMenuItem(
		"Bye", "Bye",
		null, null, null,
		"hearEvent", ["Bye"], "Hero"
	)
)

You can find this example under examples/menu. The content page contains an object of the name Hero. The Hero has got two talk items, which are triggered by the event types "Hello" and "Bye". The Menu is created in the other frame. It has two menu items. Each sends an event "hearEvent" to the Hero, when clicked. The trigger event, which is provided with the hearEvent is "Hello" or "Bye". That will trigger the execution of the fitting talk item.

A Controller Example

In the last example the menu knew the name of the object Hero, which it controlled. For a standard controller it is more useful, when the object knows the controller rather than the controller knows the object. Each object can register the controller when it knows the name of the controller. See the example for a controller. First see the source code for the page:

// create the hero
var hero = new MacaoObject("Hero", "Arnold", 200, 200)

// set the image of the hero
hero.setImage("examples/controller/hero.gif", 32, 32)

// add the talk items which are triggered by the menu items
hero.createTalkItem("Hero_Hello", "Hello", "Hello world!")
hero.createTalkItem("Hero_Bye", "Bye", "Good bye.")

// add a method, which is controller sensitive
hero.hearMyEvent = function(eventType, controllerName) {
	
	// test the controller name
	if((! controllerName) || this.isController(controllerName)) {
		
		// call the standard method
		this.hearEvent(eventType)
	}
}

// register the controller to the object
hero.addController("MyController")

Here the source code for the controller:

// create the controller
var controller = new MacaoMenu("MyController", null, 20, 20)

// set two columns, hide images, show text
controller.setMenuCharacteristics(2, false, true)

// add broadcast method
controller.broadcastMyEvent = function(eventType) {
	this.broadcastEvent("hearMyEvent", [eventType, this.getName()], true)
}
	
// add the menu items with the events
controller.addMenuItem(
	new MacaoMenuItem(
		"Hello", "Hello",
		null, null, null,
		"broadcastMyEvent", ["Hello"], null
	)
)
controller.addMenuItem(
	new MacaoMenuItem(
		"Bye", "Bye",
		null, null, null,
		"broadcastMyEvent", ["Bye"], null
	)
)

You can find this example under examples/controller. Some methods of an object are controller sensitive (See MacaoObject.approachAndTryAction(), MacaoObject.setSteeringIndex() and MacaoObject.stopWalking()). Because the method MacaoObject.hearEvent() is not controller sensitive, we add our own controller sensitive method hearMyEvent() to the object. If the controller name is not provided or the provided name is in the list of registered controllers, the method will call the standard method hearEvent(). Otherwise the call will be ignored. To accept the event from the new controller, the controller MyController is registered to the object using MacaoObject.addController().

The controller of the example is a menu object, which is extended by the method broadcastMyEvent(). It broadcasts the new "hearMyEvent" to all objects in all frames. As parameters it provides the event type of the menu item and the name of the menu object, which is the controller name "MyController". The menu items are changed to send their events to the new method of the controller object. Setting the recipient name to null does this.

The method hearMyEvent() may now be implemented for all objects. This could be done for example by sub-classing the class MacaoObject. But only that objects will react to the controller, which have registered the controller using addController(). If you remove this call from the example page, the object will not react to the controller any more.

Use this constructor to create a new menu on your page.

Parameters

name: Provide a unique name for the menu object.
title: Provide a title, which will be displayed as tool-tip over the menu. Provide null, if you don't want a tool-tip to be displayed.
The title is automatically added to the resources and received from the resources. The object name is used as the resource item name. See also MacaoPage.getResource().
left: Provide the x-coordinate of the menus left edge relative to the page in pixels.
top: Provide the y-coordinate of the menus top edge relative to the page in pixels.

Call this method to append a new menu item to the menu.

Each item of a menu has to have a unique name.

Parameters

menuItem: Provide the menu item to be added.


Returns

Returns the menu item you provided.

This method overrides the method from the super class MacaoObject. For a menu ever the name of the menu object is used as CSS class name.

Returns

Returns the name of the cascading style sheet class.

Call this method to get a menu item from the menu by its name.

Parameters

itemName: Provide the name of the menu item you are looking for.


Returns

Returns the menu item or null, if there is no menu item with this name.

The constructor of the menu calls this method to initiate the menu properties. Call this method, if you sub-class the class MacaoMenu.

Parameters

name: Provide a unique name for the menu.
title: Provide a title, which will be displayed as tool-tip over the menu. Provide null, if you don't want a tool-tip to be displayed.
left: Provide the x-coordinate of the menus left edge relative to the page in pixels.
top: Provide the y-coordinate of the menus top edge relative to the page in pixels.

Call this method to remove all menu items from the menu.

This method removes all menu items from the menu object and clears the HTML.

Call this method to set the focus to the first visible menu item, which has an input field.

Call this method to define the look of the positioning of the menu items and the elements, which are displays by the menu items.

This method has to be called, before the menu items are added using the method addMenuItem().

Parameters

maxColumnCount: Provide the maximum number of columns of the table, which is used to position the menu items. Set this parameter to 1, if you want all items be displayed in a column. Set this parameter to a large value like 100, if you want all menu items to be displayed in a row. You may also provide values in between. The default value is 1.
showMenuItemImages: Set this parameter to true, if the menu items have to display an image. Set this parameter to false, if the menu items don't have to create a DOM image object.
showMenuItemText: Set this parameter to true, if the title of the menu item is to be displayed beside the image or instead of the image. Set this parameter to false, if the title of the menu item is only to be displayed as tool tip.

Call this method to set a menu item active or inactive.

This method is useful for radio or toggle menu items. See also MacaoMenuItem.setActive().

Parameters

itemName: Provide the name of the menu item.
active: Provide true to set the item active. Provide false to set the item inactive.

Call this method to change the image, which is used to display the menu item.

See also MacaoMenuItem.setImageSource().

Parameters

itemName: Provide the name of the menu item.
imageSource: Provide the URL of the image relative to the base path. See also MacaoPage.getBasePath().
isDefaultImage: Set this parameter to true, if this image is to be displayed, when the menu item is inactive and the mouse is not over the menu item.
isMouseOverImage: Set this parameter to true, if this image is to be displayed, when the mouse is over the menu item and the menu item is not active.
isActiveImage: Set this parameter to true, if this image is to be displayed, when the menu item is active.

Call this method to display or hide a menu item.

See also MacaoMenuItem.setVisibility().

Parameters

itemName: Provide the name of the menu item.
visibility: Set this parameter to true to show the menu item. Set this parameter to false to hide the menu item.