ReportBuilder.App uses an internal lookup table to determine which handler class to instantiate for a given combination of EventType and report object (as specified by the currently selected record in the FRX cursor, which could be a report control, a report band, or the report header record itself). The structure of this table is shown below:

Any additional fields in this table are ignored by the report builder.

Classes defined in the registry table can be one of several types:

Event Handler classes can be of any Visual FoxPro base class but must implement the Event Handler API. The Event Handler API has the following attributes:

• A method named Execute that accepts a single object reference parameter.
  
  

What the class actually does in the Execute( oEvent ) method is not specified, although for Event Handler classes they probably will need to set the return flags:

В	Copy Code
DEFINE CLASS MyHandler AS Custom PROCEDURE Execute( oEvent ) * You can alter oEvent.returnFlags to suit oEvent.SetHandledByBuilder(.T. | .F. ) oEvent.SetReloadChanges( .T. | .F. ) ENDPROC ENDDEFINE

This method is passed a reference to an object representing the event that occurred. The handler should assign the appropriate ReturnFlags value to indicate what action the designer should take next when the builder terminates and returns control.

Event Handlers:

• Are identified by a REC_TYPE value of "H".
  
  
• Are generally only instantiated for a specific designer builder event type and report object type combination.
  
  

For more information on the properties and methods of the object reference passed to the handler class in the Execute() method, see The Report Builder Event Class.

Filter classes can be of any Visual FoxPro base class but must implement the Event Handler API (see above) plus one additional public property, allowToContinue:

В	Copy Code
DEFINE CLASS MyFilter AS Custom allowToContinue = .T. PROCEDURE Execute( oEvent ) * decide whether or not to process the event THIS.allowToContinue = .T. * You can optionally alter oEvent.returnFlags to suit oEvent.SetHandledByBuilder(.T. | .F. ) oEvent.SetReloadChanges( .T. | .F. ) ENDPROC ENDDEFINE

Filter Handler classes:

• Are identified by a REC_TYPE value of "F".
  
  
• Are instantiated for every report builder event.
  
  
• Are processed in the order indicated by the FLTR_ORDR field.
  
  
• Can prevent further processing of the event by setting their AllowToContinue property to false (.F.)
  
  
• Can apply pre-processing to the FRX cursor prior to the event being processed by an Event Handler class.
  
  

Exit Handler classes must support the Event Handler API.

Exit Handler classes:

• Are identified by a REC_TYPE value of "X".
  
  
• In general are a way of getting some code to run at clean-up time.
  
  
• Are only processed if an Event Handler class was previously located and executed. If a Filter handler prevented further processing, then Exit handlers will not be processed.
  
  
• Like all handler classes, they have the opportunity to alter the oEvent.ReturnFlags value but it is very bad practice to do so.
  
  

You can replace the implementation of the GETEXPR dialog box used in the report builder by registering a class of REC_TYPE="G" in the handler registry. The class must support the GetExpression() method as shown in this example:

В	Copy Code
DEFINE CLASS MyGetExpr AS Custom PROCEDURE GetExpression( cDefExpr, cDataType, cCalledFrom, oEvent ) LOCAL cExpression GETEXPR TO cExpression DEFAULT cDefExpr RETURN cExpression ENDPROC ENDDEFINE

Only one class may be registered as the default GetExpressionWrapper. If there are more than one record of REC_TYPE="G," only the first one located will be used by the report builder.

You can replace the implementation of the dialog box that appears when you click the Edit settings command button in the Run-time extensions group on the Other tab of the Report Builder by registering a class in the handler registry with a REC_TYPE of "E". The class must support the Event Handler API. If implementing a form class, then the form must be issued as a MODAL window.

A run-time extension editor classes should do the following in the Execute() method:

• Read the metadata XML from the STYLE field.
  
  
• Present a user interface to allow the user to edit the metadata.
  
  
• Save a valid XML fragment back into the STYLE field.
  
  
• Unlike the other handler types shown above, it should not attempt to set the return flags.
  
  

Only one class may be registered as the default RuntimeExtensionEditor. If there is more than one "E" record in the handler registry table, the first one found will be used.

You can add pages to the pageframe in the Multiple Selection Dialog Box (Report Builder) by registering a class in the handler registry with a REC_TYPE of "M".

The class must be derived from the Page Object. If the page contains a Container Object that implements .LoadFromFrx() and .SaveToFrx(), then these methods will be called automatically by the multiple-selection dialog at appropriate points:

В

Copy Code

DEFINE CLASS pagAlign AS page Caption = "Alignment" Name = "pagAlign" ADD OBJECT Panel1 AS panelAlign ENDDEFINE DEFINE CLASS panelAlign as Container BorderWidth = 0 Width = 300 Height = 300 Event = null frxCursor = null ADD OBJECT Check1 AS Checkbox WITH ; Caption = "Align to leftmost object", ; Top = 100, Left = 50, Width = 150, Value=.F. PROCEDURE LoadFromFrx() * No initialization required RETURN .T. ENDPROC PROCEDURE SaveToFrx() IF THIS.Check1.Value LOCAL curSel curSel = SELECT() SELECT MIN(hpos) AS hpos FROM frx ; WHERE curpos AND objcode<>53 ; INTO CURSOR query newHpos = query.hpos USE IN query SELECT frx SCAN FOR curpos AND RECNO()>1 REPLACE hpos WITH m.newHpos ENDSCAN SELECT (m.curSel) ENDIF RETURN .T. ENDPROC ENDDEFINE

This example adds a tab to the multiple-selection dialog with a single checkbox that, if checked, will set the horizontal position all selected objects to that of the left-most positioned object in the selection.

The container object may implement any of the following PEMs:

• The LoadFromFrx() method is called during the initialization of the form, and is a good place to read values from the frx cursor in order to initialize values of the controls in the container.
  
  
• The SaveToFrx() method is called when the user clicks OK. Return FALSE if you wish to prevent the dialog from closing.
  
  
• If defined, the Event property will be assigned a reference to the report builder's Event object. (See The Report Builder Event Class for more information.)
  
  
• If defined, the frxCursor property will be assigned a reference to the Event object's frxCursor member object, for convenience. (See FRX Cursor Foundation Class for more information.)
  
  

There can be more than one record in the handler registry defined with REC_TYPE="M,". Each page class will be loaded into the dialog box as a separate tab.

When the report builder is invoked, the Report Designer passes it an event type ID, with a copy of the FRX file open in a private data session. The report object that the event applies to is usually identified by the location of the record pointer in the FRX cursor. The report builder takes note of the OBJTYPE and OBJCODE values on the selected record, and then refers to the handler registry table.