Description
Call back functions (CBFs) are similar to circuit methods (see methods) but are specifically provided as a portable interface between standard OS threads and Blueprint circuitry. Their prime purpose is to allow GUI threads to transparently communicate with the the main application threads. This avoids applications being locked-in to the details of particular message pumps such as those provided by Windows QT or MFC. The principal difference between CBFs and MTHDs is that the former typically execute within the GUI thread, and cannot be re-entered (re-entrancy of one).
Definition Content
The following information is required in order to define a GUI call back function (CBF);
Window Pointer Type
Executing CBF's window pointer type (see GUI programming).
Type Namespace
Executing CBF's window pointer type 'namepace' (see GUI programming).
Instance Content
The following information is required in order to instantiate a GUI call back function.
Name
Instance name (see Object Names)
Dimension
Instance dimensionality (see Object Dimensionality)
Presence
Instance presence flag (see Object Presence)
Occasionally Over-Rideable Functions
The following functions have generated bodies that can be 'over-ridden' (see Browsing and Inserting User Code);
Create Function
This over-rideable function creates the CBF and is called automatically once only when its parent circuit instance is created.
Integrate Function
This over-rideable function populates the CBF's parent pointer and is called automatically once only when its parent circuit instance is integrated.
Connect Function
This over-rideable function connects the CBF's trigger connection and is called automatically, once only, when its parent circuit instance is connected.
Activate Function
This over-rideable function activates the CBF, and is called automatically once only when the parent circuit instance is activated.
Execute Function
This over-rideable function is automatically called each time the CBF's trigger connection delivers an event. The generated code will call the Process function.
Frequently Over-Rideable Functions
The following functions have generated bodies that usually require insertion of user code (see Browsing and Inserting User Code);
Initialize Function
This user defined function is entered using the Blueprint editor and is automatically called once only before the CBF is first executed.
Process Function
This user defined function is entered using the Blueprint editor and is automatically called each time the CBF's trigger connection delivers an event. If the trigger event is overloaded (contains irregular multiplexed events) then the translator will generate one entry point for each overload (see Multiplexors).
Exit Function
This user defined function is entered using the Blueprint editor and is automatically called once only on process exit.
Member Functions
Call back functions support the following member functions. None of these functions takes an argument.
Name()
Returns the address of a string containing the executing call back element's creation name.
NumDimensions()
Returns the number of dimensions that the executing CBF instance was created with. This does not include the dimensionality of the parent circuit which can be obtained through use of the 'parent' member function (see below).
Dimensions()
Returns the address of an unsigned integer array containing the executing CBF's creation dimensions. The first element of the array contains the fastest varying (rightmost) dimension.
Element()
Returns the address of an unsigned integer array containing the executing CBF element's particular coordinates.
Parent()
Returns a reference to the executing CBF's parent circuit. If the CBF is defined in-line then the function will return a pointer of the parent circuit's derived instance type. If the CBF is defined explicitly then it will return a reference of the base circuit type and will therefore only provide this function and the four member functions described above (in this section).
Workspace()
Returns a reference to the executing CBF element's workspace object (see Workspace Objects).
Notes
CBFs are primarily used as a means of passing information generated by the application to the GUI for display (output). Information entered at the GUI by a user typically needs to be passed to the application (input) for control purposes, and this is generally achieved through the use of interface objects (Interface Objects).
Examples
See Accessing CLIP from Regular Threads.