Menus

Menus are a top level element that display a list of items. They are typically used to provide contextual actions, ie. a context or ‘right click’ menu.

Menus function much like boxes, except they can only have uimenuitem as children.

New menus can be created with the menu() function in the ui module.

New menu items can be created with the following functions:

• menuitem()

• textmenuitem()

• separatormenuitem()

Functions

ui.menu()

Create a new uimenu.

Return type:

uimenu

Version History

Version	Notes
0.3.0	Added

ui.menuitem()

Create a new uimenuitem.

Return type:

uimenuitem

Version History

Version	Notes
0.3.0	Added

ui.textmenuitem(text, color, font)

Create a new menu item containing a uitext.

Parameters:

• text (string)

• color (integer)

• font (uifont)

Return type:

uimenuitem

See also

text, color, and font are passed directly to text().

Version History

Version	Notes
0.3.0	Added

ui.separatormenuitem(orientation)

Create a new uimenuitem with a uiseparator.

Parameters:

orientation (string)

Return type:

uimenuitem

See also

orientation is passed directly to separator().

Version History

Version	Notes
0.3.0	Added

Classes

class ui.uimenu

pushfront(item)

Add the given uimenuitem to the beginning of the menu.

Parameters:

item (uimenuitem)

Version History

Version	Notes
0.3.0	Added

pushback(item)

Add the given uimenuitem to the end of the menu.

Parameters:

item (uimenuitem)

Version History

Version	Notes
0.3.0	Added

popfront()

Remove the first item from the menu.

Version History

Version	Notes
0.3.0	Added

popback()

Remove the last item from the menu.

Version History

Version	Notes
0.3.0	Added

insertbefore(before, item)

Insert item before item before.

If before is not in this menu, item is not added and this method will return false. true is returned on success.

Parameters:

• before (uimenuitem)

• item (uimenuitem)

Return type:

boolean

Version History

Version	Notes
0.3.0	Added

insertafter(after, item)

Insert item after item after.

If after is not in this menu, item is not added and this method will return false. true is returned on success.

Parameters:

• after (uimenuitem)

• item (uimenuitem)

Return type:

boolean

Version History

Version	Notes
0.3.0	Added

removeitem(item)

Remove the given uimenuitem from the menu.

Parameters:

item (uimenuitem)

Version History

Version	Notes
0.3.0	Added

show([x, y])

Show the menu, either at the given location or at the mouse cursor.

Parameters:

• x (integer) – (Optional)

• y (integer) – (Optional)

Version History

Version	Notes
0.3.0	Added

hide()

Hide the menu.

Version History

Version	Notes
0.3.0	Added

Note

The following methods are inherited from uielement

x([position])

Set or get the current position X.

Parameters:

position (integer) – (Optional)

Return type:

integer

Important

It is normally not necessary to manually position an element.

Version History

Version	Notes
0.3.0	Added

y([position])

Set or get the current position Y.

Parameters:

position (integer) – (Optional)

Return type:

integer

Important

It is normally not necessary to manually position an element.

Version History

Version	Notes
0.3.0	Added

width([value])

Get or set the element’s width.

Parameters:

width (integer) – (Optional)

Return type:

integer

Important

It is normally not necessary to manually set an element’s size.

Version History

Version	Notes
0.3.0	Added

height([value])

Get or set the element’s height.

Parameters:

width (integer) – (Optional)

Return type:

integer

Important

It is normally not necessary to manually set an element’s size.

Version History

Version	Notes
0.3.0	Added

bgcolor([color])

Get or set the element’s background color.

Parameters:

color (integer) – (Optional)

Return type:

integer

Version History

Version	Notes
0.3.0	Added

class ui.uimenuitem

A item within a uimenu.

Menu items are made up of 3 pieces:

+--------+---------+------------+
| (icon) | (child) | (sub-menu) |
+--------+---------+------------+

The icon is a text value displayed using the default icon font. This can be used to indicate a status such as on/off or to give additional context or a visual hint to the menu item.

The child is any valid UI element; most commonly the child will be a uitext.

The sub-menu item will only be shown if the item contains a sub-menu. This gives the user an indication that the sub-menu exists and will be shown when the item is hovered.

enabled(value)

Set if this menu item is enabled or not.

A disabled menu item does not react or send mouse events.

Parameters:

value (boolean)

Version History

Version	Notes
0.3.0	Added

element(element)

Set the UI Element to be displayed in this menu item.

Parameters:

element (uielement)

Version History

Version	Notes
0.3.0	Added

icon([codepoint])

Get or set the icon to be shown on this menu item.

If codepoint is not supplied, the current icon string is returned.

Parameters:

codepoint (string) – (Optional) codepoint/string value of the icon

Return type:

string

See also

iconcodepoint() can be used to lookup an icon codepoint.

Version History

Version	Notes
0.3.0	Added

submenu(menu)

Set a sub-menu to be shown when this menu item is hovered.

Parameters:

menu (uimenu)

Version History

Version	Notes
0.3.0	Added

addeventhandler(handler[, event1, event2, ...])

Add an event handler.

If no event types are specified, ‘click-left’ will be used.

Parameters:

• handler (function)

• event1 (string) – (Optional)

Return type:

integer

Version History

Version	Notes
0.3.0	Added

removeeventhandler(handlerid)

Remove an event handler added with addeventhandler().

Parameters:

handlerid (integer)

Version History

Version	Notes
0.3.0	Added

sendevent(event)

Send an event to event handlers of this menu item.

Note

This is only intended to be used when sub-classing a menu item.

Parameters:

event (string)

Version History

Version	Notes
0.3.0	Added

Note

The following methods are inherited from uielement

x([position])

Set or get the current position X.

Parameters:

position (integer) – (Optional)

Return type:

integer

Important

It is normally not necessary to manually position an element.

Version History

Version	Notes
0.3.0	Added

y([position])

Set or get the current position Y.

Parameters:

position (integer) – (Optional)

Return type:

integer

Important

It is normally not necessary to manually position an element.

Version History

Version	Notes
0.3.0	Added

width([value])

Get or set the element’s width.

Parameters:

width (integer) – (Optional)

Return type:

integer

Important

It is normally not necessary to manually set an element’s size.

Version History

Version	Notes
0.3.0	Added

height([value])

Get or set the element’s height.

Parameters:

width (integer) – (Optional)

Return type:

integer

Important

It is normally not necessary to manually set an element’s size.

Version History

Version	Notes
0.3.0	Added

bgcolor([color])

Get or set the element’s background color.

Parameters:

color (integer) – (Optional)

Return type:

integer

Version History

Version	Notes
0.3.0	Added