Class: Menu

Menu(client, oOptsopt)

The ExMenu/JS component provides menu-functionaly which includes top-level menus, context, popup, drop down or shortcut menus. A menu presents a list of items, commands, attributes, or states from which a user can choose. An item within a menu is known as a menu item, and may be configured to initiate an action, toggle a state on or off, or display a submenu of additional menu items when it is selected. A context menu is a menu in a graphical user interface (GUI) that appears upon user interaction, such as a right-click mouse operation. The ExMenu/JS is a HTML standalone-component, written in JavaScript, that uses no third-party libraries.

Every option of the Menu.Options type has associated a property of the control. For instance, the option:

debug {boolean}, indicates whether the control displays debug-information
is associated with the property:
Debug {boolean}, indicates whether the control displays debug-information
which means that the following statements are equivalent:
oMenu.Options = {debug: true}
oMenu.SetOptions({debug: true})
oMenu.Debug = true
oMenu.SetDebug(true)
where oMenu is an object of Menu type
Parameters:
Name Type Attributes Description
client any The client parameter indicates the control's client area as:
  • array of [x,y,width,height] type that specifies the control's client area
  • string, that specifies the identifier of the canvas within the document, so the canvas's client area becomes the control's client area
  • HTMLCanvasElement, that specifies the identifier of the canvas within the document, so the canvas's client area becomes the control's client area
  • null, indicates that the menu is displayed as a context/shortcut-menu at position (x,y) (of options). Use Open() method to open the shortcut/context-menu any time
oOpts object <optional>
An object of Menu.Options type that defines different options to display the control
Requires:
  • module:exontrol.commmon.min.js

Requires

  • module:exontrol.commmon.min.js

Classes

Options

Members

(static, readonly) AlignContextMenuEnum :number

The Menu.AlignContextMenuEnum type defines the alignment to show the context-menu/shortcut-menu
Type:
  • number
Properties:
Name Type Description
exLeftAlign number The exLeftAlign value positions the shortcut menu so that its left side is aligned with the coordinate specified by the x parameter.
exCenterAlign number The exCenterAlign value centers the shortcut menu horizontally relative to the coordinate specified by the x parameter
exRightAlign number The exRightAlign value positions the shortcut menu so that its right side is aligned with the coordinate specified by the x parameter.
exTopAlign number The exTopAlign value positions the shortcut menu so that its top side is aligned with the coordinate specified by the y parameter.
exVCenterAlign number The exVCenterAlign value centers the shortcut menu vertically relative to the coordinate specified by the y parameter.
exBottomAlign number The exBottomAlign value positions the shortcut menu so that its bottom side is aligned with the coordinate specified by the y parameter.

(static, readonly) ArrangeItemsEnum :number

The Menu.ArrangeItemsEnum type specifies the way the items of the control are arranged.
Type:
  • number
Properties:
Name Type Description
exArrangeItemsHorizontal number The exArrangeItemsHorizontal flag specifies that the items are horizontally arranged from left to right.
exArrangeItemsVertical number The exArrangeItemsVertical flag specifies that the items are vertically arranged from top to bottom.
exArrangeItemsHideTopArrow number The exArrangeItemsHideTopArrow flag indicates that the arrow for any top-item is not visible (not valid for float-menu).
exArrangeItemsPopupAlign number The exArrangeItemsPopupAlign flag specifies that the item's float/popup-menu should be displayed to prevent overlapping other items.
exArrangeItemsWrap number The exArrangeItemsWrap flag wraps items on a new row/column (not valid for float-menu).
exArrangeItemsScroll number The exArrangeItemsScroll flag specifies that the control's scroll bar is displayed if required
exArrangeItemsAlignCenter number The exArrangeItemsAlignCenter flag centers the items on each row/column.
exArrangeItemsAlignReverse number The exArrangeItemsAlignReverse flag reverses the alignment of the items.

(static, readonly) CloseOnClickEnum :number

The Menu.CloseOnClickEnum type defines whether the float-menu is closed once an item of specified type is clicked
Type:
  • number
Properties:
Name Type Description
exCloseOnDefault number The exCloseOnDefault flag indicates that the float-menu is closed once the user clicks an enabled item with no check, radio or button associated.
exCloseOnDisabled number The exCloseOnDisabled flag specifies that the float-menu is closed once the user clicks a disabled item.
exCloseOnSeparator number The exCloseOnSeparator flag specifies that the float-menu is closed once the user clicks a separator item.
exCloseOnButton number The exCloseOnButton flag specifies that the float-menu is closed once the user clicks an item of button-type.
exCloseOnCheck number The exCloseOnCheck flag specifies that the float-menu is closed once the user clicks an item of check-type.
exCloseOnRadio number The exCloseOnRadio flag specifies that the float-menu is closed once the user clicks an item of radio-type.
exCloseOnState number The exCloseOnState flag specifies that the float-menu is closed once the user clicks an item of check or radio-type.
exCloseOnAny number The exCloseOnAny flag specifies that the float-menu is closed once the user clicks any item.

(static, readonly) DisplayTypeEnum :number

The Menu.DisplayTypeEnum type defines the type of items the control can display.
Type:
  • number
Properties:
Name Type Description
exDisplayNormal number The exDisplayNormal value indicates a normal item.
exDisplayCheck number The exDisplayCheck value specifies that the item displays a check-box
exDisplayRadio number The exDisplayRadio value specifies that the item displays a radio-button

(static, readonly) FlatEnum :number

The Menu.FlatEnum type specifies whether the menu's flat bar is shown or visible. The menu's flat bar can be displayed only if the items are vertically arranged.
Type:
  • number
Properties:
Name Type Description
exNormal number The exNormal flag indicates that the menu's flat bar is not shown.
exShowFlat number The exShowFlat flag indicates that the menu's flat bar is visible only if the menu contains items with check, radio or image.
exAlwaysFlat number The exAlwaysFlat flag indicates that the menu's flat bar is always visible.

(static, readonly) GroupPopupEnum :number

The Menu.GroupPopupEnum type specifies how the sub-items of a grouped-item are arranged
Type:
  • number
Properties:
Name Type Description
exNoGroupPopup number The exNoGroupPopup flag specifies that no grouping is performed on the popup item.
exGroupPopup number The exGroupPopup flag groups and displays the sub-menu items on the current item, arranged from left to right (horizontally).
exGroupPopupEqualWidth number The exGroupPopupEqualWidth flag displays the sub-items with the same width.
exGroupPopupEqualHeight number The exGroupPopupEqualHeight flag displays the sub-items with the same height.
exGroupPopupVertical number The exGroupPopupVertical flag groups and displays the sub-menu items on the current item, arranged from top to bottom (vertically).

(static) reqEsc :string

The reqEsc field holds the special-characters that must be escaped
Type:
  • string

(static, readonly) ShowAsButtonEnum :number

The Menu.ShowAsButtonEnum type defines the type of buttons an item supports.
Type:
  • number
Properties:
Name Type Description
exShowAsButtonNone number The exShowAsButtonNone flag indicates that no button is associated with the item
exShowAsButton number The exShowAsButton flag indicates that the item displays a button
exShowAsSelectButton number The exShowAsSelectButton flag indicates a select button is associated with the current item ( show the drop-down button to the right ).
exShowAsSelectButtonBottom number The exShowAsSelectButtonBottom flag indicates a select button is associated with the current item ( show the drop-down button to the bottom ).
exShowAsSelectList number The exShowAsSelectList flag indicates a select button is associated with the current item ( the drop down is shown when the user clicks any part of the button ).

(static, readonly) ShowCheckedAsSelectedEnum :number

The Menu.ShowCheckedAsSelectedEnum type defines how an item that has a check-box/radio button is displayed.
Type:
  • number
Properties:
Name Type Description
exDisplayItemCheckDefault number The exDisplayItemCheckDefault value indicates that no highlight is applied to the item's check/radio
exDisplayItemCheckHighlight number The exDisplayItemCheckHighlight value highlights the checked item.
exDisplayItemHighlight number The exDisplayItemHighlight value highlights the checked item, but hides the item's check/radio button.

(static, readonly) ShowPopupAlignEnum :number

The Menu.ShowPopupAlignEnum type defines the alignment the of the sub-menu/popup/float relative to its parent item.
Type:
  • number
Properties:
Name Type Description
exShowPopupAlignNone number The exShowPopupAlignNone value indicates that the sub-menu/popup is shown up-left aligned relative to the parent item.
exShowPopupAlignDown number The exShowPopupAlignDown value indicates that the sub-menu/popup is shown down-aligned relative to the parent item.
exShowPopupAlignRight number The exShowPopupAlignRight value indicates that the sub-menu/popup is shown right-aligned relative to the parent item.

(static) timeoutOC :number

The Menu.timeoutOC field indicates the time in ms, the Open/Close method opens/closes the float-menu(s) Specifies the time in ms, the Open/Close method opens/closes the float-menu(s). If negative the open/close is called immediately, if 0 the open/close method is invoked asap, else it indicates the time to wait until the open/close occurs
Type:
  • number

(static) type :string

The type field defines the full-name of the object (the constructor.name does not give the same name for minimized forms)
Type:
  • string
Since:
  • 1.8

(static) version :string

The version field defines the version of the control
Type:
  • string

Listeners :exontrol.Lts

The Listeners field defines the events of the control, as an object of exontrol.Lts type. The exontrol.Lts type supports forEach(callback, thisArg) method that helps you to enumerate the events the control supports. The Events section lists the events the component supports.
Type:
  • exontrol.Lts
Example
The following sample shows how you can get all events the component currently supports:

oMenu.Listeners.forEach(function(name)
{
 console.log(name);
});

The following sample displays the item being selected:

oMenu.Listeners.Add("onselect", function (oEvent)
{
 console.log(oEvent);
});

where oMenu is an object of Menu type

SetCanvas

The SetCanvas() method changes the control's canvas where it runs (overrides the SetCanvas method to implement the HTMLCanvasElement.ExHost(oHost) method)
Since:
  • 1.8

Shortcuts :exontrol.Sts

The Shortcuts field defines the shortcuts of the control, as an object of exontrol.Sts type. In order to provide keyboard support for the component, the owner <canvas> element must include the tabIndex attribute, as <canvas ... tabIndex="0">. You can associated a function or a callback to any shortcut.
Type:
  • exontrol.Sts
Example
The following sample activates the File popup-menu as soon as user presses F key:

oMenu.Shortcuts.Add( "F", function(oShortcut)
{
  oMenu.Open("File");
});

where oMenu is an object of Menu type

Methods

BeginUpdate()

The BeginUpdate() method suspends the control's render until the EndUpdate() method is called. It maintains performance, while multiple changes occurs within the control. You can use the Update() method to perform multiple changes at once.

cCB(event) → {boolean}

The cCB/closeComboBox() method checks whether the drop-down panel should close on click (required only if the control is hosted by an exontrol.ComboBox object)
Parameters:
Name Type Description
event event A Mouse/Touch object to be querried for the mouse/touch position.
Since:
  • 1.8
Returns:
Returns true if the drop-down panel should close on click
Type
boolean

Close()

The Close() method closes programatically the menu and all its float-menus.

EndUpdate()

The EndUpdate() method resumes the control's render, after it is suspended by the BeginUpdate() method.

EnsureVisibleItem(oItem) → {Item}

The EnsureVisibleItem() method scrolls the control to ensure that the giving item fits the control's visible area
Parameters:
Name Type Description
oItem Item Indicates an object of Item type
Returns:
Returns the item itself
Type
Item

forEachU(callback, thisArgopt, oItemopt) → {any}

The forEachU() method enumerates the items within the control
Parameters:
Name Type Attributes Description
callback callback Specifies a function of callback(oItem) {any} type that's invoked for each item. The arguments of the callback are:
oItem {Item}, specifies the item of Item type
thisArg any <optional>
Indicates the value of "this" keyword during the callback (if not specified it refers the current object as an Menu type)
oItem Item <optional>
Indicates the item whose child-items are recursivelly enumerated
Returns:
Returns the last-result of callback(oItem) call
Type
any

GetAlign() → {number}

The GetAlign() method defines the default horizontally alignment of the item's caption.
Returns:
An integer value that could be one of the following as:
  • -1 {number}, specifies that the item's caption full-fits the item's background. You can use the or ex-HTML tags to align portions of caption inside the item
  • 0 {number}, indicates that the caption is left-aligned
  • +1 {number}, specifies that the caption is centered
  • +2 {number}, specifies that the caption is right-aligned
Type
number

GetAlignClient() → {boolean}

The GetAlignClient() method indicates whether the item's client position is aligned to sub-item client position, when a float-menu is displayed.
Returns:
Returns a value that specifies whether the item's client position is aligned to sub-item client position, when a float-menu is displayed.
Type
boolean

GetAlignContextMenu() → {Menu.AlignContextMenuEnum}

The GetAlignContextMenu() method indicates the horizontal and vertical position of the context/shortcut-menu relative to the x, y coordinates.
Returns:
Returns a value that specifies the horizontal and vertical position of the context/shortcut-menu relative to the x, y coordinates. The Menu.AlignContextMenuEnum type defines the following flags:
  • exLeftAlign (0x00), positions the shortcut menu so that its left side is aligned with the coordinate specified by the x parameter
  • exCenterAlign (0x04), centers the shortcut menu horizontally relative to the coordinate specified by the x parameter
  • exRightAlign (0x08), positions the shortcut menu so that its right side is aligned with the coordinate specified by the x parameter
  • exTopAlign (0x00), positions the shortcut menu so that its top side is aligned with the coordinate specified by the y parameter
  • exVCenterAlign (0x10), centers the shortcut menu vertically relative to the coordinate specified by the y parameter
  • exBottomAlign (0x20), positions the shortcut menu so that its bottom side is aligned with the coordinate specified by the y parameter
The alignContextMenu property has effect only, if the control is opened as a context-menu, using the Open() method.
Type
Menu.AlignContextMenuEnum

GetAllowToggleRadio() → {boolean}

The GetAllowToggleRadio() method specifies whether toggling the radio state is allowed
Returns:
Returns true, if toggling the radio state is allowed
Type
boolean

GetArrangeItemsAs() → {Menu.ArrangeItemsEnum}

The GetArrangeItemsAs() method indicates how the items are arranged on the control (top-level menu).
Returns:
Returns a ArrangeItemsEnum expression that specifies how the items are arranged on the control (top-level menu). The Menu.ArrangeItemsEnum type supports the following flags:
  • exArrangeItemsHorizontal (1), specifies that the items are horizontally arranged from left to right
  • exArrangeItemsVertical (2), specifies that the items are vertically arranged from top to bottom
  • exArrangeItemsHideTopArrow (0x10), indicates that the arrow for any top-item is not visible (not valid for float-menu)
  • exArrangeItemsPopupAlign (0x20), specifies that the item's float/popup-menu should be displayed to prevent overlapping other items
  • exArrangeItemsWrap (0x100), wraps items on a new row/column (not valid for float-menu)
  • exArrangeItemsScroll (0x200), specifies that the control's scroll bar is displayed if required
  • exArrangeItemsAlignCenter (0x400), centers the items on each row/column
  • exArrangeItemsAlignReverse (0x800), reverses the alignment of the items
Type
Menu.ArrangeItemsEnum

GetArrSize() → {number}

The GetArrSize() method defines the size (width and height) to show the item's arrow
Returns:
Returns a value that specifies the size (width and height) to show the item's arrow
Type
number

GetBtnArrSize() → {number}

Returns:
Returns a value that specifies the size (width and height) to show the button's arrow
Type
number

GetBtnPad() → {number|Array.<number>|string}

The GetBtnPad() method indicates the padding to apply item's button
Returns:
Returns a value that could be a numeric value, to btnPad horizontal and vertical size with the same value, or a "x,y" or [x,y] type to specify the btnPadding on h/v size
Type
number | Array.<number> | string

GetCanvas() → {HTMLCanvasElement}

The GetCanvas() method gets the canvas element, the control is running into.
Returns:
Returns the HTMLCanvasElement object the control is running on.
Type
HTMLCanvasElement

GetCanvasRect() → {array}

The GetCanvasRect() method returns the canvas's client rectangle.
Returns:
Returns an array of [x,y,width,height] type that specifies the canvas's client rectangle
Type
array

GetClientRect() → {array}

The GetClientRect() method returns the control's client area.
Returns:
Returns an array of [x,y,width,height] type that specifies the control's client area
Type
array

GetClose() → {number}

The GetClose() method defines the time in ms the sub-menu is closed once the cursor hovers the top-level item.
Returns:
Returns the time in ms the sub-menu is closed once the cursor hovers the top-level item, as explained:
  • if positive, indicates the time in ms the sub-menu is closed once the cursor hovers the top-level item.
  • if 0, indicates that the sub-menu is closed as soon as the cursor hovers a top-level item
  • if negative, it has no effect
Type
number

GetCloseOnClick() → {Menu.CloseOnClickEnum}

The GetCloseOnClick() method defines the type of items the user can click to close the float-menu(s).
Returns:
Returns a ArrangeItemsEnum expression that specifies how the items are arranged on float-menu. The Menu.CloseOnClickEnum type defines the following flags:
  • exCloseOnDefault (0), indicates that the float-menu is closed once the user clicks an enabled item with no check, radio or button associated
  • exCloseOnDisabled (1), specifies that the float-menu is closed once the user clicks a disabled item
  • exCloseOnSeparator (2), specifies that the float-menu is closed once the user clicks a separator item
  • exCloseOnButton (4), specifies that the float-menu is closed once the user clicks an item of button-type
  • exCloseOnCheck (8), specifies that the float-menu is closed once the user clicks an item of check-type
  • exCloseOnRadio (16), specifies that the float-menu is closed once the user clicks an item of radio-type
  • exCloseOnState (24), specifies that the float-menu is closed once the user clicks an item of check or radio-type
  • exCloseOnAny (-1), specifies that the float-menu is closed once the user clicks any type of item anywhere
Type
Menu.CloseOnClickEnum

GetCriAlign() → {boolean}

The GetCriAlign() method specifies whether the check-box/radio-button or the item's image are vertically aligned.
Returns:
Returns true, if the check-box/radio-button or the item's image are vertically aligned.
Type
boolean

GetCriFlat() → {Menu.FlatEnum}

The GetCriFlat() method specifies whether the menu's flat bar is shown or hidden.
Returns:
Returns whether the menu's flat bar is shown or hidden. The Menu.FlatEnum type supports the following values:
  • exNormal (0), indicates that the menu's flat bar is not shown
  • exShowFlat (1), indicates that the menu's flat bar is visible only if the menu contains items with check, radio or image
  • exAlwaysFlat (2), indicates that the menu's flat bar is always visible
Type
Menu.FlatEnum

GetCriPad() → {number|Array.<number>|string}

The GetCriPad() method indicates the padding to apply to a check-box/radio-button or the item's image
Returns:
Returns a value that could be a numeric value, to criPad horizontal and vertical size with the same value, or a "x,y" or [x,y] type to specify the criPadding on h/v size
Type
number | Array.<number> | string

GetCriSize() → {number}

The GetCriSize() method defines the size (width and height) to show a check-box/radio-button or the item's image
Returns:
Returns a value that specifies the size (width and height) to show a check-box/radio-button or the item's image
Type
number

GetCursors() → {string}

The GetCursors() method defines the mouse cursor to be displayed when pointing over different parts of the control.
Returns:
A string expression that defines the mouse cursor to be displayed when pointing over different parts of the control. The cursors property supports any of the following parts:
  • "menu" (menu), defines the visual appearance for the entire menu
  • "flat" (flat), defines the visual appearance for menu's flat bar (usually shown in the left side of the menu)
  • "sep" (separator), defines the visual appearance to display separator-items
  • "item" (item), defines the visual appearance for the item's background. It covers all parts of the item as check, image, caption/button, popup arrow and sub-items
  • "sub" (sub-items), defines the visual appearance to display sub-items of the item (while the item is grouped)
  • "arr" (arrow), defines the visual appearance to display item's arrow (while the item contains un-grouped sub-items)
  • "cap" (caption), defines the visual appearance for the item's caption
  • "img" (image), defines the visual appearance to display the item's image
  • "chk" (check), defines the visual appearance to display the item's check-box
  • "rad" (radio), defines the visual appearance to display the item's radio-button
  • "btn" (button), defines the visual appearance to display the buttons
  • "rarr" (right-arrow), defines the visual appearance to display button's arrow (to right)
  • "barr" (bottom-arrow), defines the visual appearance to display button's arrow (to bottom)
Type
string

GetDebug() → {string}

The GetDebug() method specifies whether the control is in debug-mode
Returns:
Returns true, if the control is in debug-mode
Type
string

GetItems() → {string}

The GetItems() method returns the items of the menu as a string-representation.
Returns:
Returns the string representation of the current menu as a string-representation. The format of the items'string representation is (everything between () refers to children, and everything between [] refers to flags):
"item1[flag=value]...[flag=value](sub-item1[flag=value]...[flag=value],...,sub-itemn[flag=value]...[flag=value]),...,itemn[flag=value]...[flag=value](sub-item1[flag=value]...[flag=value],...,sub-itemn[flag=value]...[flag=value])"
The string-representation supports the following flags:
  • [id], specifies the item's identifier, such as [id=10].
  • [align] {number}, horizontally aligns the caption. The align could be -1(full-fits the item), 0(left-alignment), 1(center), or 2( right-alignment) such as [align=2] right-aligns the item.
  • [pad], specifies the item's padding (space between the menu border and the item content). The pad could be one or two numbers, separated by comma, such as [pad=2] or [pad=2,2]
  • [itemsPad], specifies the items padding (space between the menu border and the item content). The itemsPad could be one or two numbers, separated by comma, such as [itemsPad=2] or [itemsPad=2,2]
  • [chk], indicates that the item has a check-box associated. If the [typ] flag is present, the [chk] flag indicates the state of the item, and the [rad] flag is ignored. The chk could be 0 or 1, such as [chk] or [chk=0] for a un-checked item, or [chk=1] for checked item.
  • [rad], indicates that the item has a radio-button associated. If the [typ] flag is present, the [chk] flag indicates the state of the item, and the [rad] flag is ignored. The rad could be 0 or 1, such as [rad] or [rad=0] for a un-checked item, or [rad=1] for checked item.
  • [typ], specifies the type of the item, that can be normal, check or radio. The typ could be 0(normal item), 1(items that display a check/box (chk)) or 2(items that display radio buttons (rad)). If the [typ] flag is present, the [chk] flag indicates the state of the item, and the [rad] flag is ignored. For instance [typ=1], specifies a check-box item
  • [grp], defines the radio group. It should be used when you define more groups of radio buttons. A group of radio buttons means that only one item could be checked at one time. The rad option specifies that the item displays a radio button. Use the grp option to define the group of radio where this button should be associated, If no group of radio buttons is required, the grp could be ignored. For instance, [grp=sample]
  • [img], indicates that the item's image. The img indicates the name of an exontrol.HP, such as [img=logo]
  • [group], specifies how the sub-items are being grouped. The group could be a flag combination of Menu.GroupPopupEnum type, such as [group] to group horizontlly the item, or [group=0x100] to group vertically the items
  • [arrow], indicates whether the item's popup-arrow is shown or hidden. The arrow could be 0 to hide the arrow, or not-zero to show the arrow, such as [arrow] or [arrow=0] to hide the arrow, or [arrow=1] to show the arrow
  • [hid], hides/shows the item. The hid could be 0 which indicates that the item is hidden. Any other value makes the item visible, such as [hid] or [hid=0] to hide the item, or [hid=1] to show the item
  • [captionWidth] or [cw], specifies the width to show the HTML caption of the item, where value could be a integer expression. A negative value indicates that no limitation is applied to the item's caption, so no truncate caption is shown. For instance [cw=128]
  • [captionHeight] or [ch], specifies the height to show the HTML caption of the item, where value could be a integer expression. A negative value indicates that no limitation is applied to the item's caption, so no truncate caption is shown. For instance [ch=128]
  • [height], specifies the height to display the item, where value could be a integer expression (it applies to all parts of the item). For instance [height=64]
  • [width], specifies the width to display the item, where value could be a integer expression (it applies to all parts of the item). For instance [width=64]
  • [button], associates a button with the item. The value could be a flag combination of Menu.ShowAsButtonEnum type, such as [button] or [button=1] makes the item to display a button, or [button=0] disables displaying any button.
  • [spchk], indicates whether the sub-items/popup of giving item are shown when the item is checked. The value could be 0, which indicates that it has no effect, or non-zero to show the sub-item when the item is checked. For instance [spchk]
  • [show], specifies how an item that has a check-box/radio-button should be displayed. The value could be any value of Menu.ShowCheckedAsSelectedEnum type. For instance [show=-1] (the exDisplayItemCheckHighlight value highlights the checked item)
  • [showdis], makes the item to show as disabled, while it is still enabled. The flag is applied to all descendents. Any value not-zero indicates that the item is shown as disabled. For instance [showdis]
  • [tab], indicates the identifier of the item that displays the sub-items of the current item. For instance: [tab=page] or [tab=1]
  • [dis], disables the item. The flag is applied to all descendents. Any value not-zero indicates that the item is enabled. For instance [dis]
  • [sep], specifies an separator item, such as [sep]. The value is ignored if provided. For instance [sep]
  • [popupalign] or [pa], indicates how the sub-menu/popup/float is aligned relative to the parent item (Menu.ShowPopupAlignEnum). For instance [pa=1] (The exShowPopupAlignDown value indicates that the sub-menu/popup is shown down-aligned relative to the parent item)
  • [shapes], specifies the shapes to be applied on the item only. For instance [shapes=dfitem(item),dfcap(cap)]
  • [cursors], defines the mouse cursor to be displayed when pointing over a part of the item only. For instance [cursors=pointer(item)]
  • [close], specifies whether clicking the item closes the float-menu (Menu.CloseOnClickEnum). For instance [close=-1], closes the context-menu once the user clicks the items (no matter, if it is of check, radio or button type)
Type
string

GetItemsPad() → {number|Array.<number>|string}

The GetItemsPad() method defines the padding the sub-items section of the item (space between the menu border and the items content).
Returns:
Returns a value that could be a numeric value, to itemsPad horizontal and vertical size with the same value, or a "x,y" or [x,y] type to specify the itemsPadding on h/v size
Type
number | Array.<number> | string

GetLocked() → {boolean}

The GetLocked() method specifies whether the control is locked(protected) or unlocked
Returns:
Returns true, if the control is locked(protected) or unlocked
Type
boolean

GetOpen() → {number}

The GetOpen() method defines the time in ms the top-level item opens its sub-menu once the cursor hovers it.
Returns:
Returns the time in ms the top-level item opens its sub-menu once the cursor hovers it, as explained:
  • if positive, indicates the time in ms the top-level item opens its sub-menu once the cursor hovers it.
  • if 0, indicates that the top-level item opens its sub-menu as soon as cursor hovers it
  • if negative, indicates that the item requires click to to open its sub-menu
Type
number

GetOptions() → {Menu.Options}

The GetOptions() method returns the current options of the control.
Returns:
An object of Menu.Options that indicates the options to display the control.
Type
Menu.Options

GetOutClose() → {number}

The GetOutClose() method defines the time in ms the control closes all its float-menu as soon as the cursor hovers outside portion of the menu.
Returns:
Returns the time in ms the control closes all its float-menu as soon as the cursor hovers outside portion of the menu, as explained:
  • if positive, specifies the time in ms the control closes all its float-menu as soon as the cursor hovers outside portion of the menu
  • if 0, indicates that the menu's floats are closed as soon as the cursor hovers outside portion of it
  • if negative, it has no effect
Type
number

GetPad() → {number|Array.<number>|string}

The GetPad() method defines the item's padding (space between the menu border and the item content).
Returns:
Returns a value that could be a numeric value, to pad horizontal and vertical size with the same value, or a "x,y" or [x,y] type to specify the padding on h/v size
Type
number | Array.<number> | string

GetPopupRatio() → {number}

The GetPopupRatio() method defines a positive number that specifies the maximum ratio of the document's view page, a float or a popup menu can be shown.
Returns:
Returns a positive number that specifies the maximum ratio of the document's view page, a float or a popup menu can be shown. For instance, 1/2 indicates that the width / height of the float-menu can not exceed half of the width / height of the document's view page.
Type
number

GetReadOnly() → {boolean}

The GetReadOnly() method specifies whether the control is read-only
Since:
  • 1.8
Returns:
Returns true, if the control is read-only
Type
boolean

GetScrollClip() → {boolean}

Returns:
Returns a value that specifies the size (width and height) to display the control's scroll bar
Type
boolean

GetScrollOpt() → {exontrol.ScrollBar.Options}

Returns:
Returns the options (UI visual appearance, behavior) to display the control's scroll bar.
Type
exontrol.ScrollBar.Options

GetScrollSize() → {number}

Returns:
Returns a value that specifies the size (width and height) to display the control's scroll bar
Type
number

GetSepSize() → {number}

Returns:
Returns a value that specifies the size to show a separator item
Type
number

GetShapes() → {string}

The GetShapes() method defines the shapes each part of the control can display. The shapes field customizes the control's visual appearance.
Returns:
A string expression that defines the shapes each part of the control can display. The format of shapes property is:
"shape(part),shape(part),..."
where:
  • "shape", defines the shape to apply on the UI part as one of the following:

    ◦ any of 140 color names any browser supports (such as red, blue, green, ...)
    ◦ hexadecimal colors, is specified with: #RRGGBB, where the RR (red), GG (green) and BB (blue) hexadecimal integers specify the components of the color. All values must be between 00 and FF (such as #0000ff which defines a blue background)
    ◦ hexadecimal colors with transparency, is specified with: #RRGGBBAA, where AA (alpha) value must be between 00 and FF (such as #0000ff80 which defines a semi-transparent blue background)
    ◦ RGB colors, is specified with the RGB(red, green, blue) function. Each parameter (red, green, and blue) defines the intensity of the color and can be an integer between 0 and 255( such as rgb(0,0,255) that defines a blue background)
    ◦ RGBA colors, are an extension of RGB color values with an alpha channel as RGBA(red, green, blue, alpha) function, where the alpha parameter is a number between 0.0 (fully transparent) and 1.0 (fully opaque) ( such as rgba(0,0,255,0.5) which defines a semi-transparent blue background)
    ◦ HSL colors, is specified with the HSL(hue, saturation, lightness) function, where hue is a degree on the color wheel (from 0 to 360) - 0 (or 360) is red, 120 is green, 240 is blue. saturation is a percentage value; 0% means a shade of gray and 100% is the full color. lightness is also a percentage; 0% is black, 100% is white. HSL stands for hue, saturation, and lightness - and represents a cylindrical-coordinate representation of colors (such as hsl(240, 100%, 50%) that defines a blue background)
    ◦ HSLA colors, are an extension of HSL color values with an alpha channel - which specifies the opacity of the object as HSLA(hue, saturation, lightness, alpha) function, where alpha parameter is a number between 0.0 (fully transparent) and 1.0 (fully opaque) (such as hsla(240, 100%, 50%,0.5) that defines a semi-transparent blue background)
    ◦ a JSON representation of the shape object to apply (while it starts with { character, such as '{"normal": {"primitive": "RoundRect","fillColor":"black","tfi": {"fgColor": "white"}}}')
    ◦ specifies the name of the field within the exontrol.Shapes.Menu object (while it starts with a lowercase letter, such as dfitem which refers to exontrol.Shapes.Menu.dfitem shape)
    ◦ specifies the name of the field within the exontrol.Shapes object (while it starts with an uppercase letter, such as Button which refers to exontrol.Shapes.Button shape)

  • "part", defines the name of the part the shape is applied on (as defined bellow)
The shapes property supports any of the following parts:
  • "menu" (menu), defines the visual appearance for the entire menu
  • "flat" (flat), defines the visual appearance for menu's flat bar (usually shown in the left side of the menu)
  • "sep" (separator), defines the visual appearance to display separator-items
  • "item" (item), defines the visual appearance for the item's background. It covers all parts of the item as check, image, caption/button, popup arrow and sub-items
  • "sub" (sub-items), defines the visual appearance to display sub-items of the item (while the item is grouped)
  • "arr" (arrow), defines the visual appearance to display item's arrow (while the item contains un-grouped sub-items)
  • "cap" (caption), defines the visual appearance for the item's caption
  • "img" (image), defines the visual appearance to display the item's image
  • "chk" (check), defines the visual appearance to display the item's check-box
  • "rad" (radio), defines the visual appearance to display the item's radio-button
  • "btn" (button), defines the visual appearance to display the buttons
  • "rarr" (right-arrow), defines the visual appearance to display button's arrow (to right)
  • "barr" (bottom-arrow), defines the visual appearance to display button's arrow (to bottom)
Type
string

GetShow() → {Menu.ShowCheckedAsSelectedEnum}

The GetShow() method indicates how an item that has a check-box/radio button is displayed.
Returns:
Returns a ShowCheckedAsSelectedEnum expression that specifies how an item that has a check-box/radio button is displayed.. The Menu.ShowCheckedAsSelectedEnum type defines the following values:
  • exDisplayItemCheckDefault (0), indicates that no highlight is applied to the item's check/radio
  • exDisplayItemCheckHighlight (-1), highlights the checked item
  • exDisplayItemHighlight (1), highlights the checked item, but hides the item's check/radio button
Type
Menu.ShowCheckedAsSelectedEnum

GetSmoothSel() → {number}

The GetSmoothSel() method defines the time in ms the control's selection goes from one state to another.
Returns:
Returns the time in ms the control's selection goes from one state to another.
Type
number

GetSubArrangeItemsAs() → {Menu.ArrangeItemsEnum}

The GetSubArrangeItemsAs() method indicates how the items are arranged on float-menu.
Returns:
Returns a ArrangeItemsEnum expression that specifies how the items are arranged on float-menu. The Menu.ArrangeItemsEnum type supports the following flags:
  • exArrangeItemsHorizontal (1), specifies that the items are horizontally arranged from left to right
  • exArrangeItemsVertical (2), specifies that the items are vertically arranged from top to bottom
  • exArrangeItemsHideTopArrow (0x10), indicates that the arrow for any top-item is not visible (not valid for float-menu)
  • exArrangeItemsPopupAlign (0x20), specifies that the item's float/popup-menu should be displayed to prevent overlapping other items
  • exArrangeItemsWrap (0x100), wraps items on a new row/column (not valid for float-menu)
  • exArrangeItemsScroll (0x200), specifies that the control's scroll bar is displayed if required
  • exArrangeItemsAlignCenter (0x400), centers the items on each row/column
  • exArrangeItemsAlignReverse (0x800), reverses the alignment of the items
Type
Menu.ArrangeItemsEnum

GetSubClose() → {number}

The GetSubClose() method defines the time in ms the sub-menu is closed once the cursor hovers the second-level item (it is applied to any level excepts the top-level).
Returns:
Returns the time in ms the sub-menu is closed once the cursor hovers the second-level item, as explained:
  • if positive, indicates the time in ms the sub-menu is closed once the cursor hovers the second-level item
  • if 0, indicates that the sub-menu is closed as soon as the cursor hovers a second-level item
  • if negative, it has no effect
Type
number

GetSubOpen() → {number}

The GetSubOpen() method defines the time in ms the second-level item opens its sub-menu once the cursor hovers it (it is applied to any level excepts the top-level).
Returns:
Returns the time in ms the second-level item opens its sub-menu once the cursor hovers it, as explained:
  • if positive, indicates the time in ms the item opens its sub-menu once the cursor hovers it.
  • if 0, indicates that the item opens its sub-menu as soon as the cursor hovers it
  • if negative, it has no effect so the item requires click in order to open its sub-menu
Type
number

GetTfi() → {string|object}

The GetTfi() method gets the font attributes to apply on captions of the control.
Returns:
Returns the font attributes as a string representation such as "b monospace 16" or as an object such as {bold: true, fontName: "monospace", fontSize: 16}.

The result as a {string} can include any of the following keywords separated by space characters:

  • bold, displays the text in bold (equivalent of <b> tag)
  • italic, displays the text in italics (equivalent of <i> tag)
  • underline, underlines the text (equivalent of <u> tag)
  • strikeout, specifies whether the text is strike-through (equivalent of <s> tag)
  • <fontName name>, specifies the font's family (equivalent of <font name> tag)
  • <fontSize size>, specifies the size of the font (equivalent of <font ;size> tag)
  • <fgColor CSSColor>, specifies the text's foreground color (equivalent of <fgcolor> tag)
  • <bgColor CSSColor>, specifies the text's background color (equivalent of <bgcolor> tag)
  • <shaColor CSSColor;width;offset>, defines the text's shadow (equivalent of <sha color;width;offset> tag)
  • <outColor CSSColor>, shows the text with outlined characters (CSScolor) (equivalent of <out color> tag)
  • <graColor CSSColor;mode;blend>, defines a gradient text (equivalent of <gra color;mode;blend> tag)

Any other word within the string result that's not recognized as a keyword is interpreted as:

  • name of the font (not a number), specifies the font's family (equivalent of <font name> tag)
  • size of the font (number), specifies the size of the font (equivalent of <font ;size> tag)

The result as {object} can include any of the following fields:

  • bold {boolean}, displays the text in bold (equivalent of <b> tag)
  • italic {boolean}, displays the text in italics (equivalent of <i> tag)
  • underline {boolean}, underlines the text (equivalent of <u> tag)
  • strikeout {boolean}, specifies whether the text is strike-through (equivalent of <s> tag)
  • fontName {string}, specifies the font's family (equivalent of <font name> tag)
  • fontSize {number}, specifies the size of the font (equivalent of <font ;size> tag)
  • fgColor {string}, specifies the text's foreground color (CSScolor) (equivalent of <fgcolor> tag)
  • bgColor {string}, specifies the text's background color (CSScolor) (equivalent of <bgcolor> tag)
  • shaColor {object}, specifies an object of {color, width, offset} type that defines the text's shadow (equivalent of <sha color;width;offset> tag), where:
    • color {string}, defines the color of the text's shadow (CSScolor)
    • width {number}, defines the size of the text's shadow
    • offset {number}, defines the offset to show the text's shadow relative to the text
  • outColor {string}, shows the text with outlined characters (CSScolor) (equivalent of <out color> tag)
  • graColor {object}, specifies an object of {color, mode, blend} type that defines a gradient text (equivalent of <gra color;mode;blend> tag), where:
    • color {string}, defines the gradient-color (CSScolor)
    • mode {number}, defines the gradient mode as a value between 0 and 4
    • blend {number}, defines the gradient blend as a value between 0 and 1

CSSColor or CSS legal color values can be specified by the following methods:

  • Hexadecimal colors, is specified with: #RRGGBB, where the RR (red), GG (green) and BB (blue) hexadecimal integers specify the components of the color. All values must be between 00 and FF. For example, #0000ff value is rendered as blue, because the blue component is set to its highest value (ff) and the others are set to 00.
  • Hexadecimal colors with transparency, is specified with: #RRGGBBAA, where AA (alpha) value must be between 00 and FF. For example, #0000ff80 defines a semi-transparent blue.
  • RGB colors, is specified with the RGB(red, green, blue) function. Each parameter (red, green, and blue) defines the intensity of the color and can be an integer between 0 and 255. For example, rgb(0,0,255) defines the blue color.
  • RGBA colors, are an extension of RGB color values with an alpha channel as RGBA(red, green, blue, alpha) function, where the alpha parameter is a number between 0.0 (fully transparent) and 1.0 (fully opaque). For example, rgba(0,0,255,0.5) defines a semi-transparent blue.
  • HSL colors, is specified with the HSL(hue, saturation, lightness) function, where hue is a degree on the color wheel (from 0 to 360) - 0 (or 360) is red, 120 is green, 240 is blue. saturation is a percentage value; 0% means a shade of gray and 100% is the full color. lightness is also a percentage; 0% is black, 100% is white. HSL stands for hue, saturation, and lightness - and represents a cylindrical-coordinate representation of colors. For example, hsl(240, 100%, 50%) defines the blue color.
  • HSLA colors, are an extension of HSL color values with an alpha channel - which specifies the opacity of the object as HSLA(hue, saturation, lightness, alpha) function, where alpha parameter is a number between 0.0 (fully transparent) and 1.0 (fully opaque). For example, hsla(240, 100%, 50%,0.5) defines a semi-transparent blue.
  • Predefined/Cross-browser color names, 140 color names are predefined in the HTML and CSS color specification. For example, blue defines the blue color.
Type
string | object

GetViewRect() → {array}

The GetViewRect() method returns the position of the owner canvas element within the document.
Returns:
Returns an array of [x,y,width,height] that specifies the position canvas element within the document.
Type
array

GetVisibleRect() → {array}

The GetVisibleRect() method indicates the control's visible rectangle
Returns:
Returns an array of [x,y,width,height] type that specifies the canvas's client rectangle
Type
array

GetWheelChange() → {number}

The GetWheelChange() method defines the amount the control scrolls when the user rolls the mouse wheel.
Returns:
Returns the amount the control scrolls when the user rolls the mouse wheel.
Type
number

GetX() → {number}

The GetX() method indicates the horizontal position to display the context/shortcut-menu relative to document.
Returns:
Returns a value that specifies the horizontal position to display the context/shortcut-menu relative to document.
Type
number

GetY() → {number}

The GetY() method indicates the vertical position to display the conteyt/shortcut-menu relative to document.
Returns:
Returns a value that specifies the vertical position to display the conteyt/shortcut-menu relative to document.
Type
number

init(client, oOptsopt)

The init() method initializes the control
Parameters:
Name Type Attributes Description
client any The client parameter indicates the control's client area as:
  • array of [x,y,width,height] type that specifies the control's client area
  • string, that specifies the identifier of the canvas within the document, so the canvas's client area becomes the control's client area
  • HTMLCanvasElement, that specifies the identifier of the canvas within the document, so the canvas's client area becomes the control's client area
  • null, indicates that the menu is displayed as a context/shortcut-menu at position (x,y) (of options). Use Open() method to open the shortcut/context-menu any time
oOpts object <optional>
An object of Menu.Options type that defines different options to display the control
Since:
  • 1.8

Item(id) → {Item}

The Item() method returns the item giving its identifier or caption.
Parameters:
Name Type Description
id any Indicates the item's identifier or caption to look for. The id can include \ to locate exactly an item by parent\child relation
Returns:
Returns null or an object of Item type that item with the giving identifier
Type
Item

Open(id) → {Menu}

The Open() method opens the float-menu(s) giving the item's identfier (if no canvas has been specified, the menu is shown as shortcut/context-menu)
Parameters:
Name Type Description
id any Indicates the item's identifier or caption to open. The id can include \ to locate exactly an item by parent\child relation. (if the id is missing/undefined/null the current menu is shown as a shortcut/context-menu)
Returns:
Returns the current menu as an object of Menu type
Type
Menu

Refresh() → {Menu}

The Refresh() method refreshes the entire control (including the float-menu(s)).
Returns:
Returns the control itself as an object of Menu type
Type
Menu

SetAlign(value)

The SetAlign() method horizontally aligns the item's caption.
Parameters:
Name Type Description
value number An integer value that could be one of the following as:
  • -1 {number}, specifies that the item's caption full-fits the item's background. You can use the or ex-HTML tags to align portions of caption inside the item
  • 0 {number}, indicates that the caption is left-aligned
  • +1 {number}, specifies that the caption is centered
  • +2 {number}, specifies that the caption is right-aligned
Example
2 {number}, right aligns the item's caption

SetAlignClient(value)

The SetAlignClient() method aligns the item's client position to sub-item client position, when a float-menu is displayed.
Parameters:
Name Type Description
value boolean A boolean value that specifies the item's client position is aligned to sub-item client position, when a float-menu is displayed
Example
false {boolean}, specifies that the item and its sub-items are not vertically aligned (when a popup is opened)
  true {boolean}, specifies that the item and its sub-items are vertically aligned (when a popup is opened)

SetAlignContextMenu(value)

The SetAlignContextMenu() method changes the horizontal and vertical position of the context/shortcut-menu relative to the x, y coordinates.
Parameters:
Name Type Description
value Menu.AlignContextMenuEnum A Menu.AlignContextMenuEnum value that specifies the horizontal and vertical position of the context/shortcut-menu relative to the x, y coordinates. The Menu.AlignContextMenuEnum type defines the following flags:
  • exLeftAlign (0x00), positions the shortcut menu so that its left side is aligned with the coordinate specified by the x parameter
  • exCenterAlign (0x04), centers the shortcut menu horizontally relative to the coordinate specified by the x parameter
  • exRightAlign (0x08), positions the shortcut menu so that its right side is aligned with the coordinate specified by the x parameter
  • exTopAlign (0x00), positions the shortcut menu so that its top side is aligned with the coordinate specified by the y parameter
  • exVCenterAlign (0x10), centers the shortcut menu vertically relative to the coordinate specified by the y parameter
  • exBottomAlign (0x20), positions the shortcut menu so that its bottom side is aligned with the coordinate specified by the y parameter
The alignContextMenu property has effect only, if the control is opened as a context-menu, using the Open() method.
Example
0 or Menu.AlignContextMenuEnum.exLeftAlign | Menu.AlignContextMenuEnum.exTopAlign {number}, the context-menu is shown aligned to x and y properties
  20 or Menu.AlignContextMenuEnum.exCenterAlign | Menu.AlignContextMenuEnum.exVCenterAlign {number}, centers the context-menu relative to x and y properties
  32 or Menu.AlignContextMenuEnum.exLeftAlign | Menu.AlignContextMenuEnum.exBottomAlign {number}, opens the context-menu right to the x and y properties

SetAllowToggleRadio(value)

The SetAllowToggleRadio() method allows or prevents toggling the radio state
Parameters:
Name Type Description
value boolean Indicates true to allow, and false to prevent toggling the radio state
Example
false {boolean}, no radio-item toggles its state (once the user clicks a checked radio-item, it stays checked (state on 1))
  true {number}, any radio-item toggles its state (once the user clicks a checked radio-item, it gets unchecked (state on 0))

SetArrangeItemsAs(value)

The SetArrangeItemsAs() method defines how the items are arranged on the control (top-level menu).
Parameters:
Name Type Description
value Menu.ArrangeItemsEnum Specifies whether the items are horizontally or vertically aligned. The Menu.ArrangeItemsEnum type supports the following flags:
  • exArrangeItemsHorizontal (1), specifies that the items are horizontally arranged from left to right
  • exArrangeItemsVertical (2), specifies that the items are vertically arranged from top to bottom
  • exArrangeItemsHideTopArrow (0x10), indicates that the arrow for any top-item is not visible (not valid for float-menu)
  • exArrangeItemsPopupAlign (0x20), specifies that the item's float/popup-menu should be displayed to prevent overlapping other items
  • exArrangeItemsWrap (0x100), wraps items on a new row/column (not valid for float-menu)
  • exArrangeItemsScroll (0x200), specifies that the control's scroll bar is displayed if required
  • exArrangeItemsAlignCenter (0x400), centers the items on each row/column
  • exArrangeItemsAlignReverse (0x800), reverses the alignment of the items
Example
561 or Menu.ArrangeItemsEnum.exArrangeItemsHideTopArrow | Menu.ArrangeItemsEnum.exArrangeItemsHorizontal | Menu.ArrangeItemsEnum.exArrangeItemsScroll | Menu.ArrangeItemsEnum.exArrangeItemsPopupAlign {number}, arranges horizontally all items of top-level menu

SetArrSize(Specifies)

The SetArrSize() method changes the size (width and height) to show the item's arrow
Parameters:
Name Type Description
Specifies number a value that defines the size (width and height) to show the item's arrow
Example
0 {number}, indicates that no arrow is shown
 6 {number}, indicates that the arrow is displayed into a square of 6x6 pixels

SetBtnArrSize(Specifies)

Parameters:
Name Type Description
Specifies number a value that defines the size (width and height) to show the button's arrow
Example
0 {number}, indicates that no arrow is shown for an item of button type ([button])
 6 {number}, indicates that the arrow is displayed into a square of 6x6 pixels

SetBtnPad(Specifies)

The SetBtnPad() method changes the padding to apply item's button
Parameters:
Name Type Description
Specifies number | Array.<number> | string a value that could be a numeric value, to btnPad horizontal and vertical size with the same value, or a "x,y" or [x,y] type to specify the btnPadding on h/v size
Example
4 {number}, increases the object's client with 2 * 4-pixels, which includes width and height
  "8,4" {string}, increases the object's width with 2 * 8-pixels and object's height with 2 * 4-pixels
  [8,4] {array}, increases the object's width with 2 * 8-pixels and object's height with 2 * 4-pixels

SetCanvas(canvas, localCanvas)

The SetCanvas() method changes the control's canvas where it runs.
Parameters:
Name Type Description
canvas any A string that indicates the indetifier of the element within the document, or a HTMLCanvasElement reference
localCanvas boolean Specifies whether the canvas is used localy without requesting the canvas to handle the control itself.

SetClientRect(client)

The SetClientRect() method defines a client area for the control.
Parameters:
Name Type Description
client any The client parameter indicates the control's client area as:
  • array of [x,y,width,height] type that specifies the control's client area
  • string, that specifies the identifier of the canvas within the document, so the canvas's client area becomes the control's client area
  • HTMLCanvasElement, that specifies the identifier of the canvas within the document, so the canvas's client area becomes the control's client area

SetClose(value)

The SetClose() method changes the time in ms the sub-menu is closed once the cursor hovers the top-level item.
Parameters:
Name Type Description
value number A numeric value that specifies the time in ms the sub-menu is closed once the cursor hovers the top-level item. No effect if negative, 0 indicates that the sub-menu is closed as soon as the cursor hovers a top-level item, else a positive value that indicates the time in ms the sub-menu is closed once the cursor hovers the top-level item.
  • if positive, indicates the time in ms the sub-menu is closed once the cursor hovers the top-level item.
  • if 0, indicates that the sub-menu is closed as soon as the cursor hovers a top-level item
  • if negative, it has no effect
Example
0 {number}, indicates that the sub-menu is closed as soon as the cursor hovers a top-level item.
 350 {number}, the sub-menu is closed once 350 ms ellapsed after the cursor hovers a top-level item.

SetCloseOnClick(value)

The SetCloseOnClick() method changes the type of items the user can click to close the float-menu(s).
Parameters:
Name Type Description
value Menu.CloseOnClickEnum Specifies whether the items are horizontally or vertically aligned. The Menu.CloseOnClickEnum type defines the following flags:
  • exCloseOnDefault (0), indicates that the float-menu is closed once the user clicks an enabled item with no check, radio or button associated
  • exCloseOnDisabled (1), specifies that the float-menu is closed once the user clicks a disabled item
  • exCloseOnSeparator (2), specifies that the float-menu is closed once the user clicks a separator item
  • exCloseOnButton (4), specifies that the float-menu is closed once the user clicks an item of button-type
  • exCloseOnCheck (8), specifies that the float-menu is closed once the user clicks an item of check-type
  • exCloseOnRadio (16), specifies that the float-menu is closed once the user clicks an item of radio-type
  • exCloseOnState (24), specifies that the float-menu is closed once the user clicks an item of check or radio-type
  • exCloseOnAny (-1), specifies that the float-menu is closed once the user clicks any type of item anywhere
Example
0 or Menu.CloseOnClickEnum.exCloseOnDefault {number}, specifies that the float-menu is closed once the user clicks an enabled item with no check, radio or button associated
  -1 or Menu.CloseOnClickEnum.exCloseOnAny {number}, specifies that the float-menu is closed once the user clicks any type of item anywhere

SetCriAlign(value)

The SetCriAlign() method vertically aligns the check-box/radio-button or the item's image.
Parameters:
Name Type Description
value boolean Specifies whether the check-box/radio-button or the item's image are vertically aligned.
Example
false {boolean}, check-box/radio-button or the item's image is not vertically aligned
 true {boolean}, check-box/radio-button or the item's image is vertically aligned

SetCriFlat(value)

The SetCriFlat() method shows or hides the menu's flat bar.
Parameters:
Name Type Description
value Menu.FlatEnum Specifies whether the menu's flat bar is visible or hidden. The Menu.FlatEnum type supports the following values:
  • exNormal (0), indicates that the menu's flat bar is not shown
  • exShowFlat (1), indicates that the menu's flat bar is visible only if the menu contains items with check, radio or image
  • exAlwaysFlat (2), indicates that the menu's flat bar is always visible
Example
2 or Menu.FlatEnum.exAlwaysFlat {number}, defines a flat-menu

SetCriPad(Specifies)

The SetCriPad() method changes the padding to apply to a check-box/radio-button or the item's image
Parameters:
Name Type Description
Specifies number | Array.<number> | string a value that could be a numeric value, to criPad horizontal and vertical size with the same value, or a "x,y" or [x,y] type to specify the criPadding on h/v size
Example
4 {number}, increases the object's client with 2 * 4-pixels, which includes width and height
  "8,4" {string}, increases the object's width with 2 * 8-pixels and object's height with 2 * 4-pixels
  [8,4] {array}, increases the object's width with 2 * 8-pixels and object's height with 2 * 4-pixels

SetCriSize(Specifies)

The SetCriSize() method changes the size (width and height) to show a check-box/radio-button or the item's image
Parameters:
Name Type Description
Specifies number a value that defines the size (width and height) to show a check-box/radio-button or the item's image
Example
16 {number}, indicates that any check-box, radio or image uses a 16x16 rectangle to display it within the item

SetCursors(value)

The SetCursors() method changes the mouse cursor to be displayed when pointing over different parts of the control.
Parameters:
Name Type Description
value string A string expression that defines the mouse cursor to be displayed when pointing over different parts of the control. The cursors property supports any of the following parts:
  • "menu" (menu), defines the visual appearance for the entire menu
  • "flat" (flat), defines the visual appearance for menu's flat bar (usually shown in the left side of the menu)
  • "sep" (separator), defines the visual appearance to display separator-items
  • "item" (item), defines the visual appearance for the item's background. It covers all parts of the item as check, image, caption/button, popup arrow and sub-items
  • "sub" (sub-items), defines the visual appearance to display sub-items of the item (while the item is grouped)
  • "arr" (arrow), defines the visual appearance to display item's arrow (while the item contains un-grouped sub-items)
  • "cap" (caption), defines the visual appearance for the item's caption
  • "img" (image), defines the visual appearance to display the item's image
  • "chk" (check), defines the visual appearance to display the item's check-box
  • "rad" (radio), defines the visual appearance to display the item's radio-button
  • "btn" (button), defines the visual appearance to display the buttons
  • "rarr" (right-arrow), defines the visual appearance to display button's arrow (to right)
  • "barr" (bottom-arrow), defines the visual appearance to display button's arrow (to bottom)
Example
"" {string}, no mouse cursor support
  "pointer(chk,rad,btn)" {string}, indicates that the "pointer" mouse cursor is shown once the cursor hovers the "chk", "rad" or "btn" parts of the control

SetDebug(value)

The SetDebug() method changes the control's debug-mode
Parameters:
Name Type Description
value boolean A boolean value that indicates whether the control is in debug-mode
Example
false {boolean}, no debug-information is displayed
  true {boolean}, debug-information is displayed for each item (usually the item's identifier)

SetItems(value)

The SetItems() method assigns items to the current menu from a string representation.
Parameters:
Name Type Description
value string Specifies the items to assign to the current menu. The format of the items'string representation is (everything between () refers to children, and everything between [] refers to flags):
"item1[flag=value]...[flag=value](sub-item1[flag=value]...[flag=value],...,sub-itemn[flag=value]...[flag=value]),...,itemn[flag=value]...[flag=value](sub-item1[flag=value]...[flag=value],...,sub-itemn[flag=value]...[flag=value])"
The string-representation supports the following flags:
  • [id], specifies the item's identifier, such as [id=10].
  • [align] {number}, horizontally aligns the caption. The align could be -1(full-fits the item), 0(left-alignment), 1(center), or 2( right-alignment) such as [align=2] right-aligns the item.
  • [pad], specifies the item's padding (space between the menu border and the item content). The pad could be one or two numbers, separated by comma, such as [pad=2] or [pad=2,2]
  • [itemsPad], specifies the items padding (space between the menu border and the item content). The itemsPad could be one or two numbers, separated by comma, such as [itemsPad=2] or [itemsPad=2,2]
  • [chk], indicates that the item has a check-box associated. If the [typ] flag is present, the [chk] flag indicates the state of the item, and the [rad] flag is ignored. The chk could be 0 or 1, such as [chk] or [chk=0] for a un-checked item, or [chk=1] for checked item.
  • [rad], indicates that the item has a radio-button associated. If the [typ] flag is present, the [chk] flag indicates the state of the item, and the [rad] flag is ignored. The rad could be 0 or 1, such as [rad] or [rad=0] for a un-checked item, or [rad=1] for checked item.
  • [typ], specifies the type of the item, that can be normal, check or radio. The typ could be 0(normal item), 1(items that display a check/box (chk)) or 2(items that display radio buttons (rad)). If the [typ] flag is present, the [chk] flag indicates the state of the item, and the [rad] flag is ignored. For instance [typ=1], specifies a check-box item
  • [grp], defines the radio group. It should be used when you define more groups of radio buttons. A group of radio buttons means that only one item could be checked at one time. The rad option specifies that the item displays a radio button. Use the grp option to define the group of radio where this button should be associated, If no group of radio buttons is required, the grp could be ignored. For instance, [grp=sample]
  • [img], indicates that the item's image. The img indicates the name of an exontrol.HP, such as [img=logo]
  • [group], specifies how the sub-items are being grouped. The group could be a flag combination of Menu.GroupPopupEnum type, such as [group] to group horizontlly the item, or [group=0x100] to group vertically the items
  • [arrow], indicates whether the item's popup-arrow is shown or hidden. The arrow could be 0 to hide the arrow, or not-zero to show the arrow, such as [arrow] or [arrow=0] to hide the arrow, or [arrow=1] to show the arrow
  • [hid], hides/shows the item. The hid could be 0 which indicates that the item is hidden. Any other value makes the item visible, such as [hid] or [hid=0] to hide the item, or [hid=1] to show the item
  • [captionWidth] or [cw], specifies the width to show the HTML caption of the item, where value could be a integer expression. A negative value indicates that no limitation is applied to the item's caption, so no truncate caption is shown. For instance [cw=128]
  • [captionHeight] or [ch], specifies the height to show the HTML caption of the item, where value could be a integer expression. A negative value indicates that no limitation is applied to the item's caption, so no truncate caption is shown. For instance [ch=128]
  • [height], specifies the height to display the item, where value could be a integer expression (it applies to all parts of the item). For instance [height=64]
  • [width], specifies the width to display the item, where value could be a integer expression (it applies to all parts of the item). For instance [width=64]
  • [button], associates a button with the item. The value could be a flag combination of Menu.ShowAsButtonEnum type, such as [button] or [button=1] makes the item to display a button, or [button=0] disables displaying any button.
  • [spchk], indicates whether the sub-items/popup of giving item are shown when the item is checked. The value could be 0, which indicates that it has no effect, or non-zero to show the sub-item when the item is checked. For instance [spchk]
  • [show], specifies how an item that has a check-box/radio-button should be displayed. The value could be any value of Menu.ShowCheckedAsSelectedEnum type. For instance [show=-1] (the exDisplayItemCheckHighlight value highlights the checked item)
  • [showdis], makes the item to show as disabled, while it is still enabled. The flag is applied to all descendents. Any value not-zero indicates that the item is shown as disabled. For instance [showdis]
  • [tab], indicates the identifier of the item that displays the sub-items of the current item. For instance: [tab=page] or [tab=1]
  • [dis], disables the item. The flag is applied to all descendents. Any value not-zero indicates that the item is enabled. For instance [dis]
  • [sep], specifies an separator item, such as [sep]. The value is ignored if provided. For instance [sep]
  • [popupalign] or [pa], indicates how the sub-menu/popup/float is aligned relative to the parent item (Menu.ShowPopupAlignEnum). For instance [pa=1] (The exShowPopupAlignDown value indicates that the sub-menu/popup is shown down-aligned relative to the parent item)
  • [shapes], specifies the shapes to be applied on the item only. For instance [shapes=dfitem(item),dfcap(cap)]
  • [cursors], defines the mouse cursor to be displayed when pointing over a part of the item only. For instance [cursors=pointer(item)]
  • [close], specifies whether clicking the item closes the float-menu (Menu.CloseOnClickEnum). For instance [close=-1], closes the context-menu once the user clicks the items (no matter, if it is of check, radio or button type)
Example
"" {string}, clears the items collection
 "Popup(A,B,C)" {string}, adds a popup-item with three sub-items A, B and C
 "Popup[group](A,B,C)" {string}, adds an item with three sub-items A, B and C, and all items are visible and displayed as an horizontally group
 "Popup[group][chk][spchk](A,B,C)" {string}, adds an item with three sub-items A, B and C, but A, B and C sub-items are visible and displayed only if the popup is checked

SetItemsPad(Specifies)

The SetItemsPad() method changes the padding the sub-items section of the item (space between the menu border and the items content).
Parameters:
Name Type Description
Specifies number | Array.<number> | string a value that could be a numeric value, to itemsPad horizontal and vertical size with the same value, or a "x,y" or [x,y] type to specify the itemsPadding on h/v size
Example
4 {number}, increases the object's client with 2 * 4-pixels, which includes width and height
  "8,4" {string}, increases the object's width with 2 * 8-pixels and object's height with 2 * 4-pixels
  [8,4] {array}, increases the object's width with 2 * 8-pixels and object's height with 2 * 4-pixels

SetLocked(value)

The SetLocked() method locks or unlocks the control.
Parameters:
Name Type Description
value boolean A boolean value that indicates whether the control is locked(protected) or unlocked
Example
false {boolean}, unlocks the control (can select any item)
  true {boolean}, locks the control (can't select any item)

SetOpen(value)

The SetOpen() method changes the time in ms the top-level item opens its sub-menu once the cursor hovers it.
Parameters:
Name Type Description
value number A numberic value that specifies the time in ms the top-level item opens its sub-menu once the cursor hovers it, as explained:
  • if positive, indicates the time in ms the top-level item opens its sub-menu once the cursor hovers it.
  • if 0, indicates that the top-level item opens its sub-menu as soon as cursor hovers it
  • if negative, indicates that the item requires click to to open its sub-menu
Example
0 {number}, indicates that the top-level item opens its sub-menu as soon as cursor hovers it.
 -1 {number}, indicates that the top-level item opens its sub-menu as soon as user clicks it.

SetOptions(nOptions, bIncludeAllopt) → {boolean}

The SetOptions() method applies new options to the Menu element
Parameters:
Name Type Attributes Description
nOptions Menu.Options Specifies an object of Menu.Options type that indicates the new options to apply
bIncludeAll boolean <optional>
Indicates whether all fields of nOptions are included in the element's oOpts object
Returns:
Returns true, if there were options applied to the element
Type
boolean

SetOutClose(value)

The SetOutClose() method changes the time in ms the control closes all its float-menu as soon as the cursor hovers outside portion of the menu.
Parameters:
Name Type Description
value number A numeric value that specifies the time in ms the control closes all its float-menu as soon as the cursor hovers outside portion of the menu, as explained:
  • if positive, specifies the time in ms the control closes all its float-menu as soon as the cursor hovers outside portion of the menu
  • if 0, indicates that the menu's floats are closed as soon as the cursor hovers outside portion of it
  • if negative, it has no effect
Example
0 {number}, indicates that the menu's floats are closed as soon as the cursor hovers outside portion of it
 350 {number}, the control's float-menus are closed once 350 ms ellapsed after the cursor hovers outside portion of the menu

SetPad(Specifies)

The SetPad() method changes the item's padding (space between the menu border and the item content).
Parameters:
Name Type Description
Specifies number | Array.<number> | string a value that could be a numeric value, to pad horizontal and vertical size with the same value, or a "x,y" or [x,y] type to specify the padding on h/v size
Example
4 {number}, increases the object's client with 2 * 4-pixels, which includes width and height
  "8,4" {string}, increases the object's width with 2 * 8-pixels and object's height with 2 * 4-pixels
  [8,4] {array}, increases the object's width with 2 * 8-pixels and object's height with 2 * 4-pixels

SetPopupRatio(value)

The SetPopupRatio() method changes the maximum ratio of the document's view page, a float or a popup menu can be shown.
Parameters:
Name Type Description
value number A numeric value that specifies a positive number that specifies the maximum ratio of the document's view page, a float or a popup menu can be shown. For instance, 1/2 indicates that the width / height of the float-menu can not exceed half of the width / height of the document's v No effect if negative, 0 indicates that the menu's floats are closed as soon as the cursor hovers outside portion of it, else a positive vb-menu is closed once the cursor hovers the out-level item.
Example
0 {number}, indicates that the size of the float-menu is not influenced by the document's view size, so it will be displayed entirely as it is
  0.5 {number}, indicates that the width / height of the float-menu can not exceed half of the width / height of the document's view page (control's scroll is automatically added if exArrangeItemsScroll flag is specified)

SetReadOnly(value)

The SetReadOnly() method sets the control in read-only mode
Parameters:
Name Type Description
value boolean A boolean value that indicates whether the control is read-only
Since:
  • 1.8
Example
false {boolean}, the user can select any item
  true {boolean}, the user can not select the items

SetScrollClip(Specifies)

Parameters:
Name Type Description
Specifies boolean a value that indicates whether the control's scroll bar is clipped
Example
false {boolean}, the scroll is not clipped, so it is shown over the menu
 true {boolean}, the scroll and items portions of the menu are separatly

SetScrollOpt(Defines)

Parameters:
Name Type Description
Defines exontrol.ScrollBar.Options an object of exontrol.ScrollBar.Options type that specifies the options (UI visual appearance, behavior) to display the control's scroll bar.

SetScrollSize(Specifies)

Parameters:
Name Type Description
Specifies number a value that defines the size (width and height) to display the control's scroll bar
Example
0 {number}, hides the menu's scroll-bar but scrolling it is still posible by drag. Click an item and drag outside the margins so the menu gets scrolled
 4 {number}, defines a 4-pixels wide scroll bar

SetSepSize(Specifies)

Parameters:
Name Type Description
Specifies number a value that defines the size to show a separator item
Example
0 {number}, hides all separator items ([sep])
 4 {number}, specifies the separator items of 4-pixels size

SetShapes(value)

The SetShapes() method changes the shapes each part of the control can display.
Parameters:
Name Type Description
value string A string expression that defines the shapes each part of the control can display. The format of shapes property is:
"shape(part),shape(part),..."
where:
  • "shape", defines the shape to apply on the UI part as one of the following:

    ◦ any of 140 color names any browser supports (such as red, blue, green, ...)
    ◦ hexadecimal colors, is specified with: #RRGGBB, where the RR (red), GG (green) and BB (blue) hexadecimal integers specify the components of the color. All values must be between 00 and FF (such as #0000ff which defines a blue background)
    ◦ hexadecimal colors with transparency, is specified with: #RRGGBBAA, where AA (alpha) value must be between 00 and FF (such as #0000ff80 which defines a semi-transparent blue background)
    ◦ RGB colors, is specified with the RGB(red, green, blue) function. Each parameter (red, green, and blue) defines the intensity of the color and can be an integer between 0 and 255( such as rgb(0,0,255) that defines a blue background)
    ◦ RGBA colors, are an extension of RGB color values with an alpha channel as RGBA(red, green, blue, alpha) function, where the alpha parameter is a number between 0.0 (fully transparent) and 1.0 (fully opaque) ( such as rgba(0,0,255,0.5) which defines a semi-transparent blue background)
    ◦ HSL colors, is specified with the HSL(hue, saturation, lightness) function, where hue is a degree on the color wheel (from 0 to 360) - 0 (or 360) is red, 120 is green, 240 is blue. saturation is a percentage value; 0% means a shade of gray and 100% is the full color. lightness is also a percentage; 0% is black, 100% is white. HSL stands for hue, saturation, and lightness - and represents a cylindrical-coordinate representation of colors (such as hsl(240, 100%, 50%) that defines a blue background)
    ◦ HSLA colors, are an extension of HSL color values with an alpha channel - which specifies the opacity of the object as HSLA(hue, saturation, lightness, alpha) function, where alpha parameter is a number between 0.0 (fully transparent) and 1.0 (fully opaque) (such as hsla(240, 100%, 50%,0.5) that defines a semi-transparent blue background)
    ◦ a JSON representation of the shape object to apply (while it starts with { character, such as '{"normal": {"primitive": "RoundRect","fillColor":"black","tfi": {"fgColor": "white"}}}')
    ◦ specifies the name of the field within the exontrol.Shapes.Menu object (while it starts with a lowercase letter, such as dfitem which refers to exontrol.Shapes.Menu.dfitem shape)
    ◦ specifies the name of the field within the exontrol.Shapes object (while it starts with an uppercase letter, such as Button which refers to exontrol.Shapes.Button shape)

  • "part", defines the name of the part the shape is applied on (as defined bellow)
The shapes property supports any of the following parts:
  • "menu" (menu), defines the visual appearance for the entire menu
  • "flat" (flat), defines the visual appearance for menu's flat bar (usually shown in the left side of the menu)
  • "sep" (separator), defines the visual appearance to display separator-items
  • "item" (item), defines the visual appearance for the item's background. It covers all parts of the item as check, image, caption/button, popup arrow and sub-items
  • "sub" (sub-items), defines the visual appearance to display sub-items of the item (while the item is grouped)
  • "arr" (arrow), defines the visual appearance to display item's arrow (while the item contains un-grouped sub-items)
  • "cap" (caption), defines the visual appearance for the item's caption
  • "img" (image), defines the visual appearance to display the item's image
  • "chk" (check), defines the visual appearance to display the item's check-box
  • "rad" (radio), defines the visual appearance to display the item's radio-button
  • "btn" (button), defines the visual appearance to display the buttons
  • "rarr" (right-arrow), defines the visual appearance to display button's arrow (to right)
  • "barr" (bottom-arrow), defines the visual appearance to display button's arrow (to bottom)
Example
null {null}, specifies the default visual appearance
 "" {string}, no shape (no visual appearance is applied to any part of the control)
 "red(item)", "#FF0000(item)", "rgb(255,0,0)(item)", "rgba(255,0,0,1)(item)" {string}, shows all-items in red
 '{"hover":{"frameColor":"black","pad":-0.5}}(item)' {string}, draws a black-frame arround the item being hovered
 "xxx(d),yyy(d,m),zzz(y)"  {string}, specifies that the exontrol.Shapes.Menu.xxx combined with exontrol.Shapes.Menu.yyy object defines the visual appearance of "d" part of the control, exontrol.Shapes.Menu.yyy object defines the visual appearance of "m" part of the control and exontrol.Shapes.Menu.zzz object defines the visual appearance of "y" part of the control

SetShow(value)

The SetShow() method changes how an item that has a check-box/radio button is displayed.
Parameters:
Name Type Description
value Menu.ShowCheckedAsSelectedEnum Specifies how an item that has a check-box/radio button is displayed. The Menu.ShowCheckedAsSelectedEnum type defines the following values:
  • exDisplayItemCheckDefault (0), indicates that no highlight is applied to the item's check/radio
  • exDisplayItemCheckHighlight (-1), highlights the checked item
  • exDisplayItemHighlight (1), highlights the checked item, but hides the item's check/radio button
Example
1 (Menu.ShowCheckedAsSelectedEnum.exDisplayItemHighlight) {number}, specifies that any checked-item gets highlighted, by not showing the item's check/radio button

SetSmoothSel(value)

The SetSmoothSel() method changes the time in ms the control's selection goes from one state to another.
Parameters:
Name Type Description
value number A numeric value that specifies the time in ms the control's selection goes from one state to another.
Example
0 {number}, no smooth changes once the user selects a new item
  125 {number}, specifies that a smooth-transition is performed from a layout to another for 125 ms.

SetSubArrangeItemsAs(value)

The SetSubArrangeItemsAs() method defines how the items are arranged on float-menu.
Parameters:
Name Type Description
value Menu.ArrangeItemsEnum Specifies whether the items are horizontally or vertically aligned. The Menu.ArrangeItemsEnum type supports the following flags:
  • exArrangeItemsHorizontal (1), specifies that the items are horizontally arranged from left to right
  • exArrangeItemsVertical (2), specifies that the items are vertically arranged from top to bottom
  • exArrangeItemsHideTopArrow (0x10), indicates that the arrow for any top-item is not visible (not valid for float-menu)
  • exArrangeItemsPopupAlign (0x20), specifies that the item's float/popup-menu should be displayed to prevent overlapping other items
  • exArrangeItemsWrap (0x100), wraps items on a new row/column (not valid for float-menu)
  • exArrangeItemsScroll (0x200), specifies that the control's scroll bar is displayed if required
  • exArrangeItemsAlignCenter (0x400), centers the items on each row/column
  • exArrangeItemsAlignReverse (0x800), reverses the alignment of the items
Example
257 or Menu.ArrangeItemsEnum.exArrangeItemsHorizontal | Menu.ArrangeItemsEnum.exArrangeItemsWrap {number}, wraps items within the float-menu
 546 or Menu.ArrangeItemsEnum.exArrangeItemsVertical | Menu.ArrangeItemsEnum.exArrangeItemsScroll | Menu.ArrangeItemsEnum.exArrangeItemsPopupAlign {number}, arranges vertically the items within the float-menu

SetSubClose(value)

The SetSubClose() method changes the time in ms the sub-menu is closed once the cursor hovers the second-level item (it is applied to any level excepts the top-level).
Parameters:
Name Type Description
value number A numeric value that specifies the time in ms the sub-menu is closed once the cursor hovers the second-level item, as explained:
  • if positive, indicates the time in ms the sub-menu is closed once the cursor hovers the second-level item
  • if 0, indicates that the sub-menu is closed as soon as the cursor hovers a second-level item
  • if negative, it has no effect
Example
0 {number}, indicates that the sub-menu is closed as soon as the cursor hovers a second-level item
 350 {number}, the sub-menu is closed once 350 ms ellapsed after the cursor hovers the second-level item

SetSubOpen(value)

The SetSubOpen() method changes the time in ms the second-level item opens its sub-menu once the cursor hovers it (it is applied to any level excepts the top-level).
Parameters:
Name Type Description
value number A numeric value that specifies the time in ms the second-level item opens its sub-menu once the cursor hovers it, as explained:
  • if positive, indicates the time in ms the item opens its sub-menu once the cursor hovers it.
  • if 0, indicates that the item opens its sub-menu as soon as the cursor hovers it
  • if negative, it has no effect so the item requires click in order to open its sub-menu
Example
0 {number}, indicates that the item opens its sub-menu as soon as the cursor hovers it
 -1 {number}, indicates that the item's sub-menu is opened once the user clicks it

SetTfi(value)

The SetTfi() method sets the font attributes to apply on captions of the control.
Parameters:
Name Type Description
value string | object Indicates a string representation such as "b monospace 16" or as an object such as {bold: true, fontName: "monospace", fontSize: 16}.

The value as {string} supports any of the following keywords (each keyword can be specified using first letters only such as "b" for "bold) separated by space characters:

  • bold, displays the text in bold (equivalent of <b> tag)
  • italic, displays the text in italics (equivalent of <i> tag)
  • underline, underlines the text (equivalent of <u> tag)
  • strikeout, specifies whether the text is strike-through (equivalent of <s> tag)
  • <fontName name>, specifies the font's family (equivalent of <font name> tag)
  • <fontSize size>, specifies the size of the font (equivalent of <font ;size> tag)
  • <fgColor CSSColor>, specifies the text's foreground color (equivalent of <fgcolor> tag)
  • <bgColor CSSColor>, specifies the text's background color (equivalent of <bgcolor> tag)
  • <shaColor CSSColor;width;offset>, defines the text's shadow (equivalent of <sha color;width;offset> tag)
  • <outColor CSSColor>, shows the text with outlined characters (CSScolor) (equivalent of <out color> tag)
  • <graColor CSSColor;mode;blend>, defines a gradient text (equivalent of <gra color;mode;blend> tag)

Any other word within the string value that's not recognized as a keyword is interpreted as:

  • name of the font (not a number), specifies the font's family (equivalent of <font name> tag)
  • size of the font (number), specifies the size of the font (equivalent of <font ;size> tag)

The value as {object} supports any of the following fields:

  • bold {boolean}, displays the text in bold (equivalent of <b> tag)
  • italic {boolean}, displays the text in italics (equivalent of <i> tag)
  • underline {boolean}, underlines the text (equivalent of <u> tag)
  • strikeout {boolean}, specifies whether the text is strike-through (equivalent of <s> tag)
  • fontName {string}, specifies the font's family (equivalent of <font name> tag)
  • fontSize {number}, specifies the size of the font (equivalent of <font ;size> tag)
  • fgColor {string}, specifies the text's foreground color (CSScolor) (equivalent of <fgcolor> tag)
  • bgColor {string}, specifies the text's background color (CSScolor) (equivalent of <bgcolor> tag)
  • shaColor {object}, specifies an object of {color, width, offset} type that defines the text's shadow (equivalent of <sha color;width;offset> tag), where:
    • color {string}, defines the color of the text's shadow (CSScolor)
    • width {number}, defines the size of the text's shadow
    • offset {number}, defines the offset to show the text's shadow relative to the text
  • outColor {string}, shows the text with outlined characters (CSScolor) (equivalent of <out color> tag)
  • graColor {object}, specifies an object of {color, mode, blend} type that defines a gradient text (equivalent of <gra color;mode;blend> tag), where:
    • color {string}, defines the gradient-color (CSScolor)
    • mode {number}, defines the gradient mode as a value between 0 and 4
    • blend {number}, defines the gradient blend as a value between 0 and 1

CSSColor or CSS legal color values can be specified by the following methods:

  • Hexadecimal colors, is specified with: #RRGGBB, where the RR (red), GG (green) and BB (blue) hexadecimal integers specify the components of the color. All values must be between 00 and FF. For example, #0000ff value is rendered as blue, because the blue component is set to its highest value (ff) and the others are set to 00.
  • Hexadecimal colors with transparency, is specified with: #RRGGBBAA, where AA (alpha) value must be between 00 and FF. For example, #0000ff80 defines a semi-transparent blue.
  • RGB colors, is specified with the RGB(red, green, blue) function. Each parameter (red, green, and blue) defines the intensity of the color and can be an integer between 0 and 255. For example, rgb(0,0,255) defines the blue color.
  • RGBA colors, are an extension of RGB color values with an alpha channel as RGBA(red, green, blue, alpha) function, where the alpha parameter is a number between 0.0 (fully transparent) and 1.0 (fully opaque). For example, rgba(0,0,255,0.5) defines a semi-transparent blue.
  • HSL colors, is specified with the HSL(hue, saturation, lightness) function, where hue is a degree on the color wheel (from 0 to 360) - 0 (or 360) is red, 120 is green, 240 is blue. saturation is a percentage value; 0% means a shade of gray and 100% is the full color. lightness is also a percentage; 0% is black, 100% is white. HSL stands for hue, saturation, and lightness - and represents a cylindrical-coordinate representation of colors. For example, hsl(240, 100%, 50%) defines the blue color.
  • HSLA colors, are an extension of HSL color values with an alpha channel - which specifies the opacity of the object as HSLA(hue, saturation, lightness, alpha) function, where alpha parameter is a number between 0.0 (fully transparent) and 1.0 (fully opaque). For example, hsla(240, 100%, 50%,0.5) defines a semi-transparent blue.
  • Predefined/Cross-browser color names, 140 color names are predefined in the HTML and CSS color specification. For example, blue defines the blue color.
Example
null {null}, the tfi field is ignored
  "bold monospace 16 &lt;fg blue>" {string}, defines Monospace font of 16px height, bold and blue
  {bold: true, fontName: "monospace", fontSize: 16, fgColor: "blue"} {object}, defines Monospace font of 16px height, bold and blue

SetWheelChange(value)

The SetWheelChange() method changes the amount the control scrolls when the user rolls the mouse wheel.
Parameters:
Name Type Description
value number A value that specifies the amount the control scrolls when the user rolls the mouse wheel.
Example
0 {number}, locks any action the mouse's wheel performs
  1 {number}, indicates that the scrollOpt.wheelChange property is applied for 1-time when user rotates the mouse wheel. Changes the scrollOpt.wheelChange property to provide a different step to scroll once the user rotates the mouse wheel

SetX(value)

The SetX() method changes the horizontal position to display the context/shortcut-menu relative to document.
Parameters:
Name Type Description
value number A numeric value that specifies the horizontal position to display the context/shortcut-menu relative to document.
Example
event.pageX {number}, The pageX read-only property of the MouseEvent(event) interface returns the X (horizontal) coordinate (in pixels) at which the mouse was clicked, relative to the left edge of the entire document.

SetXY(x, y)

The SetXY() method changes the horizontal and vertical position to display the context/shortcut-menu relative to document.
Parameters:
Name Type Description
x number A number value that specifies the horizontal position to display the context/shortcut-menu relative to document.
y number A number value that specifies the vertical position to display the context/shortcut-menu relative to document.

SetY(value)

The SetY() method changes the vertical position to display the conteyt/shortcut-menu relative to document.
Parameters:
Name Type Description
value number A numeric value that specifies the vertical position to display the conteyt/shortcut-menu relative to document.
Example
event.pageY {number}, The pageY read-only property of the MouseEvent(event) interface returns the Y (vertical) coordinate in pixels of the event relative to the whole document.

Shuffle(ratio)

The Shuffle() method arranges randomly all items within the control (the Refresh() method always resets any previous shuffle).
Parameters:
Name Type Description
ratio number specifies how far each element is randomized relative to the current size of the layout. For instance, 0 indicates that the element is not moved/shuffled, while 1, indicates that the element can randomize its position up to one width/height.

toString() → {string}

The toString() method convert the menu to a string whenever the item is used in a string context
Returns:
Returns the menu’s string representation
Type
string

Unshuffle()

The Unshuffle() method restores the items of the control in case they were shuffled.

Update(callback, thisArgopt)

The Update() method locks the control's paint during the callback, and invalidates the control once the method ends.
Parameters:
Name Type Attributes Description
callback callback Indicates a callback to perform changes within the control
thisArg any <optional>
Specifies the value of "this" keyword during the callback. If missing/empty/undefined the thisArg points to the control itself, as an object of Menu type

Events

oncheck

The oncheck() method notifies your application that an item has been checked.
Parameters:
Name Type Description
oEvent Item Indicates an object of Item type being checked.
Example
The following samples display the item being checked:

oMenu.oncheck = function (oEvent)
{
 console.log(oEvent);
}

or

oMenu.Listeners.Add("oncheck", function (oEvent)
{
 console.log(oEvent);
})

where oMenu is an object of Menu type

onclose

The onclose() method notifies your application that a float-menu has been closeed
Parameters:
Name Type Description
oEvent object Specifies an object of Menu type being closeed
Example
The following samples display the popup menu which has been closed:

oMenu.onclose = function (oEvent)
{
 console.log(oEvent);
}

or

oMenu.Listeners.Add("onclose", function (oEvent)
{
 console.log(oEvent);
})

where oMenu is an object of Menu type

onlayoutchange

The onlayoutchange() method notifies your application that a new layout is about to be applied on the control.
Parameters:
Name Type Description
oEvent Layout Specifies an object of Layout type that specifies the control's new layout
Example
The following samples display a message once a new layout for the menu has been built:

oMenu.onlayoutchange = function (oEvent)
{
 console.log(oEvent);
}

or

oMenu.Listeners.Add("onlayoutchange", function (oEvent)
{
 console.log(oEvent);
})

where oMenu is an object of Menu type

onmodal

The onmodal() method occurs once that the control's modal-mode starts or ends (one or more float-menus are being displayed)
Parameters:
Name Type Description
oEvent boolean Specifies whether the control's modal-mode starts. If true it indicates that the first float-menu is being displayed, while if false it indicates that the control displays no more any float-menus
Example
The following samples display a message once one or more float-menus are being displayed:

oMenu.onmodal = function (oEvent)
{
 console.log(oEvent);
}

or

oMenu.Listeners.Add("onmodal", function (oEvent)
{
 console.log(oEvent);
})

where oMenu is an object of Menu type

onopen

The onopen() method notifies your application that a new float-menu has been opened
Parameters:
Name Type Description
oEvent Menu Specifies an object of Menu type being opened
Example
The following samples display the popup menu which has been opened:

oMenu.onopen = function (oEvent)
{
 console.log(oEvent);
}

or

oMenu.Listeners.Add("onopen", function (oEvent)
{
 console.log(oEvent);
})

where oMenu is an object of Menu type

onselect

The onselect() method notifies your application that an item has been selected/clicked (excluding popup-items).
Parameters:
Name Type Description
oEvent Item Indicates an object of Item type being clicked.
Example
The following samples display the item being selected:

oMenu.onselect = function (oEvent)
{
 console.log(oEvent);
}

or

oMenu.Listeners.Add("onselect", function (oEvent)
{
 console.log(oEvent);
})

where oMenu is an object of Menu type

onuncheck

The onuncheck() method notifies your application that an item has been unchecked.
Parameters:
Name Type Description
oEvent Item Indicates an object of Item type being unchecked.
Example
The following samples display the item being unchecked:

oMenu.onuncheck = function (oEvent)
{
 console.log(oEvent);
}

or

oMenu.Listeners.Add("onuncheck", function (oEvent)
{
 console.log(oEvent);
})

where oMenu is an object of Menu type