M_PROCESS

Process a menu

WSupported on Windows

USupported on Unix

VSupported on OpenVMS

NSupported in Synergy .NET

xcall M_PROCESS([input_string], [help_id][, wait_time]) 

Arguments

input_string

(optional) The “path” to follow to get to a specific menu column entry. (a)

help_id

(optional) The help identifier. (a)

wait_time

(optional) The time-out limit for I/O processing to be completed before returning to the calling routine. (n)

D_FOREVER or -1

Never time out.

D_GLOBAL or -2

Use the global value (see g_wait_time). (default)

D_IMMEDIATE or 0

Time out immediately.

n

Wait up to n seconds (where n is a positive value) for I/O processing to be complete.

Discussion

M_PROCESS explicitly processes a menu. You rarely need to call M_PROCESS, because menu processing is normally done implicitly during input. However, you may need to use this subroutine at initial program entry to explicitly process the menu when you’re not doing any input.

If you call M_PROCESS while no columns are loaded, UI Toolkit issues a “No columns placed” error (using U_MESSAGE, error-style) and return to the calling routine with g_select false.

Calling M_PROCESS with no arguments is the same as pressing the process-menu key when doing input. You will return from M_PROCESS when an entry is selected or when the user presses the process-menu key to deactivate the menu bar.

The input_string simulates what you would type in order to move to a specific position on the menu (for example, what would happen after you pressed the process-menu key). The following characters are valid (not case sensitive):

Character	Meaning
[entry_name]	Name of the entry—the brackets are required
<L>	Left Arrow key
<R>	Right Arrow key
<U>	Up Arrow key
<D>	Down Arrow key
<E>	Enter key—this is needed to activate a submenu
quick-select_character	Any valid quick-select character

Assuming that input_string does not begin with an entry name, the sequence of characters begins as if no menu column is dropped down (in other words, as if M_DEFCOL had been called with a 0 argument). Thus, an initial <R> drops down the first column.

On Windows, the number of arrow movements required does not match the actual keystrokes pressed after the Alt key. (Specifically, one more <R> and one less <D> are required.) For compatibility with other platforms, input_string must match the keystrokes for a Unix or OpenVMS environment.

On Windows, input_string can only specify a submenu entry if it follows a valid menu entry. For example, the following is allowed:

xcall m_process("[menu_entry]<E>[submenu_entry]")

but the following is not allowed:

xcall m_process("<R><D><D><E>[submenu_entry]")

Input_string overrides the effect of any previous call to M_DEFCOL, though the default column or entry remains in effect for future calls to M_PROCESS without input_string.

The following example is equivalent to pressing the Right Arrow key twice and typing the “m” key. In other words, it selects the entry in the second column whose quick-select character is m. (The user must press Enter to complete the selection if the quick-select character is non-unique within the column.)

"<r><r>m" 

On Windows, M_PROCESS recognizes the following menu entries (though they generally don’t have a purpose): E_CLEAR, E_COPY, E_CUT, E_MARK, E_PASTE. If a menu entry other than one of these is selected from the menu, g_select is returned with a value of true. G_entnam will contain the uppercased name of the entry the user was on when the user pressed Enter. If the selected menu entry begins with “U_” the EUTILS_METHOD subroutine is called and the menu is reprocessed. If the selected menu entry is “O_HELP” the EHELP_METHOD subroutine is called, with help_id as its argument.

You will need to clear g_select after you satisfy the event.

Additionally, when a menu entry is selected, g_mnustrng will contain the input_string which, in turn, could be passed to the next call to M_PROCESS to get back to the same menu entry.

If the operation times out, g_select is set to true and g_entnam set to the entry name specified in g_time_entry, which is defined in tkctl.def. See g_time_entry. Note that the time-out is reset after each keystroke. Additionally, in Windows environments, if a menu column is dropped down no time-out will occur.

Typically, Windows applications do not pull menu columns down automatically. Instead, menus are explicitly invoked by the user using the mouse or the ALT key. Rather than change the default M_PROCESS behavior (which could require a redesign of your program flow), you may suppress the automatic menu pull-down feature of M_PROCESS by setting the environment variable DTK_MENU_UP or by calling M_DEFCOL(0).

See also

• M_LDCOL routine to load a menu from a library
• MB_COLUMN routine to create (and load) a column at runtime

Examples

The following example enables menu processing (exactly as if you had pressed the process-menu key at an input).

xcall m_process

The next example processes a menu and selects an entry that is in the third column, one entry down from the top. It passes the argument “menuhelp” to the EHELP_METHOD subroutine if the selected menu entry is “O_HELP.”

xcall m_process("<r><r><r><d>", "menuhelp")

The following example initializes to the entry below the entry whose name is ap, no matter which column contains ap.

xcall m_process("[ap]<d>") 

The following example selects the entry “o_lock” on the submenu accessed by the entry “o_admin.”

xcall m_process("[o_admin]<e>[o_lock]") 

The following code fragment illustrates one way to use M_PROCESS.

  do 
    begin 
     xcall m_process 
     if(g_select) 
       case g_entnam of 
         begincase 
  "ENTRY1"  : xcall entry1 
  "ENTRY2"  : xcall entry2 
  "ENTRY3"  : xcall entry3 
  "EXIT"    : done=TRUE 
          endcase 
    end 
until(done)