MENU Object
- Last UpdatedNov 07, 2024
- 7 minute read
Members
|
Name |
Type |
Purpose |
|---|---|---|
|
Callback |
STRING Get/Set |
Sets/gets the callback on the menu. |
|
PickedField |
STRING Get Only |
Returns the DTEXT of the last picked menu field. Note: |
|
PickedFieldName |
STRING Get Only |
Returns the field name of the last-picked TOGGLE or CALLBACK field. |
Methods
|
Name |
Result |
Purpose |
|---|---|---|
|
Add('SEPARATOR', {STRING fieldName}) |
NO RESULT |
Append a SEPARATOR field, with an optional STRING argument, 'fieldName', that if present denotes the unique field-name in the menu. |
|
Add('CALLBACK', STRING Dtext, STRING callback, {STRING fieldName}) |
NO RESULT |
Append a CALLBACK field with Dtext, which may contain multi-byte characters, but which cannot be NULL or blank. The argument 'callback' gives the callback command. There is also an optional fieldName argument that, if present, denotes the unique field name in the menu. |
|
Add('FORM', STRING Dtext, STRING formName, {STRING fieldName}) |
NO RESULT |
Append a FORM display field with Dtext, which may contain multi-byte characters, but which cannot be NULL or blank. The argument formName, gives the name of the form to be displayed, which may be NULL but may not be blank. There is also an optional fieldName argument that, if present, denotes the unique field name in the menu. |
|
Add('MENU', STRING DText, STRING menuName, {STRING fieldName}) |
NO RESULT |
Append a MENU (pullright) field with Dtext, which may contain multi-byte characters, but which cannot be NULL or blank. menuName gives the pullright menu name, which may be NULL but may not be blank. There is also an optional fieldName argument that, if present, denotes the unique field name in the menu. |
|
Add('TOGGLE', STRING Dtext, STRING callback, {STRING fieldName}) |
NO RESULT |
Append a TOGGLE field with Dtext, which may contain multi-byte characters, but which cannot be NULL or blank. The argument callback gives the callback command, which must be an open PML function. There is also an optional fieldName argument that, if present, denotes the unique field name in the menu. |
|
Clear() |
NO RESULT |
Removes all menu fields from the menu. Note: |
|
Clear(STRING Dtext) |
NO RESULT |
Removes menu fields starting with the one that matches Dtext onwards. Note: |
|
FieldProperty(STRING menuField, STRING property) |
BOOLEAN |
Get the value of the property named in property for the menu field named in menuField. The allowed values for property are ‘ACTIVE’, ‘VISIBLE’, or ‘SELECTED’. |
|
FullName() |
STRING |
Returns menu object's full name, for example: '!!Form.Menu'. |
|
InsertAfter(STRING menuField, ‘CALLBACK’, STRING Dtext, STRING callback, {STRING fieldName}) |
NO RESULT |
Insert a CALLBACK field with Dtext, which may contain multi-byte characters, but which cannot be NULL or blank, immediately after the menu field identified by menuField. The argument callback gives the callback command. There is also an optional fieldName argument that, if present, denotes the unique field name in the menu. |
|
InsertAfter(STRING menuField, ‘FORM’, STRING Dtext, STRING formName, {STRING fieldName}) |
NO RESULT |
Insert a FORM display field with Dtext, which may contain multi-byte characters, but which cannot be NULL or blank, immediately after the menu field identified by menuField. The argument formName gives the name of the form. There is also an optional fieldName argument that, if present, denotes the unique field name in the menu. |
|
InsertAfter(STRING menuField, ‘MENU’, STRING Dtext, STRING menuName, {STRING fieldName}) |
NO RESULT |
Insert a MENU (pullright) field with Dtext, which may contain multi-byte characters, but which cannot be NULL or blank, immediately after the menu field identified by menuField. The argument menuName gives the name of the form. There is also an optional fieldName argument that, if present, denotes the unique field name in the menu. |
|
InsertAfter(STRING menuField, ‘TOGGLE’, STRING Dtext, STRING menuName, {STRING fieldName}) |
NO RESULT |
Append TOGGLE field with Dtext, which may contain multi-byte characters, but which cannot be NULL or blank, immediately after the menu field identified by menuField. The argument callback gives the callback command, which must be an open PML function. There is also an optional fieldName argument that, if present, denotes the unique field name in the menu. |
|
InsertAfter(STRING menuField, ‘SEPARATOR’, {STRING fieldName}) |
NO RESULT |
Append a SEPARATOR field immediately after the menu field identified by menuField. There is also an optional fieldName argument that, if present, denotes the unique field name in the menu. |
|
InsertBefore(STRING menuField, ‘CALLBACK’, STRING Dtext, STRING callback, {STRING fieldName}) |
NO RESULT |
Insert a CALLBACK field with Dtext, which may contain multi-byte characters, but which cannot be NULL or blank, immediately before the menu field identified by menuField. The argument callback gives the callback command. There is also an optional fieldName argument that, if present, denotes the unique field name in the menu. |
|
InsertBefore(STRING menuField, ‘FORM’, STRING Dtext, STRING formName, {STRING fieldName}) |
NO RESULT |
Insert a FORM display field with Dtext, which may contain multi-byte characters, but which cannot be NULL or blank, immediately before the menu field identified by menuField. The argument formName gives the name of the form. There is also an optional fieldName argument that, if present, denotes the unique field name in the menu. |
|
InsertBefore(STRING menuField, ‘MENU’, STRING Dtext, STRING menuName, {STRING fieldName}) |
NO RESULT |
Insert a MENU (pullright) field with Dtext, which may contain multi-byte characters, but which cannot be NULL or blank, immediately before the menu field identified by menuField. The argument menuName gives the name of the form. There is also an optional fieldName argument that, if present, denotes the unique field name in the menu. |
|
InsertBefore(STRING menuField, ‘TOGGLE’, STRING Dtext, STRING menuName, {STRING fieldName}) |
NO RESULT |
Append TOGGLE field with Dtext, which may contain multi-byte characters, but which cannot be NULL or blank, immediately before the menu field identified by menuField. The argument callback gives the callback command, which must be an open PML function. There is also an optional fieldName argument that, if present, denotes the unique field name in the menu. |
|
InsertBefore(STRING menField, ‘SEPARATOR’, {STRING fieldName}) |
NO RESULT |
Append a SEPARATOR field immediately before the menu field identified by menuField. There is also an optional fieldName argument that, if present, denotes the unique field name in the menu. |
|
Name() |
STRING |
Returns menu object's simple name, for example: 'Menu'. |
|
Owner() |
FORM |
Returns reference to owning form. |
|
PopupGadget() |
GADGET |
Returns the name of the gadget that popped up the menu. The value is unset if the menu was not popped up by a gadget. |
|
Refresh() |
NO RESULT |
Refreshes the display of the gadget. |
|
Select(STRING Dtext, BOOLEAN status) |
NO RESULT |
Set the selected status of TOGGLE field identified by Dtext to the value of status. Note: |
|
Selected( STRING Dtext ) |
BOOLEAN |
Get selected status of the TOGGLE field identified by Dtext. Note: |
|
SetActive(STRING Dtext, BOOLEAN active) |
NO RESULT |
Set the active status of the menu field identified by Dtext. Note: |
|
SetFieldProperty(STRING menuField , STRING property, BOOLEAN value) |
NO RESULT |
Set the value of property with value, for the menu field identified by menuField. The allowed values for property are ‘ACTIVE’, ‘VISIBLE’, or ‘SELECTED’. But see the note below for special cases when you use a SEPARATOR field. |
Note:
Setting the Active and Visible properties of a SEPARATOR field will affect the implied group of fields comprising
the SEPARATOR field and all subsequent fields up to but not including the next SEPARATOR
field.
For each of the Add() methods above, you can use a special field-type to indicate that the field is managed
by core-code i.e. CORESEPARATOR, CORECALLBACK, COREFORM, COREMENU, and CORETOGGLE.
You do not need to specify callback functions for core-managed fields.
Command
MENU objects are owned by FORM objects, and can be created within form setup mode. It is also possible to add a new menu to an existing form - usually for context sensitive pop-up menus.
The recommended way to create a menu and its fields, typically within form setup mode, is:
!menu = !this.newmenu( ‘Menu1’, ‘MAIN’ )
!menu.add( ‘CALLBACK’, ‘save’, ‘<callback>’, ‘field1’ )
!menu.add( ‘FORM’, ‘save asº’, ‘saveForm’, ‘field2’ )
Note:
-
Each menu is either part of the Main menu system or part of the Popup menu system, but cannot belong to both.
-
If you specify neither POPUP nor MAIN at setup time, then the menu’s usage is initially unknown. The system will attempt to deduce the usage type from the first action that references the menu.
-
Menus in the Main system can only appear once. That is, a main system menu cannot be a sub-menu of several menus.
-
Menus in the Popup system may appear only once in a given popup tree, but may be used in any number of popup trees.
-
A menu cannot reference itself, either directly as a pullright of one of its own fields or be a pullright of another menu in its own menu tree.
Note:
You can add menu fields with an optional field-name. If you do not specify a field-name, then you will not be able to refer to it later.
-
You can use a special field-type to indicate that the field is managed by core-code i.e. CORESEPARATOR, CORECALLBACK, COREFORM, COREMENU, and CORETOGGLE.
-
You do not need to specify callback functions for core-managed fields.
An alternative is to use the MENU command, followed by the menu’s ADD commands and terminated by the EXIT command. The full syntax is shown below:
>-- MENU -- gname ‑+- POPUP ‑-. .--------<-------.
+- MAIN --| / |
‘----------‘-+- NL -+- <fmenu> -|
+- PML -----*
+- EXIT ‑---.
‘-----------‘-->
.-----<-----.
/ |
fmenu>-+- ADD -+- fieldname -|
+- CORE ------*
+- SEParator -------------------------------.
‘- dtext -+- rtext -------------------------|
+- MENU -- gname -----------------|
+- FORM -- fname -----------------|
+- CALLback ‑+- rtext ------------|
| ‘--------------------|
‘- TOGgle ‑+- rtext ‑. |
‘---------+- SELected -|
‘------------‘-->