Trigger_RegisterFocusByName()

Examples


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.

Syntax

Trigger_RegisterFocusByName(product_ID, qualified_resource, focus_type, attach_type, script processing_procedure {, tag})

Parameters

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:

[spacer]

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:

[spacer]

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.

Return value

An integer corresponding to the following constants:

[spacer]

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.


Comments

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:

[spacer]

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)



Documentation Feedback