How to: Add Your Own Handler to the Report Builder's Registry

  • Article

The Report Builder uses an internal lookup table mapping event types in the Report or Label Designer to specific event handler classes. Because this table is built into reportbuilder.app, it is read-only and cannot be modified.

By default, the Report Builder will use an external table with the filename reportbuilder.dbf in preference to its internal handler table, if it meets one of the following requirements:

  • It is in Visual FoxPro's SET PATH

  • It is in the same folder as reportbuilder.app.

The Report Builder has a mechanism to create an external copy of the lookup table, available from its Options dialog box.

Once the file exists on disk, you can make changes to the table, either by browsing it in the Visual FoxPro directory, or by using the Report Builder's Handler Registry Table Explorer.

In this topic, you will learn how to:

  • Copy the read-only event lookup table so that you can make changes.

  • Explore the Report Builder's event lookup table.

  • Add and configure your own event handler class to the lookup table.

See Report Builder Event Handler Registry Table for more information on the lookup table.

Creating an editable copy of the internal lookup table

To copy the internal lookup table out to disk using the options dialog

  1. Open the Report Builder Options dialog box. For more information, see How to: Display the Report Builder Options Dialog Box.

  2. Click Create copy… to open the Save as dialog box.

  3. Change the file name and location if you wish, and click Save to create the copy.

  4. Click Close to dismiss the Options dialog box.

The default location in the Save as dialog box will be the directory in which reportbuilder.app is located, and the default file name will be reportbuilder.dbf. This is the table that the Report Builder will use in preference to its internal one.

Tip

After you create and edit your event lookup table, you can add it to your applications and give it a different name. To specify this table for the Report Builder's use in your applications, you invoke reportbuilder.app in a special configuration mode while performing setup tasks for your application. For more information, see How to: Specify an Alternate Report Event Handler Table.

To copy the internal lookup table out to disk using command-line parameters

  1. Open the Command window.

  2. Type one of the following commands:

    • DO (HOME() + "reportbuilder.app") WITH 5, cFilename

    • * OR:

    • DO (_REPORTBUILDER) WITH 5

The cFilename parameter must be a fully pathed file specification of a table (.dbf) file. If the file exists, it will be over-written. If you omit the cFilename parameter, the Save As dialog box will appear.

Browsing the Event Handler Registry table

To explore the lookup table using the Builder's Event Handler Registry browser

  1. Open the Report Builder Options dialog box. For more information, see How to: Display the Report Builder Options Dialog Box.

  2. Click Explore registry… to open the Event Handler Registry dialog box.

For more information on adjusting the contents of the lookup table, see Event Handler Registry Dialog Box (Report Builder).

Adding a custom handler class to the Event Handler Registry table

In this example, you will create a class that handles the event that occurs when you press CTRL-E on a label report control.

To create a CTRL-E label edit handler

  1. Create or edit a programmatic class library:

    MODIFY COMMAND c:\temp\mylibrary.prg

  2. Create your handler class by typing the following code, then save your changes:

DEFINE CLASS MyLabelEditor AS Custom
    PROCEDURE Execute( oEvent )
        LOCAL cCaption
        cCaption = INPUTBOX("Label caption:",;
                        "Label Properties", TRIM(frx.expr))
        IF NOT EMPTY( m.cCaption )
            REPLACE frx.expr WITH m.cCaption
            oEvent.SetHandledByBuilder(.T.)
            oEvent.SetReloadChanges(.T.)
        ENDIF
    ENDPROC
ENDDEFINE

To register your handler for the Ctrl-E builder event

  1. Open the Report Builder Options dialog box. For more information, see How to: Display the Report Builder Options Dialog Box.

  2. If the Current registry table text box contains "Internal lookup table," follow the steps above to copy the read-only event lookup table so that you can make changes.

  3. Click Explore registry… to open the Event Handler Registry dialog box.

  4. Locate a record with Type="H", Event=14, ObjType=5, ObjCode=0.

  5. If such a record does not exist in the table, add a new record to the table by clicking on Add Record.

  6. Set the field values as shown in the table below.

  7. Click Close to dismiss the Event Handler Registry dialog box.

  8. Click Close to dismiss the Report Builder Options dialog box.

Type

H

Class

MyLabelEditor

Library

c:\temp\mylibrary.prg

Description

Sample Ctrl-E on Label handler

Event

14

ObjType

5

ObjCode

0

Native

False

Debug

False

To test your event handler registry changes

  1. Open a report or label layout in the designer.

  2. Select a label control

  3. Press CTRL-E.

    You should see an INPUTBOX() dialog as your class is invoked to handle the event.

See Also

Tasks

How to: Configure the Report Builder's Event Handling
How to: Specify an Alternate Report Event Handler Table

Reference

Event Handler Registry Dialog Box (Report Builder)
Report Builder Options Dialog Box (Report Builder)
Report Builder Event Handler Registry Table

Concepts

Understanding Report Builder Events

Other Resources

Extending Reports at Design Time