|
WSupported on Windows
|
USupported on Unix
|
VSupported on OpenVMS
|
NSupported in Synergy .NET
|
status = %M_INFO(subfunction, args)
or
xcall M_INFO(subfunction, args)
Return value
status
An integer value specific to subfunction. (^VAL)
Arguments
subfunction
One of the following: (n)
Retrieve loaded columns.
Determine whether a column or entry is enabled.
Retrieve the entries in a column.
Retrieve information about a menu entry.
Retrieve information about a column’s header.
Retrieve the entry lists in a column.
Retrieve the entries in a list.
Determine the entry that corresponds to a shortcut.
args
Arguments specific to subfunction.
Discussion
%M_INFO enables you to get information about the menu system. See the individual subfunctions for details.
See also
- M_KEYTXT routine for information on getting shortcut text
- M_SCINFO routine for information on getting menu and shortcut entry information
- %M_TEXT routine for information on modifying and retrieving menu entry text
numcols = %M_INFO(D_MENU_COLUMNS, [max], [array], [env][, placed])
or
xcall M_INFO(D_MENU_COLUMNS, [max], [array], [env][, placed])
Return value
numcols
The number of columns that match the default criteria or the criteria specified by the env or placed arguments. (^VAL)
Arguments
max
(optional) The maximum number of column IDs to be returned in the array specified by array. (n)
array
(optional) The first element of an array that will accept the returned column IDs. (n)
env
(optional) One of the following: (n)
Include loaded columns for all environment levels.
Include loaded columns for the global environment level.
Include loaded columns for the current environment level. (default)
Include loaded columns for the specified environment level (1 through the number for the current environment level).
placed
(optional) One of the following: (n)
TRUE = Return placed columns.
FALSE = Return placed and unplaced columns. (default)
Discussion
The D_MENU_COLUMNS subfunction of %M_INFO returns the following information about loaded columns:
- The number of columns that match the default criteria or the criteria you specify. This is returned in the numcols return value.
- Column IDs for columns that match the criteria. This is returned in the array specified by the array argument. Note that you must pass both array and max to get this information. (Passing one without the other, however, does not generate an error.) The array argument specifies the first element in an array that will accept the column IDs. The max argument limits the number of column IDs that will be written to the array.
By default, D_MENU_COLUMNS reports the number of loaded columns (placed or not placed) at the local environment level. To change this, do one of the following:
- Pass the env argument to instruct the subroutine to return information on loaded columns for the global level, for the local level, for a specific level, or for all environment levels. To specify an environment level by number, pass the environment level number as env_level.
- Pass the placed argument to instruct the subroutine to return information on all loaded columns or just on placed columns. If you don’t pass placed, this defaults to false.
Submenu columns are included only if they have been separately loaded with M_LDCOL. In addition, if placed is passed as true, submenus won’t be included unless they are also placed as primary columns.
Examples
The following example returns the number of loaded columns (placed and not placed) at the local level. (It doesn’t return any column IDs because we didn’t pass the array argument.)
columns = %m_info(D_MENU_COLUMNS)
The following example returns the number of loaded columns (placed or not placed) at the local level. It returns this number in the columns variable. Because we passed array (col_ids) and max (max_cols), it also returns the column IDs. (Max_cols limits the number of returned IDs.)
columns = %m_info(D_MENU_COLUMNS, max_cols, col_ids)
The following example returns the number of loaded columns and the IDs for the loaded columns (placed or not placed) at the previous environment level.
prev_env = %e_info(D_ENV_LEVEL) ;Get level number for current environment prev_env = environment - 1 ;Decrement to get previous environment columns = %m_info(D_MENU_COLUMNS, max_cols, col_ids, prev_env)
The following example returns the number of loaded columns (in columns) and the IDs for loaded columns that are placed at the local environment level. It returns the IDs in the array specified by col_ids.
columns = %m_info(D_MENU_COLUMNS, max_cols, col_ids,, TRUE)
The following example returns the number of loaded columns (in columns) and the IDs for loaded columns that are placed at all environment levels. It returns the IDs in the array specified by col_ids.
columns = %m_info(D_MENU_COLUMNS, max_cols, col_ids, D_ALL, TRUE)
enabled = %M_INFO(D_MENU_ENABLED, colid, [entry][, env])
or
xcall M_INFO(D_MENU_ENABLED, colid, [entry][, env])
Return value
enabled
Returns TRUE if the column or entry is enabled or FALSE if the column or entry is disabled. (^VAL)
Arguments
colid
The ID of a currently loaded column. (n)
entry
(optional) The name of the menu entry to report on. (a)
env
(optional) One of the following: (n)
Return the initial state of the column or entry.
Return the state of the column or entry in the current environment. (default)
Return the state of the column or entry at a specified environment level (1 through the number of the current environment level).
Discussion
The D_MENU_ENABLED subfunction of %M_INFO enables you to get the state (enabled or disabled) of a menu column or menu entry at a given environment level.
- For a menu entry, pass entry with the name of the menu entry. (If there is no menu entry with the name passed as entry, a fatal Toolkit error is generated.)
- For a menu column, omit entry or pass it as blank.
In either case, you must pass a valid column ID as colid. (Otherwise a fatal Toolkit error is generated.) The column doesn’t have to be a primary column. It can be a submenu column. But if it’s a submenu column from a window library, it must first be loaded using M_LDCOL with the D_NOPLC parameter. (Submenus are not loaded as menu columns during normal processing.) Note that you can pass the ID of any column created using MB_COLUMN with the D_NOLOAD option—even if it is a subcolumn.
You can also select which environment level you want the state returned for. You can use the env argument to instruct D_MENU_ENABLED to return the state at the global level (D_GLOBAL), the local level (D_LOCAL, which is the default), or a specific level (by passing the number of the level as env_level). Note, however, that if the column isn’t placed in the specified environment (or default environment if you don’t pass env), this function returns the initial state, the state specified when the column or entry was created.
Examples
The following example returns the current state of the column whose ID is passed as col_id—if the column has been placed, that is. (If the column hasn’t been placed, it returns the initial state, the state specified when the column was created.) Because we don’t pass the env argument, this example returns the column’s state for the local environment.
state = %m_info(D_MENU_ENABLED, col_id)
The following example returns the current state of the N_FINDCUST menu entry if the col_id column has been placed. Note that it returns the state for the local environment because we didn’t pass env.
state = %m_info(D_MENU_ENABLED, col_id, "N_FINDCUST")
The next example returns the initial state of the col_id column. It returns the initial state because we passed D_GLOBAL as the env argument.
state = %m_info(D_MENU_ENABLED, col_id,, D_GLOBAL)
The following example returns the state of the N_FINDCUST menu entry in the previous environment. (Assume that prev_env is set to the number of the previous environment level.) If col_id hasn’t been placed in the previous environment level, however, this example returns the initial state of N_FINDCUST, the state specified when the column was created.
state = %m_info(D_MENU_ENABLED, col_id, "N_FINDCUST", prev_env)
num_entries = %M_INFO(D_MENU_ENTRIES, colid, [max][, array])
or
xcall M_INFO(D_MENU_ENTRIES, colid, [max][, array])
Return value
num_entries
The number of entries in the menu column specified by colid. (^VAL)
Arguments
colid
The ID of a currently loaded column. (n)
max
(optional) The maximum number of entries to return in array. (n)
array
(optional) The first element of an array that will receive the menu entry names (up to ten characters each). (n)
Discussion
The D_MENU_ENTRIES subfunction of %M_INFO returns the number of menu entries in the menu column or submenu column specified by colid. If you pass max and array, it also returns the names of the menu entries in the column. (To get this information, you must pass both of these arguments. However, if you pass one without the other, you won’t get an error.)
- The array argument specifies the first element in an array that will accept the menu entry names.
- The max argument specifies the maximum number of menu entry names that will be written to the array.
If colid is not a valid column ID, a fatal Toolkit error is generated. The column doesn’t have to be a primary column. It can be a submenu column. But if it’s a submenu column from a window library, it must first be loaded using M_LDCOL with the D_NOPLC parameter. (Submenus are not loaded as menu columns during normal processing.) Note that you can pass the ID of any column created using MB_COLUMN with the D_NOLOAD option—even if it is a subcolumn.
Examples
The following example returns the number of menu entries in the column whose ID was passed as col_id. This number is returned in menu_entries.
menu_entries = %m_info(D_MENU_ENTRIES, col_id)
The following example returns the number of menu entries in the column specified by col_id. It also returns the names of the menu entries in the column. These names are returned in the array whose first element is entry_array. The max_entries variable sets a limit to the number of names that can be returned.
menu_entries = %m_info(D_MENU_ENTRIES, col_id, max_entries, entry_array)
found = %M_INFO(D_MENU_ENTRY, colid, [entry], [index], [text], [quick_select], [shortcut], & [user][, noreset])
or
xcall M_INFO(D_MENU_ENTRY, colid, [entry], [index], [text], [quick_select], [shortcut], & [user][, noreset])
Return value
found
Returns TRUE if the menu entry is found or FALSE if the menu entry does not exist in the column. (^VAL)
Arguments
colid
The ID of a currently loaded menu column. (n)
entry
(optional) The name of the menu entry. (a)
index
(optional) The numeric position (base 1) of the menu entry. (n)
text
(optional) Returned with the text of the menu entry. (a)
quick_select
(optional) Returned with the uppercased quick-select character for the entry. (a)
shortcut
(optional) Returned with the function code (as defined in inpctl.def) associated with the keyboard shortcut for the menu entry, or 0 if the entry has no shortcut. (n)
user
(optional) Returned with the user text associated with the menu entry, or blank if no user text is associated with the entry. (a)
noreset
(optional) One of the following: (n)
TRUE = The menu entry is set to NORESET.
FALSE = The menu entry is not set to NORESET.
Discussion
The D_MENU_ENTRY subfunction of %M_INFO returns information about a menu entry. You must specify the menu column by passing the column ID as colid. And you must specify the menu entry by passing the entry or index argument.
- To use the menu entry name to specify the menu entry, pass the name as the entry argument (case-insensitive). If you also pass index, it is returned with a numeric position indicator (base 1) of the specified menu entry.
- To use a column position to specify the menu entry, pass the position number (base-1) in the index argument. (For example, pass 1 for the top entry in the column, pass 2 for the next entry, etc.) If you want the name of the menu entry returned in entry, pass entry as a variable that’s set to blank.
In addition to retrieving the menu entry name by passing the entry’s position and vice versa, you can also get the following:
- The text for the entry by passing the text argument.
- The quick-select character for the entry by passing the quick_select argument. (The quick-select character is returned as an uppercased character.)
- The numeric identifier for the entry’s keyboard shortcut (as defined in inpctl.def) by passing the shortcut argument. This argument is returned as 0 if there is no shortcut for the entry or D_SUBMENU if a submenu is attached to the entry.
- The user text associated with the menu entry by passing the user argument. This argument is returned as 0 if there is no user text for the menu entry. (The M_USER subroutine also returns the user text for a menu entry, but M_USER works only with primary columns.)
- A value that indicates whether or not the menu column will be reset if the entry is selected. You can get this information by passing the noreset argument. (See .ENTRY for information on the NORESET qualifier that specifies this.)
If colid is not a valid column ID, a fatal Toolkit error is generated. The column may be a primary column or a submenu column. But if it’s a submenu column from a window library, it must first be loaded using M_LDCOL with the D_NOPLC parameter. (Submenus are not loaded as menu columns during normal processing.) You can pass the ID of any column created using MB_COLUMN with the D_NOLOAD option—even if it is a subcolumn.
Examples
The following example returns a value in col_found that indicates whether the O_CANCEL menu entry exists on the menu column specified by col_id.
col_found = %m_info(D_MENU_ENTRY, col_id, "O_CANCEL")
As with the previous example, the following example returns a value in col_found that indicates whether the O_CANCEL menu entry exists on the menu column specified by col_id. However, it also returns the position of the entry in the column. Because entry is passed (“O_CANCEL”) and isn’t blank, the position is returned in entry_num.
col_found = %m_info(D_MENU_ENTRY, col_id, "O_CANCEL", entry_num)
Assuming entry_name is blank, the following example returns a value in col_found that indicates whether a menu entry exists at the position specified by entry_num. If an entry does exist at the specified position, it also returns the name of the menu entry (in entry_name) in the position specified by entry_num.
entry_name = "" col_found = %m_info(D_MENU_ENTRY, col_id, entry_name, entry_num)
The next example also returns a value in col_found that indicates whether a menu entry exists at the position specified by entry_num. In addition it returns the text of the entry, the uppercased quick-select character for the entry, the function number for the keyboard shortcut, any user text associated with the entry, and a value that indicates whether the column will be reset when the entry is selected. Note, however, that it doesn’t return the name of the entry because we didn’t pass the entry argument.
col_found = %m_info(D_MENU_ENTRY, col_id,, entry_num, entry_text, & q_select, short_num, user_text, col_reset)
header_length = %M_INFO(D_MENU_HEADER, colid, [header], [quick_select], [justification] & [, column_width])
or
xcall M_INFO(D_MENU_HEADER, colid, [header], [quick_select], [justification] & [, column_width])
Return value
header_length
The number of characters in the header text for the menu column specified by colid. (^VAL)
Arguments
colid
The ID of a currently loaded column. (n)
header
(optional) Returned with the text of the column’s header. (a)
quick_select
(optional) Returned with the uppercased quick-select character for the column header. (a)
justification
(optional) On Unix and OpenVMS, returned with the justification for the column relative to the header: D_JST_LEFT, D_JST_RIGHT, D_JST_CENTER. (On Windows, the column is positioned automatically.) (n)
column_width
(optional) Returned with the overall width (in characters) of the column. (n)
Discussion
The D_MENU_HEADER subroutine of %M_INFO returns the following information about a column’s header:
- The number of characters in the header text (including the leading and trailing space in the header) for the column. This is returned in the header_length return value.
- The text of the column’s header (including the leading and trailing space). This is returned in the optional header argument.
- The quick-select character for the column header. This is returned as an uppercased character in the optional quick_select argument.
- The justification of the column on Unix and OpenVMS. This is returned in the optional justification argument. (On Windows, this has no effect; the column is automatically left-justified under the header.)
- The overall width, in characters, of the column. This is returned in the optional column_width argument. If an entry has a shortcut, five characters of this width are reserved for the shortcut text.
If colid is not a valid column ID, a fatal Toolkit error is generated. The column may be a primary column or a submenu column. But if it’s a submenu column from a window library, it must first be loaded using M_LDCOL with the D_NOPLC parameter. (Submenus are not loaded as menu columns during normal processing.) You can pass the ID of any column created using MB_COLUMN with the D_NOLOAD option—even if it is a subcolumn.
Examples
The following example returns the number of characters in the header text for the col_id column.
h_length = %m_info(D_MENU_HEADER, col_id)
The next example returns the following information about the header for the col_id column: the number of characters in the header text (h_length), the text for the column’s header (h_text), the uppercased quick-select character for the column (q_select), the justification of the column (just), and the overall width, in characters, of the column (col_width).
h_length = %m_info(D_MENU_HEADER, col_id, h_text, q_select, just, col_width)
num_entries = %M_INFO(D_MENU_LISTS, colid, [max][, array])
or
xcall M_INFO(D_MENU_LISTS, colid, [max][, array])
Return value
num_entries
The number of menu lists defined in the menu column specified by colid. (^VAL)
Arguments
colid
The ID of a currently loaded column. (n)
max
(optional) The maximum number of list names returned in array. (n)
array
(optional) The first element of an array that will receive the list names (up to ten characters each). (n)
Discussion
The D_MENU_LISTS subfunction of %M_INFO returns the number of menu lists defined in a menu column or submenu column specified by colid. If you pass the max and array arguments, it also returns the names of the lists in the column. (To get this information, you must pass both of these arguments. However, if you pass one without the other, you won’t get an error.)
- The array argument specifies the first element in an array that will accept the list names.
- The max argument specifies the maximum number of list names that will be written to the array.
If colid is not a valid column ID, a fatal Toolkit error is generated. The column may be a primary column or a submenu column. But if it’s a submenu column from a window library, it must first be loaded using M_LDCOL with the D_NOPLC parameter. (Submenus are not loaded as menu columns during normal processing.) You can pass the ID of any column created using MB_COLUMN with the D_NOLOAD option—even if it is a subcolumn.
See also
.LIST script command for information on menu lists
Examples
The following example returns the number of menu lists defined in the column specified by col_id. Because we didn’t pass the max and array arguments, this example won’t return the names of the lists.
num_lists = %m_info(D_MENU_LISTS, col_id)
The following example returns the number of lists and the names of the lists in the column specified by col_id. List_name_array points to the first element of the array that will receive the list names, and max_lists specifies the maximum number of lists names that will be returned.
num_lists = %m_info(D_MENU_LISTS, col_id, max_lists, list_name_array)
num_entries = %M_INFO(D_MENU_LIST, colid, list, [max][, array])
or
xcall M_INFO(D_MENU_LIST, colid, list, [max][, array])
Return value
num_entries
The number of menu entries in the specified menu list, or 0 if the list doesn’t exist in the menu column specified by colid. (^VAL)
Arguments
colid
The ID of a currently loaded column. (n)
list
The name of a menu list (case-insensitive). (a)
max
(optional) The maximum number of menu entry names returned in array. (n)
array
(optional) The first element of an array that will receive the names of menu entries in the list (up to ten characters each). (n)
Discussion
The D_MENU_LIST subfunction of %M_INFO returns the number of menu entries in a list or 0 if the menu list specified by the list argument is not in the column specified by colid. If you pass max and array, this function also returns the names of the menu entries in the list. (To get this information, you must pass both max and array. However, if you pass one without the other, you won’t get an error.)
- The array argument specifies the first element in an array that will accept the entry names.
- The max argument specifies the maximum number of entry names that will be written to the array.
If colid is not a valid column ID, a fatal Toolkit error is generated. The column may be a primary column or a submenu column. But if it’s a submenu column from a window library, it must first be loaded using M_LDCOL with the D_NOPLC parameter. (Submenus are not loaded as menu columns during normal processing.) Note that you can pass the ID of any column created using MB_COLUMN with the D_NOLOAD option—even if it is a subcolumn.
Examples
The following example returns the number of menu entries that belong to the list list_name. If list_name isn’t part of the column col_id, the example will return 0. (Because we didn’t pass max and array, this example won’t return the names of the entries.)
num_lists = %m_info(D_MENU_LIST, col_id, list_name)
The following example returns the number of entries and the names of the entries that belong to the list specified by list_name. List_name_array is the first element of the array that will receive the menu entry names, and max_lists specifies the maximum number of entry names that will be returned.
num_lists = %m_info(D_MENU_LIST, col_id, list_name, max_lists, list_name_array)
colid = %M_INFO(D_MENU_SHORTCUT, keycode, [entry][, env])
or
xcall M_INFO(D_MENU_SHORTCUT, keycode, [entry][, env])
Return value
colid
The ID of the menu column that contains the menu entry for the specified shortcut code, or 0 if the shortcut code isn’t assigned to an entry. (^VAL)
Arguments
keycode
The shortcut code to look for. This must be one of the _KEY values defined in inpctl.def. (n)
entry
(optional) Returned with the name of the menu entry that the shortcut code is assigned to. (a)
env
(optional) The number of an environment level (1 through the number of the current environment level), or D_LOCAL for the current environment level (default). (n)
Discussion
The D_MENU_SHORTCUT subfunction of %M_INFO returns the ID of the menu column that contains an entry for the specified shortcut code as defined in inpctl.def, or it returns 0 if the shortcut code isn’t assigned to an entry. If you pass the entry argument, it also returns the name of the entry or blank if there’s no entry for the shortcut.
|
|
On Windows, for F11 and F12, you can’t use the shortcut codes (F11_KEY and F12_KEY) defined in inpctl.def. To get information for F11, pass keycode as F33_KEY(68). To get information for F12, pass keycode as F34_KEY(69). See the distributed keymap.msw file and MSWINDOWS keymap. |
By default, D_MENU_SHORTCUT searches the local environment for the entry, but you can specify another environment level by passing the number for that environment level as the env argument. If entries on more than one placed column have the same shortcut, the entry from the column that was placed last will be returned. This corresponds to the entry that would be signaled if the user pressed the key.
The following example returns the ID of the menu column that contains an entry whose shortcut code is mapped to the F18_KEY entry in inpctl.def. If there is no menu entry assigned to this shortcut code, the example will return 0.
col_id = %m_info(D_MENU_SHORTCUT, F18_KEY)
In the following example, the D_MENU_SHORTCUT subfunction returns not only a column ID but also the name of the menu entry whose shortcut code is mapped to the F18_KEY entry in inpctl.def. This information is returned for the previous environment level.
env_num = %e_info(D_ENV_LEVEL) ;Get level number for current environment env_num = environment - 1 ;Decrement to get previous environment col_id = %m_info(D_MENU_SHORTCUT, F18_KEY, menu_entry, env_num)
