win.menuWindow - WIN
Class menuWindow
Inherits from listWindow.
The menuWindow class provides a vertical list of selectable strings,
initially empty and invisible. Menu items must be added to the menu
after creation with menuWindow:add_string, and then
call menuWindow:track
which displays it in the parent window and operates the menu. The
menu object automatically destroys itself when the menu operation
completes. Its colors are initialized from the theme but may be
customized after creation. If an item is selected by the user a menu_cmd
event is sent to the parent with a first parameter of the menu
item's id. Pressing Ctrl will cancel a menu without action.
Typical usage, only local object required:
-- command ids
local IDM_ONE = 1001
local IDM_TWO = 1002
local IDM_THREE = 1003
local IDM_QUITAPP = 1004
function appFrame:on_event (event, p1, p2, p3, p4, p5, ...)
-- handle events and return true
if event == "menu_cmd" then
return self:on_command (p1)
end
return false
end
-- method to create and display menu
function appFrame:on_menu ()
local menu = win.menuWindow:new (self)
menu:add_string ("One Ctrl+1", IDM_ONE)
menu:add_string ("Two Ctrl+2", IDM_TWO)
menu:add_string ("Three Ctrl+3", IDM_THREE)
menu:add_string ("------------")
menu:add_string ("Quit App", IDM_QUITAPP)
menu:track (0, 1)
end
-- command handler
function appFrame:on_command (cmd_id)
if cmd_id == IDM_ONE then
-- do something
return true
end
if cmd_id == IDM_TWO then
-- do something
return true
end
if cmd_id == IDM_THREE then
-- do something
return true
end
if cmd_id == IDM_QUITAPP then
self:quit_app ()
return true
end
return false
end
Properties
none
Methods
See also API
Reference, WIN.
win.menuWindow:add_string
menuWindow:add_string (str, item_id, index)
Inserts a string into the menu at the given index.
Parameters
str |
string |
The string to display in the menu. |
item_id |
number/nil |
Unique value for the menu command. If zero or
nil the item is treated as inactive (useful for separators).
|
index |
number |
1 based index to insert the item. If nil or
out of range the item is added to the end of the list. |
Returns
Remarks
The item_id should be a unique number value identifying this menu
item's command. This value is passed as the first parameter to the
parent in the menu_cmd
event to indicated the user's response.
Strings must be added to the menu after creation but before calling
menuWindow:track.
Invalidation is handled.
See listWindow:add_string.
top
win.menuWindow:constructor
menu menuWindow:constructor (parent)
Constructs and returns the instantiated menu window.
Parameters
parent |
window |
Parent window, typically a frame. |
Returns
menu |
menuWindow |
The instantiated menu window. |
Remarks
The menu window is initially empty and invisible. Items must be
added to the menu after creation with menuWindow:add_string, and then
call menuWindow:track
which displays it in the parent window and operates the menu.
top
win.menuWindow:next_valid_item
index menuWindow:next_valid_item (from)
Returns the index of the next active item (non-zero item_id)
after from. If none from is returned.
Parameters
from |
number |
The index of the item to search from. |
Returns
index |
number |
The next active item after from, or from if
none. |
Remarks
See menuWindow:prior_valid_item.
top
win.menuWindow:on_blur
result menuWindow:on_blur (focused)
Destroys this menu window.
Parameters
focused |
window |
The window gaining focus, it may be nil. |
Returns
result |
boolean |
Always true. |
Remarks
See window:on_blur.
top
win.menuWindow:on_key
result menuWindow:on_key (key, ctrl, alt, shift)
Handles key events; up, down, home, end, ctrl (destroys the menu
window), and destroys this menu window and sends a menu_cmd
event to the parent window on enter with a first parameter of the
selected menu item_id.
Parameters
key |
number |
Key code. |
ctrl |
boolean |
True if control key is depressed. |
alt |
boolean |
True if alternate key is depressed. |
shift |
boolean |
True if shift key is depressed. |
Returns
result |
boolean |
True if key was handled, false if not. |
Remarks
See window:on_key.
top
win.menuWindow:on_left_click
result menuWindow:on_left_click (x, y, count)
Calls base window implementation, sets the selected item at the
click point and sends a menu_cmd event to the parent
window if on an item with a first parameter of the menu item_id, and
destroys this menu window.
Parameters
x |
number |
Window relative x position. |
y |
number |
Window relative y position. |
count |
number |
The number of times this same position was
repeatedly clicked, with each successive click within the double_click_time. |
Returns
result |
boolean |
Always true. |
Remarks
See window:on_left_click.
top
win.menuWindow:on_touch
result menuWindow:on_touch (x, y)
Calls base window implementation, sets the selected item at the
touch point and sends a menu_cmd event to the parent
window if on an item with a first parameter of the menu item_id, and
destroys this menu window.
Parameters
x |
number |
Window relative x position. |
y |
number |
Window relative y position. |
Returns
result |
boolean |
Always true. |
Remarks
See window:on_touch.
top
win.menuWindow:prior_valid_item
index menuWindow:prior_valid_item (from)
Returns the index of the next active item (non-zero item_id)
before from. If none from is returned.
Parameters
from |
number |
The index of the item to search from. |
Returns
index |
number |
The next active item before from, or from if
none. |
Remarks
See menuWindow:next_valid_item.
top
win.menuWindow:set_cur_sel
changed menuWindow:set_cur_sel (index, make_visible)
Sets the currently selected item in the menu to the index given (1
based).
Parameters
index |
number |
1 based index of the item to select. Zero or
nil for no selection. |
make_visible |
boolean |
If true or nil scrolling is adjusted to bring
the selected item into view if needed. |
Returns
changed |
boolean |
True if the current selection changed, false
if not. |
Remarks
If index is greater than the number of items in the menu the last
one is selected.
Invalidation is handled.
top
win.menuWindow:track
menuWindow:track (x, y)
Dimensions the menu window to accommodate all the string entries and
displays it in the parent window at x, y, adjusted if required. The
menu is assured at the top of the parent's child z order, and has
mouse capture.
Parameters
x |
number |
Parent relative x position. |
y |
number |
Parent relative y position. |
Returns
Remarks
top
See also API
Reference, WIN.