Clarion Community Help

ToolbarClass and ToolbarTarget objects work together to reliably “convert” an event associated with a toolbar button into an appropriate event associated with a specific control or window. This lets you use a single toolbar to drive a variety of targets, such as update forms, browse lists, relation tree lists, etc. A single toolbar can even drive multiple targets (two or more BrowseBoxes) in a single procedure.

Although the ToolbarTarget is useful by itself, other more useful classes are derived from it (ToolbarListboxClass, the ToolbarRelTreeClass, and the ToolbarUpdateClass), and other structures, such as the ToolbarClass, use it to reference any of these derived classes. The classes derived from ToolbarTarget let you set the state of the toolbar appropriate to the toolbar driven entity (set tooltips, enable/disable buttons, etc.), then process toolbar events for the entity by converting the generic toolbar events into appropriate entity-specific events.

ToolbarTarget Concepts

Within an MDI application, the ToolbarClass and ToolbarTarget work together to reliably interpret and pass an event (EVENT:Accepted) associated with a toolbar button into an event associated with a specific control or window. For example, the end user CLICKS on a toolbar button (say the “Insert” button) on the MDI application frame. The frame procedure forwards the event to the active thread (POST(EVENT:Accepted,ACCEPTED(),SYSTEM{Prop:Active})). The active thread (procedure) manages a window that displays two LIST controls, and one of the LISTs has focus. This procedure has a ToolbarClass object plus a ToolbarTarget object for each LIST control. The ToolbarClass object takes the event (ToolbarClass.TakeEvent)1 and forwards the event to the active ToolbarTarget object (the target that represents the LIST with focus). The ToolbarTarget object takes the event (ToolbarListBoxClass.TakeEvent) and handles it by posting an appropriate event to a specific control or to the window, for example:

POST(EVENT:ACCEPTED,SELF.InsertButton) !insert a record

POST(EVENT:PageDown,SELF.Control)      !scroll a LIST

POST(EVENT:Completed)                  !complete an update form

POST(EVENT:CloseWindow)                !select a record

etc.

1If the procedure has a WindowManager object, the WindowManager object takes the event (WindowManager.TakeEvent) and forwards it to the ToolbarClass object (WindowManager.TakeAccepted).

ToolbarTarget Relationship to Other Application Builder Classes

At present, the ABC Library has three classes derived from the ToolbarTarget class:

These ToolbarTarget objects convert generic toolbar events into appropriate entity-specific events. There may be zero or more ToolbarTarget objects within a procedure; however, only one is active at a time.

The ToolbarClass keeps a list of ToolbarTarget objects so it can forward events and method calls to a particular target.

ToolbarTarget ABC Template Implementation

Each template that requests global toolbar control instantiates a ToolbarTarget object. The FormVCRControls template's ToolbarTarget object is called ToolBarForm; the RelationTree template's ToolbarTarget object is called REL#::Toolbar, where # is the RelationTree template's instance number; and the BrowseBox's ToolbarTarget object is completely encapsulated within the BrowseClass object and is not referenced in the template generated code. You may see code such as the following in your template generated procedures.

Toolbar    ToolbarClass            !declare Toolbar object

CODE

!

ThisWindow.Init PROCEDURE

SELF.AddItem(Toolbar)             !register Toolbar with WindowManager

BRW1.AddToolbarTarget(Toolbar)    !register BrowseClass as target

Toolbar.AddTarget(REL1::Toolbar,?RelTree) !register RelTree as target

SELF.AddItem(ToolbarForm)         !register update form as target

ToolbarTarget Source Files

The ToolbarTarget source code is installed by default to the Clarion \LIBSRC folder. The ToolbarTarget source code and its respective components are contained in: