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
none


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
none


Remarks


top


See also API Reference, WIN.