pGetAction

Get the next action.

Syntax

pGetAction ( out vlStatus,
             in vlInputWinName,
             out vlAction,
             inout vlTargetWinName )

Parameters

vlStatus	The returned status from pGetAction.
vlInputWinName	The name of the current window.
vlAction	The “action” returned from pGetAction.
vlTargetWinName	The window for which the action is intended.

Comments

The pGetAction command is used, usually within an event loop, to get the next action and is usually followed by a call to pDispatchAction. If vlInputWinName is not $NULL and not blank, then pGetAction gets only actions destined for that window. Usually, when pGetAction is used in a modal window, the window name is passed in vlInputWinName. If vlInputWinName is blank or $NULL, then the next action for any window is returned. This option is typically used for non-modal windows where the next action could be for any open window.

The pGetAction command first tries to fetch an action from the Message Queue. If one is found, vlAction is updated with the action name and vlTargetWindow is set to the name of the window to receive the action.

If no queued action is found, pGetAction sets the current window to be vlInputWinName (if it is not $NULL or blank) and does a FORM INPUT. It then looks up the event in EventAction. In particular, after FORM INPUT:

pGetAction searches EventAction for an entry where WindowTag, ObjectTag, EventName, and EventType exactly match Event.WindowTag, Event.EventTag, Event.EventName, and Event.EventType.
If no entry is found, it searches EventAction for an entry with WindowTag equal to “Unknown” and ObjectTag, EventName, and EventType matching Event.EventTag, Event.EventName, and Event.EventType.
If no entry is found, it searches EventAction for an entry with WindowTag, EventName, and EventType equal to “Unknown” and ObjectTag matching Event.EventTag.
If no entry is found, it searches EventAction for an entry with WindowTag and ObjectTag equal to “Unknown” and EventName and EventType matching Event.EventName and Event.EventType.
If no entry is found, it searches EventAction for an entry with WindowTag, ObjectTag, and EventName equal to “Unknown” and EventType matching Event.EventType.
If no entry is found, then the action is assumed to be Event.EventTag.
Otherwise, the action name is taken from the Action field.
If the Action field value matches a special value shown below, then the action is taken, as indicated, from the Event structure.

Contents of Action field	Action value to be taken from:
	Event.EventTag
	Event.EventName
	Event.WindowTag
	Event.MenuTag
	Event.MenuItemTag
	Event.FormTag
	Event.FieldTag
	Event.EventType
	Event.MouseClick
	Event.KeyPressed
	Event.ScrollingKey
	Event.ShiftKey
	Event.CtrlKey
	Event.AltKey

If an entry in EventAction is found, then the Macro field is checked. If a macro has been specified, that command line is executed immediately and pGetAction loops back to get the next action (from the Message Queue or via FORM INPUT). Otherwise, the pGetAction command returns with the action name and the name of the window for which the action is intended is returned in vlTargetWindow. This window name is normally the name of the window in which the event occurred. Tool bar events are detected and reflected to vlInputWinName by setting vlTargetWindow to vlInputWinName (or the current window name if vlInputWinName is $NULL or blank). pGetAction also refreshes the spy window if it is open.

If no errors occur, vlStatus is set to blank. Otherwise, it is set to “ERROR”.