%M_INFO

Get menu system information

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
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)

D_MENU_COLUMNS

Retrieve loaded columns.

D_MENU_ENABLED

Determine whether a column or entry is enabled.

D_MENU_ENTRIES

Retrieve the entries in a column.

D_MENU_ENTRY

Retrieve information about a menu entry.

D_MENU_HEADER

Retrieve information about a column’s header.

D_MENU_LISTS

Retrieve the entry lists in a column.

D_MENU_LIST

Retrieve the entries in a list.

D_MENU_SHORTCUT

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

D_MENU_COLUMNS

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)

D_ALL

Include loaded columns for all environment levels.

D_GLOBAL

Include loaded columns for the global environment level.

D_LOCAL

Include loaded columns for the current environment level. (default)

env_level

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:

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:

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)

D_MENU_ENABLED

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)

D_GLOBAL

Return the initial state of the column or entry.

D_LOCAL

Return the state of the column or entry in the current environment. (default)

env_level

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.

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)

D_MENU_ENTRIES

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.)

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)

D_MENU_ENTRY

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.

In addition to retrieving the menu entry name by passing the entry’s position and vice versa, you can also get the following:

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)

D_MENU_HEADER

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:

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)

D_MENU_LISTS

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.)

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 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)

D_MENU_LIST

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.)

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)

D_MENU_SHORTCUT

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.

Note

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.

Examples

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)