# JSMenu

## Overview

`JSMenu` is a wrapper for scripting menu objects, providing properties and methods to define and manage menus in a user interface.

The **name** property serves as the identifier for a menu, allowing for easy reference during scripting. The **styleClass** property enables the assignment of space-separated CSS style classes to customize the menu's appearance.

JSMenu offers a range of methods to interact with menu items. The `addMenuItem(id)` and `addMenuItem(id, index)` methods allow adding menu items either at the end of the list or at a specific position. Existing menu items can be retrieved using methods like `findMenuItem(id)`, which searches for items by identifier, including nested ones, and `getMenuItem(id)` or `getMenuItemAt(index)`, which retrieve menu items based on identifier or index respectively. The `getMenuItems()` method returns a list of all menu items in the order they appear in the interface.

Additional functionality includes removing menu items using `removeMenuItem(menuItem)` or `removeMenuItem(id)`, both of which return a Boolean indicating success. The `selectMenuItem(menuItem)` method allows selecting a specific menu item in the user interface. For enhanced security considerations, the `getMenuItemsWithSecurity()` method provides items with security metadata, and the `getSelectedItem()` method retrieves the currently selected item.

For further information, refer to the [menu](https://docs.servoy.com/reference/servoy-developer/menu) section of this documentation.

## Properties Summarized

| Type                                                                         | Name                      | Summary                                      |
| ---------------------------------------------------------------------------- | ------------------------- | -------------------------------------------- |
| [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) | [name](#name)             | The menu name (identifier)                   |
| [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) | [styleClass](#styleclass) | Set/Get the menu space separated styleclases |

## Methods Summarized

| Type                                                                                | Name                                                             | Summary                                                                                                                     |
| ----------------------------------------------------------------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| [JSMenuItem](https://docs.servoy.com/reference/servoycore/dev-api/menus/jsmenuitem) | [addMenuItem(id)](#addmenuitem-id)                               | Adds a new menu item, as last item in the list.                                                                             |
| [JSMenuItem](https://docs.servoy.com/reference/servoycore/dev-api/menus/jsmenuitem) | [addMenuItem(id, index)](#addmenuitem-id-index)                  | Adds a new menu item, at a specific position.                                                                               |
| [JSMenuItem](https://docs.servoy.com/reference/servoycore/dev-api/menus/jsmenuitem) | [findMenuItem(id)](#findmenuitem-id)                             | Gets a menu item by identifier.                                                                                             |
| [JSMenuItem](https://docs.servoy.com/reference/servoycore/dev-api/menus/jsmenuitem) | [getMenuItem(id)](#getmenuitem-id)                               | Gets a menu item by identifier.                                                                                             |
| [JSMenuItem](https://docs.servoy.com/reference/servoycore/dev-api/menus/jsmenuitem) | [getMenuItemAt(index)](#getmenuitemat-index)                     | Gets a menu item by index (0 based).                                                                                        |
| [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array)          | [getMenuItems()](#getmenuitems)                                  | Returns all the menus items, either created at design time or at runtime, in the order they will show up in user interface. |
| [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array)          | [getMenuItemsWithSecurity()](#getmenuitemswithsecurity)          |                                                                                                                             |
| [JSMenuItem](https://docs.servoy.com/reference/servoycore/dev-api/menus/jsmenuitem) | [getSelectedItem()](#getselecteditem)                            |                                                                                                                             |
| [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean)      | [removeMenuItem(menuItem)](#removemenuitem-menuitem)             | Removes a menu item from children's list, returns true if element was found an removed                                      |
| [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean)      | [removeMenuItem(id)](#removemenuitem-id)                         | Removes a menu item with given id, returns true if element was found an removed                                             |
| void                                                                                | [selectMenuItem(menuItem)](#selectmenuitem-menuitem)             | Selects a menu item in user interface                                                                                       |
| [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean)      | [selectMenuItemById(menuItemId)](#selectmenuitembyid-menuitemid) | Selects a menu item in user interface (by menu id).                                                                         |

## Properties Detailed

### name

The menu name (identifier)

**Type**\
[String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) the name (identifier) of the menu

### styleClass

Set/Get the menu space separated styleclases

**Type**\
[String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) The space-separated style classes applied to the menu.

**Sample**

```js
menu.styleClass = 'myclass';
```

## Methods Detailed

### addMenuItem(id)

Adds a new menu item, as last item in the list.

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **id** the menu item identifier

**Returns:** [JSMenuItem](https://docs.servoy.com/reference/servoycore/dev-api/menus/jsmenuitem) The newly added menu item.

**Sample**

```js
var item = menu.addMenuItem('item1');
```

### addMenuItem(id, index)

Adds a new menu item, at a specific position.

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **id** the menu item identifier
* [Number](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/number) **index** the index position in list (0 based)

**Returns:** [JSMenuItem](https://docs.servoy.com/reference/servoycore/dev-api/menus/jsmenuitem) The newly added menu item at the specified index.

**Sample**

```js
var mnu = menu.addMenuItem('item1',0);
```

### findMenuItem(id)

Gets a menu item by identifier. Also searches for nested elements. Returns null if not found.

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **id** the menu item identifier

**Returns:** [JSMenuItem](https://docs.servoy.com/reference/servoycore/dev-api/menus/jsmenuitem) The menu item with the specified identifier, including nested items, or null if not found.

**Sample**

```js
var mnu = menu.findMenuItem('item1');
```

### getMenuItem(id)

Gets a menu item by identifier. Returns null if not found.

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **id** the menu item identifier

**Returns:** [JSMenuItem](https://docs.servoy.com/reference/servoycore/dev-api/menus/jsmenuitem) The menu item with the specified identifier, or null if not found.

**Sample**

```js
var mnu = menu.getMenuItem('item1');
```

### getMenuItemAt(index)

Gets a menu item by index (0 based). Returns null if not found.

**Parameters**

* [Number](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/number) **index** the menu item index among its sibblings

**Returns:** [JSMenuItem](https://docs.servoy.com/reference/servoycore/dev-api/menus/jsmenuitem) The menu item at the specified index, or null if the index is out of bounds.

**Sample**

```js
var mnu = menu.getMenuItemAt(0);
```

### getMenuItems()

Returns all the menus items, either created at design time or at runtime, in the order they will show up in user interface.

**Returns:** [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array) An array of all menu items in this menu, in the order they appear in the user interface.

**Sample**

```js
var items = menu.getMenuItems();
```

### getMenuItemsWithSecurity()

**Returns:** [Array](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/array) An array of menu items that have the security flag set to "viewable."

### getSelectedItem()

**Returns:** [JSMenuItem](https://docs.servoy.com/reference/servoycore/dev-api/menus/jsmenuitem) the selectedItem

### removeMenuItem(menuItem)

Removes a menu item from children's list, returns true if element was found an removed

**Parameters**

* [JSMenuItem](https://docs.servoy.com/reference/servoycore/dev-api/menus/jsmenuitem) **menuItem** the menu item to be removed

**Returns:** [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean) True if the specified menu item was removed; false otherwise.

**Sample**

```js
var success = menu.removeMenuItem(item);
```

### removeMenuItem(id)

Removes a menu item with given id, returns true if element was found an removed

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **id** the menu item identifier

**Returns:** [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean) True if a menu item with the specified identifier was removed; false otherwise.

**Sample**

```js
var success = menu.removeMenuItem('item1');
```

### selectMenuItem(menuItem)

Selects a menu item in user interface

**Parameters**

* [JSMenuItem](https://docs.servoy.com/reference/servoycore/dev-api/menus/jsmenuitem) **menuItem** the menu item to be selected

**Returns:** void

**Sample**

```js
menu.selectMenuItem(item);
```

### selectMenuItemById(menuItemId)

Selects a menu item in user interface (by menu id). Returns whether the item was found and selected.

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **menuItemId** the menu item id to be selected

**Returns:** [Boolean](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/boolean) True if the specified menu item was selected; false otherwise.

**Sample**

```js
menu.selectMenuItemId('item1');
```

***