Item class (Menu)

Item(text, oParentopt, nPositionopt)

new Item(text, oParentopt, nPositionopt)

The Item class defines the item within the Menu control. The Items property defines the items of the control. Each item can include sub-items, which are delimited by parentheses (). Additionally, each item or sub-item can have one or more flags enclosed in square brackets []. These flags determine the properties of the item, such as its alignment, whether it displays a check-box, its associated image, and other settings. The Item class provides a structured way to represent the menu items and their attributes, allowing for dynamic and customizable menu configurations.

The Item class includes teh following properties:

  • id: The id property specifies the item's identifier
  • caption: The caption property defines the item's ex-HTML caption
  • flags: The flags property holds a map of [name => value] type that specifies the options of the current item. The flags are specified within the item's string representation, such as "[chk]", "[id=10]", "[img=logo]", etc
Parameters:
Name Type Attributes Description
text string | object Indicates a string represemtation that defines the sub-items, such as "Item 1,Item 2,[sep],Check 1[chk],Check 2[chk]" or an object of {caption,flags,subText} type.
oParent Item <optional>
 Specifies an object of Item type that defines the item's parent. If null/missing/undefined the item is considered as root.
nPosition number <optional>
 Specifies the position within the parent's child collection. If missing/undefined the item is added at the end of the collection.

Members

(static, readonly) PartEnum :string

The Item.PartEnum type defines the parts of the Item object. The Item object is composed of different parts, such as the check-box, image, caption, button, arrow, sub-items, and others. The Item.PartEnum provides a set of constants that represent these parts, allowing you to reference them in a clear and consistent way when working with item' properties and methods. By using the Item.PartEnum, you can easily identify and manipulate specific parts of an item within the menu structure. The Layout class uses the Item.PartEnum to define the rectangles of each part of the item, which are essential for rendering and interaction purposes.
Type:
  • string
Properties:
Name value Type Description
exItem item string The exItem field specifies the item's client part (it includes all parts of the item as check, image, caption, popup arrow and sub-items)
exFlat flat string The exFlat field specifies the portion of the menu to show the flat bar
exCheck chk string The exCheck field indicates the item's check-box part.
exRadio rad string The exRadio field indicates the item's radio-button part.
exImage img string The exImage field indicates the item's image/icon part.
exCaption cap string The exCaption field indicates the item's caption part.
exButton btn string The exButton field indicates the item's button part.
exButtonRArrow rarr string The exButtonRArrow field indicates the item's button-select part (shown to the right).
exButtonBArrow barr string The exButtonBArrow field indicates the item's button-select part (shown to the bottom).
exSeparator sep string The exSeparator field indicates the item's separator part.
exArrow arr string The exArrow field indicates the item's arrow part.
exSubItems sub string The exSubItems field indicates the item's sub-items part.
exMenu menu string The exMenu field indicates the entire menu

(static) AutoID :number

The AutoID property holds the auto-incremented identifier for each new item created within the control. The AutoID is used to assign a unique identifier to each item when the [id] flag is not specified in the item's string representation. This property ensures that every item has a distinct identifier, allowing for easy reference and manipulation within the menu structure. The AutoID starts at 0 and increments by 10 for each new item created, providing a simple mechanism for generating unique IDs without conflicts.
Type:
  • number
Example
10 {number}, the first item created without an [id] flag will be assigned an identifier of 10
20 {number}, the second item created without an [id] flag will be assigned an identifier of 20
AutoID

caption :string

The caption property defines the item's ex-HTML caption. The caption is the text that is displayed on the menu item, and it can include HTML formatting to enhance its appearance. For example, you can use HTML tags to make the caption bold, italic, or to include line breaks. The caption is specified within the item's string representation, such as "Item 1[chk]", where "Item 1" is the caption of the item. If the text parameter is an object with a caption property, that value will be used as the item's caption. If the text parameter is a string, it will be treated as the item's caption directly.
Type:
  • string
Example
"&lt;b&gt;File&lt;/b&gt;" {string}, defines the caption of the item as "File" in bold
"New[chk]" {string}, defines the caption of the item as "New", and also specifies that the item has a check-box associated
caption

(readonly) children :array

The children property contains the item's child collection as an array of Item objects. It allows you to access and manipulate sub-items, iterate through them, apply settings, or gather information. With the children property, you can navigate downward in the menu structure and work with related items as needed. The parent property holds a reference to the item's parent, while the root property returns the root item (the root item has no parent item). You can use the children property to access and manipulate an item's sub-items, iterate through them, apply specific settings, or gather information about the children. Using the children property, you can navigate the menu structure downward and work with related items as needed.
Type:
  • array
Since:
  • 5.3
Example
The following sample code enumerates the child items of the current item and logs them in the console:

 oItemchildren.forEach(function(oChildItem)
 {
  console.log(exontrol.ToString.Quote(oChildItem));
 })
children

enabled :boolean

The enabled property controls whether an item is enabled or disabled. An item is considered enabled only if it and all its predecessor items are enabled (not disabled by the [dis] flag). While the [dis] flag in the flags property can also be used to enable or disable an item, the enabled property provides a more straightforward and convenient way to manage an item's state.
Type:
  • boolean
Since:
  • 1.1
Example
oItem.enabled = false, disables the item
 console.log( oItem.enabled ), displays whether the item is enabled
enabled

flags :map

The flags property holds a map of [name => value] pairs that define the options for the current item. The flags property can be null, which indicates that no flags are specified for the item. When defined, it contains a collection of key-value pairs where the key is the flag's name and the value is its corresponding setting. Flags determine various attributes and behaviors of the item, such as its alignment, whether it includes a check-box, its associated image, and other properties. Flags are specified within the item's string representation using notations like [chk], [id=10], [img=logo], and so on. If the text parameter is provided as an object with a flags property, that value is used as the item's flags. If the text parameter is a string, it is parsed to extract the flags from the string representation of the item.
Type:
  • map
Example
The following sample assigns an image to the item when it is selected, by using the "img" flag within the onselect event of the menu:

 oMenu.on("select", function(oItem)
 {
   oItem.setFlag("img", "none");
 })

The setFlag method is used to set a specific flag for the item, such as "img" in this example, which assigns an image to the item when it is selected. The flags property holds the collection of flags for the item, and the setFlag method allows you to modify or add flags dynamically based on user interactions or other conditions.

The oItem.setFlag("img", "none") is equivalent with (oItem.flags = oItem.flags || new Map()).set("img", "none"), which ensures that the flags property is initialized as a Map if it is not already defined, and then sets the "img" flag to "none" for the item.
flags

(readonly) id :any

The id property specifies the item's identifier. The id property gets the identifier as specified by [id] flag, while getID() method gets the item's identifier no matter if it was specified by [id] flag. You can use the debug property to display identifiers for all items within the menu. The AutoID property holds the auto-incremented identifier for each new item created within the control. The AutoID is used to assign a unique identifier to each item when the [id] flag is not specified in the item's string representation. This property ensures that every item has a distinct identifier, allowing for easy reference and manipulation within the menu structure. The AutoID starts at 0 and increments by 10 for each new item created, providing a simple mechanism for generating unique IDs without conflicts.
Type:
  • any
id

image :string

The image property gets or sets the image of the item. The exontrol.HTMLPicture.Add method could be used to add images to the menu. The image could be removed by setting null/undefined/empty value. The image property is a more convenient way to get or set the item's image. The flags([img]) property could be used to get or set the item's image as well, but the image property is more straightforward and easier to use.
Type:
  • string
Since:
  • 1.1
Example
oItem.image = "myImage", sets the item's image to "myImage"
 console.log( oItem.image ), displays the item's image
image

(readonly) parent :Item

The parent property holds a reference to the item's parent. The root property returns the root item (the root item has no parent item). You can use the parent property to traverse the menu structure upwards, accessing the parent item of a given item. This is particularly useful when you need to determine the context of an item within the menu hierarchy or when you want to manipulate the parent item based on certain conditions. By accessing the parent property, you can easily navigate through the menu's structure and access related items as needed.
Type:
Since:
  • 1.1
Example
oItem.parent.caption {string}, returns the caption of the parent item
parent

(readonly) path :Array.<any>

The path property returns the hierarchical path of the current item, including all identifiers from the root down to the item. Each element in the path array is the value of the item's id or caption property. Accessing the path property provides an array representing the location of the item within the menu structure, with each element corresponding to a specific level. The path is constructed by traversing from the current item up to the root, collecting the identifiers of each parent item, and then reversing the order so that the array starts with the root and ends with the current item. This is useful for identifying an item's position in the hierarchy or performing operations based on its location within the menu.
Type:
  • Array.<any>
Since:
  • 1.1
Example
oItem.path.join("\") {string}, returns the path of the item as string, such as "10\20\30"
path

(readonly) root :Item

The root property holds a reference to the root item (the root item has no parent). The root property includes all items of the menu. The parent property returns the item's parent. By accessing the root property, you can easily reference the top-level item in the menu hierarchy, which serves as the entry point to the entire menu structure. This is particularly useful when you need to perform operations that affect the whole menu or when you want to traverse the menu from the top down. The root property provides a convenient way to access the root item without needing to call a method, allowing for more concise code when working with the menu structure.
Type:
Since:
  • 1.1
Example
oItem.root.save() {string}, returns the string representation of the entire menu
root

state :number

The state property indicates the current state of an item and applies only to items of the check-box or radio-button type. The oncheck event is triggered when a user checks an item, and the onuncheck event is triggered when a user unchecks an item. These events are not triggered when the check or radio state is changed programmatically using the state property.
Type:
  • number
Since:
  • 1.1
Example
if ( oItem.state ) {...} // checks whether the item is checked
state

visible :boolean

The visible property shows or hides the item. An item is displayed only if it has a caption, flag, or children, is not marked with the "hid" flag, and its size (width/height), if specified, is greater than 0. You can also control the item's visibility using the flags([hid]) property, but the visible property provides a simpler and more direct way to get or set whether the item is shown.
Type:
  • boolean
Since:
  • 1.1
Example
oMenu.Item("Redo").visible = false, hides the "Redo" item
console.log( oItem.visible ), displays whether the item is visible
visible

Methods

forEachU(callback, thisArg) → {any}

The forEachU() method enumerates recursivelly the child-items, until the callback returns a truthy value. The forEachU() method can be used to find an item by enumerating the item and its descendents, while the enumeration is stopped once the callback returns a truthy value. The root.forEachU(callback) method enumerates the root item and its descendents, while the enumeration is stopped once the callback returns a truthy value. The Menu.Item() method returns the item giving its identifier, caption or path.
Parameters:
Name Type 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 Indicates the value of "this" keyword during the callback (if not specified it refers the current object as an Menu type).
Returns:
Returns the last-result of callback(oItem) call
Type
any

load(text)

The load() method loads the items from a string representation (ToString format). The load() method overrides the current item, and may insert new items on the same level. When you call load() on an item, it replaces the current item's children with the new items defined in the string representation. If the string is empty, null, or undefined, the current item is removed from its parent's child collection. Otherwise, the load() method parses the provided string and creates new child items accordingly. This method is particularly useful for dynamically updating the menu structure based on user input or other runtime conditions, allowing for flexible and responsive menu configurations.

The format of the string representation is the same as the one used for the Menu.Items property, which includes the caption and flags for each item. For example, a string like "Item 1,Item 2,[sep],Check 1[chk],Check 2[chk]" would create two regular items, a separator, and two checkable items under the current item.

Parameters:
Name Type Description
text string Indicates a string represemtation that defines the items, such as "Item 1,Item 2,[sep],Check 1[chk],Check 2[chk]". If empty/null/undefined the current element is removed, else it is replaced.
Example
The following sample code replaces the current item with new items defined in the string representation when the item is selected, by using the onselect event of the menu:

 oMenu.on("select", function(oItem)
 {
   oItem.load("Item[group=0x01](Child 1,Child 2[dis],Child 3)")
 })

The following sample code loads new items into the current item from a string representation:

 oItem.load("Item 1,Item 2,[sep],Check 1[chk],Check 2[chk]")

where oItem is the current item
load

save() → {string}

The save() method returns the current item as a string representation (ToString format). It generates a string representation that includes the item's caption, flags, and any child items, following the same format used for defining menu items. This makes it easy to serialize the menu structure or recreate the item later. The save() method is useful for debugging, as it provides a readable view of an item's structure and properties. When called, it constructs a string containing the item's caption, associated flags, and, if present, the string representations of all child items recursively. The Menu.Items property uses the save() method to generate a string representation of the entire menu structure, offering a convenient way to view or manipulate the menu configuration as text.
Returns:
Returns the string representation of the current item (including its children), such as "Item[group=0x01](Child 1,Child 2[dis],Child 3)"
Type
string
Example
console.log(oItem.save()), logs the string representation of the current item in the console:
save