The Trigger_RegisterFocus() function registers a focus trigger for use with the runtime engine. Focus triggers are activated by “focus” events in an application, such as a window opening or closing, or the focus moving from one field to the next. Focus triggers can be linked to any location where Dexterity allows you to attach a script, such as window pre and post scripts, or field pre, change and post scripts.
Trigger_RegisterFocus(anonymous (qualified_resource), focus_type, attach_type, script processing_procedure {, tag})
• qualified_resource – A resource fully qualified using the “form,” “window,” and “menu” sanScript qualifiers, such as:
Typically, you should use the anonymous() function with this parameter to avoid implicitly opening the resource.
• focus_type – An integer identifying which focus event activates the trigger. Use either the integer value or its corresponding constant:
Constant |
Value |
---|---|
TRIGGER_FOCUS_PRE |
0 |
TRIGGER_FOCUS_CHANGE |
1 |
TRIGGER_FOCUS_POST |
2 |
TRIGGER_FOCUS_PRINT |
3 |
TRIGGER_FOCUS_ACTIVATE |
4 |
TRIGGER_FOCUS_FILL |
5 |
TRIGGER_FOCUS_INSERT |
6 |
TRIGGER_FOCUS_DELETE |
7 |
TRIGGER_FOCUS_CONTEXT_MENU |
9 |
If the qualified_resource is a menu, focus_type indicates which menu item activates the trigger. If the qualified_resource is a button field, only change events (TRIGGER_FOCUS_CHANGE) activate a focus trigger.
• attach_type – An integer indicating when the focus trigger runs relative to the original focus event:
Constant |
Value |
---|---|
TRIGGER_BEFORE_ORIGINAL |
1 |
TRIGGER_AFTER_ORIGINAL |
2 |
• script processing_procedure – A procedure you write that’s run when the focus trigger is activated.
• tag – An optional returned integer that uniquely identifies the trigger. This value is used when you want to unregister, enable or disable the trigger individually.
An integer corresponding to the following constants:
Constant |
Value |
Description |
---|---|---|
SY_NOERR |
0 |
No error occurred. |
SY_UNKNOWN |
1 |
An unknown error occurred and the trigger was not registered. |
SY_INVALID_SCRIPT |
2 |
The trigger processing script was either not found or had the wrong number of parameters. The trigger was not registered. |
SY_INVALID_FOCUS |
3 |
The focus_type is not valid for the qualified_resource. |
It’s important to remember that focus triggers are activated by focus events regardless of whether a script already exists for that focus event. You can create focus triggers that are activated by the following types of objects and focus events:
Object |
Available focus events |
---|---|
Field |
pre, change, post, or context menu (Note: Button fields run triggers for change focus events only.) |
Form |
pre or post |
Window |
pre, post, activate, print, or context menu |
Scrolling Window |
pre line, change line, post line, fill line, insert line, delete line, or context menu |
Menu |
change (for the menu item) |
Command |
change (only for commands of type Script) |