Synopsis
unsigned int OMpush_ctx (
OMobj_id context_id,
int state_mode,
int notify_mode,
int child_notify_mode );
int OMpop_ctx (
OMobj_id context_id );
unsigned int OMXobj::push_ctx(
int state_mode = 0,
int notify_mode = 0,
int child_notify_mode = 0);
int OMXobj::pop_ctx(void);
Description
These routines suspend and resume AVS/Express' execution in the context of a specified object.
OMpush_ctx suspends execution, meaning that, in general:
• Notifications that have the same function id or argument id as context_id are suppressed. They are never executed.
• All other notifications are queued.
OMpush_ctx also sets the state_mode with the state_mode argument. The state mode determines how object's values are saved during the save operation. If you only want to set the state mode without affecting how events are queued, use the routine OMset_state_mode.
OMpop_ctx can be made to execute the notifications queued by the most recent OMpush_ctx command. It also restores the state mode to its previous value.
You can modify the treatment of notifications with the event_mode and child_notify_mode arguments.
Calls to OMpush_ctx and OMpop_ctx can be nested. A nested push/pop context is known as the child context of the enclosing push/pop context. The enclosing context is known as the parent context .
Calls to OMpush_ctx and OMpop_ctx bracket the invocation of any method's callback routine. Since calls to OMpush_ctx can be nested, you can still call these routines to control events generated from within the module's compute function.
Even if the OMpop_ctx executes the update functions of all outstanding methods, in some cases a widget's display will not have been updated after the OMpop_ctx call. This is because the widget sends itself a window system expose event which is not delivered with OMpop_ctx. To guarantee that all widgets are also updated, you should call the routine EVflush_events after calling OMpop_ctx.
Arguments
context_id
The id of an object.
In OMpop_ctx, context_id must be the same id as the one specified in the most recent call to OMpush_ctx.
The context_id is used as a filter to prevent a method from sending notification events to itself. Any events that are delivered to the object specified by context_id are not delivered unless the notify_mode argument is specified as OM_CTX_ALL_NOTIFIES.
state_mode
An integer indicating whether changes to the application's network should be saved when the user performs a save operation. Specify one of the symbolic constants (defined in <avs/om.h>):
|
State mode
|
Meaning
|
|
0 |
Inherit the state mode from the parent context. |
|
OM_STATE_PROG |
Save the changes unconditionally when the user performs a save operation. |
|
OM_STATE_USR |
Give the user the choice to either save or discard the changes. |
|
OM_STATE_TRANSIENT |
Never save the changes. |
notify_mode
An integer indicating how AVS/Express should treat notifications that occur during the push/pop context.
AVS/Express always suppresses notifications that have the same function id or argument id as context_id.
All other notifications are either queued until the pop, or queued until the parent's pop, or suppressed. Specify one of the following symbolic constants (defined in <avs/om.h>):
|
Notify mode
|
Meaning
|
|
0 |
Queue notifications until the next call to OMpop_ctx. |
|
OM_CTX_PARENT_NOTIFIES |
Queue notifications until the parent context's call to OMpop_ctx. If there is no parent context defined, events are queued and executed in this context's call to OMpop_ctx. Use this flag if you do not require that all queued events are executed when your OMpop_ctx call returns. |
|
OM_CTX_BEGIN_OP |
Specify the start of an operation that is not part of the operation defined by the parent context. This has the effect of requiring that "delayed operations" (such as the mapping of a user interface window) are executed in this context and the child_notify_mode is not propagated to this context. |
|
OM_CTX_TOSS_NOTIFIES |
Suppress all notifications. This mode should be used with extreme caution since it can prevent objects from being notified about events that they need to be notified of (like instance and destroy events). |
|
OM_CTX_ALL_NOTIFIES |
Allow notifications to be delivered to functions whose object is context_id. In other words, allow this method to notify itself. |
child_notify_mode
An integer specifying the notify mode of all child contexts. Specify one of the following symbolic constants listed under the notify_mode argument.
When push/pop contexts are nested, a child's notification mode is the OR'd combination of:
• The notify_mode argument specified by the child.
• The child_notify_mode arguments specified by any outer-level push/pop context. Put another way, the child notify mode specified by a push/pop context is in effect for all inner contexts, including children, their children, and so forth.
Example 1
Here is a simple push/pop context that executes all events setting the state mode so that all changes made in the context will be saved:
OMpush_ctx(obj_id, OM_STATE_PROG, 0,0);
// any notifications that are triggered here....
OMpop_ctx(obj_id); // are executed during this call
Example 2
Here is a simple push/pop context that sets the state mode so that no changes made in the context will be saved and delays executing notifications until the parent context is popped:
OMpush_ctx(obj_id, OM_STATE_TRANSIENT,
OM_CTX_PARENT_NOTIFIES, 0);
// any notifications that are triggered here...
OMpop_ctx(obj_id); // are not executed here (unless there is
// no parent context)
See also