The Trigger_RegisterFocusByName() function registers a focus trigger for a resource in the specified dictionary. 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_RegisterFocusByName(product_ID, qualified_resource, focus_type, attach_type, script processing_procedure {, tag})
• product_ID – An integer specifying the ID of the product that contains the form for which the trigger is being registered.
• qualified_resource – A string containing the fully qualified name of the resource. It must use the “form,” “window,” and “menu” sanScript qualifiers, such as:
Any resource names that contain spaces must be enclosed in single quotes.
• 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. |
SY_INVALID_OBJECT |
4 |
The object for which the trigger is being registered cannot be found. |
It’s important to remember that focus triggers are activated by focus events regardless of whether a script already exists for that focus event. Focus triggers 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) |