%M_TEXT

Modify and retrieve menu entry text

status = %M_TEXT(col_id, entry, [new_text], [old_text][, quick_select])

xcall M_TEXT(col_id, entry, [new_text], [old_text][, quick_select])

Return value

status

True (1) if successful, and false (0) if unsuccessful. (^VAL)

Arguments

col_id

The ID of the column in which the entry is located. (n)

entry

The name or row number of the entry to modify. (a or n)

new_text

(optional) The new menu entry text. (a)

old_text

(optional) Returned with the previous menu entry text. (a)

quick_select

(optional) The new quick-select character. (a)

Discussion

%M_TEXT enables you to retrieve and modify entry text for a menu or submenu. The entry can be a selectable entry, unselectable text, or blank. If the entry is selectable, you can also modify the quick-select character. Lines in a menu column, however, cannot be modified.

To modify a submenu, load col_id by calling M_LDCOL prior to calling %M_TEXT. Note the following. Col_id must be the ID of a loaded column or a fatal Toolkit error will occur. If the column becomes unloaded after calling %M_TEXT, the menu entry text will revert to its initial state when it is reloaded.

If entry is alphanumeric, it is presumed to be the entry name (g_entnam) associated with the entry to query and/or modify. If entry is numeric, it is presumed to be the row number of the entry, which enables you to access text, blank, and selectable entries by ordinal position. When determining ordinal position, all text, blank, line, and selectable entries must be counted.

If the specified entry doesn’t exist or is a line, %M_TEXT returns false.

If new_text is passed, the menu entry text will be modified to contain new_text. Any shortcut text will remain unchanged. If new_text is shorter than the original text, the remainder will be filled with blanks. If new_text is wider than the widest entry in the column, new_text will be truncated.

If old_text is passed, it is returned with the text of the entry prior to being modified.

If quick_select is passed, the quick-select character will be modified to be the first occurrence (case insensitive) of the specified character. If quick_select is not passed and new_text is passed, the first non-blank character in new_text will be used to denote the quick-select character. If neither quick_select nor new_text is passed, the quick-select character is not modified.

Examples

The following example changes the menu text for the menu entry “entry1” of column col_id to be “New entry text.”

xcall m_text(col_id, "entry1", "New entry text")

The following example changes the menu text of the third menu entry of column col_id to be “Quick-select changed,” returns the previous menu text in old_text, and underlines the ‘s’ for the new quick-select character.

if (.not. %m_text(col_id, 3, "Quick-select changed", old_text, 's'))
    xcall u_message ("Unable to modify menu text")