C_PROCESS

Process a composite window

xcall C_PROCESS(container_id [, a_methoddata1, ..., a_methoddata20])

Arguments

container_id

The ID for the container window. This must be the ID of a composite container window (created with the DC_CREATE subfunction of %C_CONTAINER). Any other value will cause a fatal Toolkit error. (n)

a_methoddata1 through a_methoddata20

(optional) Up to 20 additional data arguments. See the Discussion. (any)

Discussion

C_PROCESS processes composite windows by looping through and processing child windows and child lists as well as enabled buttons on the composite container window.

To process a child window or list, C_PROCESS calls the method for the child (see the Processing Methods table).
To process a button on the container, C_PROCESS merely waits for a user response.

If there are no placed and enabled child windows, child lists, or buttons on the container, C_PROCESS immediately returns control to the routine that called it.

C_PROCESS starts on whatever child currently has context. By default, it starts with the first child window or list in the tabbing order, which is the child with the tabbing index of 1. (If the window has no child, C_PROCESS starts with the first button on the container window.) However, if the container has previously been processed, it starts with the child that was active when C_PROCESS last exited. Additionally, if the DC_CONTEXT subfunction for %C_CONTAINER has been used to specify a child, C_PROCESS starts with that child.

When the processing for a button or child has finished, C_PROCESS checks g_entnam to see if a C_ menu entry that it recognizes is active and, if one is, moves focus as instructed by the C_ menu entry. (Recognized menu entries are listed below.) It then continues the loop by processing the newly active child or button. However, if a processing method or button on the container returns after signaling a menu entry that C_PROCESS does not recognize, C_PROCESS returns control to the routine that called it, and the menu entry is passed on to that routine.

When C_PROCESS is first called, it does not check g_entnam, so using %M_SIGNAL to signal one of the C_ menu entries before calling C_PROCESS will not work. Use the DC_CONTEXT subfunction for %C_CONTAINER to instruct C_PROCESS to start on a child or button other than the default.

Note the following:

If a processing method returns without signaling a menu entry (and doesn’t otherwise change focus to another child or button before returning), C_PROCESS calls the method again, resulting in a possibly endless loop.
C_PROCESS clears g_select after processing a menu entry that it recognizes. Otherwise it leaves this value as is. Additionally, C_PROCESS does not in itself change the values of g_setsts, g_fldnam, or g_entnam. However, a button or the processing method for a child may change these. For example, a child method will set these variables as documented in the I_INPUT Discussion if the method calls I_INPUT and then returns without signaling another menu entry. (Such a method would need to change focus in some way to another child, or C_PROCESS will again signal the input method for the same child. See note above.)
If context moves to a disabled child, the method for the child is not called. Rather, context is automatically moved to the next or previous child or button. If the context reason is “C_PREV” or “C_LAST”, the previous enabled child or button is activated. Otherwise, the next enabled child or button is activated.
If a button is enabled on a child window or list that is not active and the user clicks that button, the signaled menu entry will be seen first by the method for the child that is active. If that method does not clear g_select, the menu entry is passed out to C_PROCESS. If C_PROCESS doesn’t recognize it, it is passed out to the routine that called C_PROCESS. Consequently, the method for the window or list that contains the button will not see the menu entry, so we recommend that you do one or more of the following:
Handle button-generated menu entries in the outermost loop that calls C_PROCESS.
Handle button-generated menu entries in a common routine that all methods can call.
Disable buttons explicitly when your application is not prepared to process them. See the .BUTTON Discussion for information on disabling and enabling buttons.

To process a child window or list, C_PROCESS calls either the processing method when the child was added (with the DC_ADD subroutine for %C_CONTAINER) or the default Toolkit-supplied method as listed in the table below.

Processing Methods
Child type	Default processing method
ActiveX window	C_METHAX
Composite window	C_METHCTR
Input window	C_METHINP
List	C_METHLST
.NET form window	C_METHNET
Selection window	C_METHSEL
Tab set window	C_METHTS
Text window	C_METHTXT
Other	C_METHNOP

C_PROCESS recognizes the following menu entries:

“C_FIRST” makes the first child (window or list) active, or it makes the first button on the composite container window active if there is no child. Note, however, that if the composite window is the child of another composite window, this menu entry is passed to the outer composite window.
“C_LAST” makes the last child on the composite window active if there are no buttons on the composite container window. If there are buttons, “C_LAST” makes the last button active. Note, however, that if the composite window is the child of another composite window, this menu entry is passed to the outer composite window.
“C_NEXT” makes the next child active or, if the last child is currently active, it makes the first button on the composite container window active. If the last child or button is active, and the composite window is not the child of another composite window, “C_NEXT” makes the first child active (or button if there is no child). If the composite window is the child of another composite window, however, and the last button is active (or child if there are no buttons), the menu entry is passed to the outer composite window.
“C_PREV” makes the previous child window, child list, or button on the container active. If the first child is active (or button if there is no child), “C_PREV” makes the last button active, or if there are no buttons, it makes the last child active. Note, however, that if the composite window is the child of another composite window, and focus is on the first child (or button if there is no child), this menu entry is passed to the outer composite window.
“C_RESET” takes into account any programmatic context change (for example, with DC_CONTEXT or DC_BTNFOCUS) and resets the context in a composite window to the currently active child window, child list, or button. Note, however, that if the composite window is itself a child of another composite window, this menu entry is passed to the outer composite window.
“C_SETnnnn” makes the child window or list with the tabbing index nnnn active. (If nnnn is less than 1 or greater than the number of children, the menu entry is ignored.)

For the child processing methods (default or otherwise), C_PROCESS passes the following: the container ID, the type of child (window or list), the child ID, the reason the child was activated, and as many method data arguments as are passed in the C_PROCESS call. Additionally, note that

the data record argument may also be passed and is required only if one of the following is invoked: C_METHINP, C_METHLST, C_METHSEL, or a method you created that requires it.
the data record argument will not be passed to the method if recordindex was not passed in the DC_ADD call for the child, if it was passed as a value that was less than 1, or if the a_methoddata argument that corresponds to recordindex is not passed in the C_PROCESS call.

The a_methoddata arguments are optional and are ignored unless C_PROCESS invokes one of the following: the default method for input windows (C_METHINP), the default method for lists (C_METHLST), the default method for selection windows (C_METHSEL), or a method you have created that requires these arguments. Note that for C_METHINP, C_METHLST, and C_METHSEL,

the only a_methoddata argument required is the one specified by the recordindex value passed in the DC_ADD call for the window or list. For example, if the value passed as recordindex in the DC_ADD call is 3, you must include the third a_methoddata argument in the C_PROCESS call.
the a_methoddata argument you pass must be the data record or field for input for the child window or list. C_PROCESS will not only pass this a_methoddata argument on to the method, it will also pass this argument as the record argument for the method. This in turn is passed as the data_area argument to I_INPUT (called by C_METHINP), the data argument passed to L_SELECT (called by C_METHLST), or the field_data argument passed to S_SELECT (called by C_METHSEL).