This document covers the following topics:
Dialog.
This event occurs whenever one or more commands (signals, menu items or tool bar items without a SAME-AS attribute, or status bar panes) need to be updated (i.e., disabled, checked, etc.) by a dialog during idle processing or in response to an explicit UPDATE-COMMAND-STATUS action. The commands do not necessarily belong to the dialog receiving the command-status event if their SHARED attribute is set to TRUE, which causes MDI frame commands to be automatically redirected to the active MDI child dialog (if any). This is precisely the case where the command-status event is most useful, because it allows multiple instances of an MDI child dialog (or even completely different MDI child dialogs) to share the same tool bar and status bar controls without interfering with each other, as would be the case if each MDI child would attempt to update the commands directly.
The intended usage of the command-status event is to only update state variables (and not the commands themselves) when the program state changes, and then to do a bulk update of the commands according to the current values of the state variables within the command-status event handler.
Note:
The command-status event handler is called frequently, and therefore
should return as quickly as possible. For this reason, database access (for
example) should be avoided in this event.
If there are no commands which need to be serviced by a particular dialog, no command-status event is raised, even if there is code available for it and the event is not suppressed. This is the case for an active MDI child if no commands have been marked as shared, for example.
For performance reasons, it is not possible for the application to find out which commands caused a particular command-status event to be triggered. Instead, a dialog should update all commands for which it is the current target, and which require a non-default state to be set. The default state is disabled and unchecked for signals, menu items and tool bar items and invisible for status bar panes. Any commands not explicitly enabled or disabled (or any status bar panes not explicitly shown or hidden) by the program in the command-status event will be automatically reset to the default state by the system. This allows a particular MDI child dialog, for example, to only set the status of commands it "knows" about, and to let the system implicitly reset the commands intended only for different child dialogs. Thus, if a command is introduced for a specific MDI child dialog only, the command-status events of the all other MDI child dialogs do not need to be modified. This automatic command resetting is not performed if the corresponding dialog's command-status event is suppressed.
The command-status event for a particular dialog is raised before the idle event (if any) for that dialog, in order that the effects of the idle event code can be taken into account by the command status updating process.