$inlinemenu

Insert or retrieve one or more menu items at the location of a dynamic menu placeholder

Setting menu items: $inlinemenu = MenuItem {;MenuItem^N}

where MenuItem is:

MenuItemId ; Type = Type ; Properties

Getting menu items: Variable = $inlinemenu

Parameters

Parameters
Parameter	Data Type	Description
MenuItem	String	Associative list defining the menu item identifier, type, and properties. The properties that can be specified depend on the type of menu item.
MenuItemId	String	String identifying the menu item; mandatory. For example, `"extra"`. If Type is `cascaded menu` or `included menu`, the referenced menu cannot be a popup menu.
Type	String	Type of menu item; mandatory; valid values are: `separator` `option` `cascaded menu` `included menu` The item type strings are case insensitive. For more information, see Type. Note: If `cascaded menu` or `included menu`, the Referenced_Menu or Nested_Menu properties must also be specified.
Properties	String	Associative list of name-value pairs specifying the properties of the menu item. Properties may be mandatory, depending on the Type.

Menu Item Definition Properties
Property	Value	Example	Description
Text	OptionText	text="Extra tools"	Option text displayed in the menu. Mandatory if Type is `Option` or `Cascaded Menu`. For more information, see Item.
Image	ImageName	`image="@ball.png"` (file) `image="^BALL"` (glyph)	String specifying the name of an image or glyph to be displayed as an icon in front of the option text
Accelerator	Accelerator	`accelerator="FileOpen"`	Accelerator definition for the item; empty by default. For more information, see Accelerator.
HintText	HintText	`hinttext="User-added plug-ins"`	Hint text for the menu item; empty by default. For more information, see Hint Text.
Checked	Boolean	`checked="true"`	Determines whether a check mark is displayed beside the item; false by default.
Disabled	Boolean	`disabled="true"`	Determines whether the item is disabled; `false` by default.
Referenced_Menu	MenuName	`Referenced_menu="Editors"`	String specifying an existing Drop-down menu.For more information, see Referenced Menu .
Nested_Menu	DynamicMenu	`Nested_menu="Preferences"`	String specifying another dynamic menu.

Return Values

Returns error code in $procerror and error description in $procerrorcontext

Values returned by $procerror after $inlinemenu
Value	Description
0	Success
-1	An error occurred.
-1600	The function has been used outside the scope of the current preDisplay context
-1601	The function has been used in a component. It is allowed only in a preDisplay trigger
-1602	The menu item list has been incorrectly defined.
-1603	Referenced menu in cascading menu does not exist
-1604	Menu item identifier is not unique
-1605	Invalid menu item type

Use

Use only in the preDisplay trigger of Menu objects.

The scope of the function is limited to the preDisplay trigger of the dynamic menu for which the trigger was fired.

Description

The $inlinemenu function contains the most recent menu items set for the dynamic menu for which the preDisplay trigger was fired. This means that if $inlinemenu is not set, the last known menu content for the dynamic menu is used.

The function is empty until a valid menu item definition list is assigned to that function. It is therefore not possible to set the content of a dynamic menu except in the preDisplay trigger used to fire it.

The list of menu item definitions is typically built up using the putitem statement or other list handling ProcScript. For more information, see List Handling in ProcScript.

Defining Dynamic Menu Items

The following example builds a dynamic menu. It uses putitem to construct a menu item definition in a variable and then inserts the value of the variable as an item in the current dynamic menu.

trigger preDisplay 
variables
   string strMenuItem
endvariables

; ----------- Insert first menu item in a dynamic menu --------------

;Initialize one menu item in list
  StrMenuItem = ""

;Define menu item "Option A"
  putitem/id strMenuItem, "TYPE", "Option"
  putitem/id strMenuItem, "TEXT", "Option A"
  putitem/id strMenuItem, "Checked", "True"
 
;Insert this item with id "A" into the dynamic menu.
  putitem/id $inlinemenu, "A", strMenuItem

; ----------- Insert second menu item in a dynamic menu -------------

;Initialize one menu item in list.
  StrMenuItem = ""

;Define menu item "Option B"
  putitem/id strMenuItem, "TYPE", "Option"
  putitem/id strMenuItem, "TEXT", "Option B"
  putitem/id strMenuItem, "IMAGE", "ball.png"

;Insert this item with id "B" into the dynamic menu.
  putitem/id $inlinemenu, "B", strMenuItem

end; preDisplay

Defining Nested Dynamic Menus

Caution: Use caution when defining nested dynamic menus because it is possible to create looping menus where a nested menu refers to a generated parent menu.

The following example creates a dynamic menu that references an existing menu and includes a submenu containing a list of attached component instances.

trigger preDisplay 
variables
   string strMenuItem
   string strSubMenu
   string strInstance
endvariables

   $inlinemenu = "" 

; Define the first item as a static cascading menu 
   strMenuItem = ""
   putitem/id strMenuItem, "TYPE", "CASCADED MENU"
   putitem/id strMenuItem, "TEXT", "File"
   putitem/id strMenuItem, "REFERENCED_MENU", "FILE_MENU"

   putitem/id $inlinemenu, "ID_FILE", strMenuItem 

; Define the second item as a dynamic cascading menu 
   strSubMenu = ""  

  ; Define the menu items for the dynamic submenu 
   $1 = 1
   getitem strInstance, $instancechildren, $1 
   while ($status > 0)
      putitem/id strSubMenu, strInstance, "TYPE=Option;TEXT=%%strInstance%%%"

      ; Get next instance
      $1 = $1 + 1
      getitem strInstance, $instancechildren, $1 
   endwhile

  ; Define the dynamic submenu 
   strMenuItem = ""
   putitem/id strMenuItem, "TYPE", "CASCADED MENU"
   putitem/id strMenuItem, "TEXT", "Attached instances"
   putitem/id strMenuItem, "NESTED_MENU", strSubMenu

   putitem/id $inlinemenu, "ID_INSTANCES", strMenuItem     
end; preDisplay

Clear $inlinemenu to ensure that an existing dynamic menu definition is not used.
As the first item in the dynamic menu, define a cascading menu that references an existing File menu.
Insert the cascading file menu item with ID ID_FILE into the dynamic menu.
As the second item in the dynamic menu, define a cascading menu that references another dynamic menu.
Initialize the dynamic submenu definition.
Get the attached component instances and create a menu item definition for each of them.
Define a cascading submenu that contains a list of the attached instances of this component.
Insert the dynamic submenu (id "ID_INSTANCES") into the main dynamic menu.

When the user selects one of the items attached to the instances, that instance is made active with the setformfocus statement.

trigger option
params
   string strId : IN
endparams

   ;Check if this ID is one of the attached instances.
  if (IsAttachedInstance(strId))
     ;Yes our selected menu item has an id which matches
     ;one of our attached instances so we can make this one
     ;current.
     setformfocus strId
  endif
end; option

History
Version	Change
9.1.01	Introduced