Plugin SDK Registration Reference

From Real Software Documentation

Contents 1 REALRegisterClass 2 REALRegisterInterface 3 REALRegisterModule 4 REALRegisterControl 5 SetClassConsoleSafe 6 REALRegisterBackgroundTask 7 REALUnregisterBackgroundTask 8 PluginEntry 9 REALclassDefinition 10 REALmoduleDefinition 11 REALinterfaceDefinition 12 REALcontrol 13 REALbasic Types To Plugin Types 14 REALmethodDefinition 15 REALproperty 16 REALevent 17 REALeventInstance 18 REALconstant 19 REALstructure 20 REALenum 21 REALcontrolBehaviour

REALRegisterClass

This function registers a plugin class for use within REALbasic based on the REALclassDefinition provided. This function must be called from within the PluginEntry method.

void REALRegisterClass( REALclassDefinition *defn );

• defn: the class definition description to register

Return Value none

REALRegisterInterface

This function registers a plugin interface for use within REALbasic based on the REALinterfaceDefinition provided. This function must be called from within the PluginEntry method.

void REALRegisterInterface( REALinterfaceDefinition *defn )

• defn: the interface definition description to register

Return Value none

REALRegisterModule

This function registers a plugin module for use within REALbasic based on the REALmoduleDefinition provided. This function must be called from within the PluginEntry method.

void REALRegisterModule( REALmoduleDefinition *defn );

• defn: the module definition description to register

Return Value none

REALRegisterControl

This function registers a plugin control for use within REALbasic based on the REALcontrol provided. This function must be called from within the PluginEntry method.

void REALRegisterControl( REALcontrol *defn );

• defn: the control definition description to register

Return Value none

SetClassConsoleSafe

Used to mark a class definition as being console safe. You must call this function before registering the class with REALRegisterClass, which means it must be called within the PluginEntry method. Note that this is a helper method which simply sets the REALconsoleSafe flag on the class definition.

void SetClassConsoleSafe( REALclassDefinition def );

• def: the class definition to mark as console safe

Return Value none

REALRegisterBackgroundTask

Creates a new background timer which fires around the given period. The period is expressed in milliseconds, and is used as an approximation. Optionally, you can pass extra data to the callback function via the "data" parameter. When you no longer require the background task, you can cancel it by calling REALUnregisterBackgroundTask.

long REALRegisterBackgroundTask( BackgroundTaskProc proc, unsigned long period, void *data );

• proc: the callback procedure to call. This parameter cannot be null.
• period: the approximate rate at which to fire the callback procedure, expressed in milliseconds
• data: (optional) data to pass to the callback procedure. Note that it is the caller's responsibility to ensure this pointer remains valid.

Return Value the identifier to be used for removing the background task

Available in REAL Studio 2007r2 and newer.

REALUnregisterBackgroundTask

Unregisters a background task which was previously created with REALRegisterBackgroundTask.

void REALUnregisterBackgroundTask( long id );

• id: the identifier of the background task to unregister

Return Value none

PluginEntry

This function must be present in your plugin as it is the entrypoint to the plugin. The Plugin SDK will automatically call the PluginEntry method, where the plugin should register any code items. Since the PluginEntry is called when the IDE is loaded, as well as when the user's application is launched, you should take care to avoid time-consuming operations.

void PluginEntry( void );

• parameters: none

Return Value none

REALclassDefinition

This structure is used to define a plugin class when passed into REALRegisterClass. Any optional fields can be set to NULL (or zero). For the array count fields, a common construct is to use the _countof macro. eg) _countof( someMethodDefArray )

• version: the structure version number. This should always be set to kCurrentREALControlVersion.
• name: the name of the class to define. Note that this string must be an ANSI string (not Unicode).
• superName: the name of the superclass for this class. Note that this string must be an ANSI string (not Unicode). This field can be NULL, in which case the superclass will be Object.
• dataSize: the size to allocate for instance specific data, which can be retrieved with REALGetClassData or the ClassData macro.
• forSystemUse: this field is reserved and must be set to zero
• constructor: (optional) this field is a misnomer as it defines the class initializer (not the constructor). The initializer fires immediately after the object has been allocated, but before the user's constructor has fired. This REALproc's signature must be void Name( REALobject ) and the only parameter is an instance of the class object.
• destructor: (optional) this field is a misnomer as it defines the class finalizer (not the destructor). The finalizer fires immediately before the object's memory is released, but after the user's destructor has fired. This REALproc's signature must be void Name( REALobject ) and the only parameter is an instance of the class object.
• properties: (optional) an array of REALproperty definitions which specify a list of properties (and computed properties) for the class. Note that the first parameter to these properties is a REALobject representing the class instance itself (the implicit me parameter).
• propertyCount: (optional) the number of properties defined in the "properties" array. If the "properties" field is non-NULL, this field is not optional.
• methods: (optional) an array of REALmethodDefinitions which specify a list of methods for the class. Note that the first parameter to these methods is a REALobject representing the class instance itself (the implicit me parameter).
• methodCount: (optional) the number of methods defined in the "methods" array. If the "methods" field is non-NULL, this field is not optional.
• events: (optional) an array of REALevent definitions which specify a list of events (event definitions in REALbasic parlance) for the class to expose.
• eventCount: (optional) the number of events defined in the "events" array. If the "events" field is non-NULL. this field is not optional.
• eventInstances: (optional) an array of REALeventInstance definitions which specify a list of events this plugin class implements. Note that the class can only implement events which are defined by the superclass. Note that the first parameter to these event instance method definitions is a REALobject representing the class instance itself (the implicit me parameter).
• eventInstanceCount: (optional) the number of event instances in the "eventInstances" array. If the "eventInstances" field is non-NULL, this field is not optional.
• interfaces: (optional) a comma delimited string of interfaces which the plugin class implements. Note that this string must be an ANSI string (not unicode) and spaces are tolerated. Also note that it is the plugin author's responsibility to ensure that the plugin implements the interface's methods.
• obsolete1: this field is deprecated and should not be used in new plugins. This field should be NULL.
• obsolete2: this field is deprecated and should not be used in new plugins. This field should be zero.
• constants: (optional) an array of REALconstant definitions which specify a list of constants the plugin class defines
• constantCount: (optional) the number of constants defined in the "constants" array. If the "constants" field is non-NULL, this field is not optional.
• mFlags: (optional) a bitmask of flags describing extra information about the plugin class. Currently, the only flags supported are REALconsoleOnly (a console-only class which is not available to desktop projects) and REALconsoleSafe (a class which is available to both desktop and console projects). If this field is zero, then the plugin class is assumed to be console-unsafe (only available to desktop projects).
• sharedProperties: (optional) an array of REALproperty definitions which specify a list of shared properties (and shared computed properties) for the class. Note that the first parameter to these properties is always NULL.
• sharedPropertyCount: (optional) the number of properties defined in the "properties" array. If the "properties" field is non-NULL, this field is not optional.
• sharedMethods: (optional) an array of REALmethodDefinitions which specify a list of shared methods for the class. Note that the first parameter to these methods is always NULL.
• sharedMethodCount: (optional) the number of methods defined in the "methods" array. If the "methods" field is non-NULL, this field is not optional.

REALmoduleDefinition

This structure is used to define a plugin module when passed into REALRegisterModule. Any optional fields can be set to NULL (or zero). For the array count fields, a common construct is to use the _countof macro. eg) _countof( someMethodDefArray )

• version: the structure version number. This should always be set to kCurrentREALControlVersion.
• name: the name of the module to define. Note that this string must be an ANSI string (not Unicode).(
• methods: (optional) an array of REALmethodDefinitions which specify a list of methods for the module. Note that the first parameter to these methods is always NULL.
• methodCount: (optional) the number of methods defined in the "methods" array. If the "methods" field is non-NULL, this field is not optional.
• constants: (optional) an array of REALconstant definitions which specify a list of constants the plugin module defines
• constantCount: (optional) the number of constants defined in the "constants" array. If the "constants" field is non-NULL, this field is not optional.
• properties: (optional) an array of REALproperty definitions which specify a list of properties (and computed properties) for the module. Note that the first parameter to these properties is always NULL.
• propertyCount: (optional) the number of properties defined in the "properties" array. If the "properties" field is non-NULL, this field is not optional.
• structures: (optional) an array of REALstructure definitions which specify a list of structures for the module.
• structureCount: (optional) the number of structures defined in the "structures" array. If the "structures" field is non-NULL, this field is not optional.
• enums: (optional) an array of REALenum definitions which specify a list of enumerations for the module.
• enumCount: (optional) the number of enumerations defined in the "enums" array. If the "enums" field is non-NULL, this field is not optional.

REALinterfaceDefinition

This structure is used to define a plugin interface when passed into REALRegisterInterface. Any optional fields can be set to NULL (or zero). For the array count fields, a common construct is to use the _countof macro. eg) _countof( someMethodDefArray )

• version: the structure version number. This should always be set to kCurrentREALControlVersion.
• name: the name of the interface to define. Note that this string must be an ANSI string (not Unicode).
• methods: (optional) an array of REALmethodDefinitions which specify a list of methods for the interface. These objects should not specify an implementation, just a declaration string.
• methodCount: (optional) the number of methods defined in the "methods" array. If the "methods" field is non-NULL, this field is not optional.

REALcontrol

This structure is used to define a plugin control when passed into REALRegisterControl. Any optional fields can be set to NULL (or zero). For the array count fields, a common construct is to use the _countof macro. eg) _countof( someMethodDefArray ) Note that controls automatically have a superclass of RectControl, or if the REALinvisibleControl flag is set, Control. If you wish for your control to have a different superclass, then you must declare them as a REALclassDefinition.

• version: the structure version number. This should always be set to kCurrentREALControlVersion.
• name: the name of the control to define. Note that this string must be an ANSI string (not Unicode).
• dataSize: the size to allocate for instance specific data, which can be retrieved with REALGetControlData or the ControlData macro.
• flags: a bitmask specifying additional information about the control. The following flags are supported:
  • REALcontrolAcceptFocus -- this control can accept keyboard focus at any time.
  • REALcontrolFocusRing -- tells REALbasic to automatically draw a focus ring around the control when it has focus (as appropriate). This flag only affects the Mac.
  • REALinvisibleControl -- if this flag is set, then the control is a subclass of Control (otherwise, it is a subclass of RectControl).
  • REALopaqueControl -- indicates a control with no transparent regions as an optimization for background redrawing. This flag only affects the Mac.
  • REALcontrolOwnsCursor -- tells REALbasic that the control is managing its own cursor, so REALbasic will not set the cursor automatically.
  • REALcontrolIsHIViewCompatible -- indicates that the plugin author assures RB that this control will work 100% on REALbasic Window objects with compositing turned on (running Mac OS 10.2 and beyond). It draws all of its content inside its Redraw event, or methods called by the redraw event, does not call Draw1Control, and doesn't do anything that Apple specifically forbids an HIView control to do. This flag only affects the Mac.
  • REALdontTryHIViewize -- indicates that REALbasic is not to try to turn this control into a custom HIView. Use this if your plugin contains an OS control, and is already an HIView, or you explicitly write code to make your control an HIView. This flag only affects the Mac.
  • REALdontEraseBackground -- when set, tells the REALbasic framework not to automatically erase the control when it is resized. This flag only affects Windows.
  • REALcontrolRequiresComposite -- indicates that this control requires a composite window to function properly. This flag only affects the Mac.
• toolbarPICT: this field is deprecated and should not be used in new plugins. Instead, you should specify the icon in the RBX plugin format manually. This field should be zero.
• toolbarDownPICT: this field is deprecated and should not be used in new plugins. This field should be zero.
• defaultWidth: specifies the default width of the control. This is the initial width of the control when the user drags one into the window editor. This value should always be non-zero.
• defaultHeight: specifies the default height of the control. This is the initial height of the control when the user drags one into the window editor. This value should always be non-zero.
• properties: (optional) an array of REALproperty definitions which specify a list of properties (and computed properties) for the control. Note that the first parameter to these properties is always a REALobject specifying the control instance.
• propertyCount: (optional) the number of properties defined in the "properties" array. If the "properties" field is non-NULL, this field is not optional.
• methods: (optional) an array of REALmethodDefinitions which specify a list of methods for the control. Note that the first parameter to these methods is a REALobject representing the control instance itself (the implicit me parameter).
• methodCount: (optional) the number of methods defined in the "methods" array. If the "methods" field is non-NULL, this field is not optional.
• events: (optional) an array of REALevent definitions which specify a list of events (event definitions in REALbasic parlance) for the control to expose.
• eventCount: (optional) the number of events defined in the "events" array. If the "events" field is non-NULL. this field is not optional.
• behaviour: (optional) a pointer to a REALcontrolBehaviour structure describing the "behavior" of the control. Essentially, this structure is a set of callback functions which are called when the IDE or framework needs to query the plugin for more information.
• forSystemUse: reserved, must be zero
• eventInstances: (optional) an array of REALeventInstance definitions which specify a list of events this plugin control implements. Note that the control can only implement events which are defined by the superclass. Note that the first parameter to these event instance method definitions is a REALobject representing the control instance itself (the implicit me parameter).
• eventInstanceCount: (optional) the number of event instances in the "eventInstances" array. If the "eventInstances" field is non-NULL, this field is not optional.

interfaces: (optional) a comma delimited string of interfaces which the plugin control implements. Note that this string must be an ANSI string (not unicode) and spaces are tolerated. Also note that it is the plugin author's responsibility to ensure that the plugin implements the interface's methods.

• obsolete1: this field is deprecated and should not be used in new plugins. This field should be NULL.
• obsolete2: this field is deprecated and should not be used in new plugins. This field should be zero.
• constants: (optional) an array of REALconstant definitions which specify a list of constants the plugin control defines
• constantCount: (optional) the number of constants defined in the "constants" array. If the "constants" field is non-NULL, this field is not optional.

REALbasic Types To Plugin Types

There are times when a plugin must use REALbasic syntax to describe a code item (such as a method or a property), but use a C type to actually interact with the user (such as a function implementation). During these times, you must map REALbasic type information onto C type information. The following chart provides you with the most common type mappings.

REALbasic Type	C Type
String	REALstring
Any Object Type	REALobject
Integer, Int32, Color	long
UInt32	unsigned long
Int64	RBInt64
UInt64	unsigned RBInt64
Currency	REALcurrency
Int16, Short	short
UInt16	unsigned short
Int8	char
UInt8, Byte	unsigned char
Single	float
Double	double
WindowPtr	The appropriate OS-specific window pointer type (such as HWND on Windows)
Ptr	void *
REALbasic Array Type	REALarray
Structure Array Type	A C array of the appropriate type
CString	const char *
WString	const wchar_t *
CFStringRef	CFStringRef
PString	const unsigned char *
Variant	REALobject
Boolean	Boolean
Any Structure Type	The appropriate C structure type
Any Enumeration Type	Based on the enumeration's "Type" field, but generally a long

If any of the REALbasic types are defined as ByRef, then the C Type should be considered as a pointer to the appropriate type. For instance, a ByRef String would map to a REALstring *. If a declaration describes a ParamArray, then you will receive a REALarray object with an element type based on the declared REALbasic type of the array.

REALmethodDefinition

This structure is used by a plugin to describe a method. The data which is pertinent in this structure varies depending on what is making use of it. For instance, when defining an interface, the "function" field is ignored. However, when defining a class, the "function" field is required.

• function: A REALproc to be called, when appropriate. The REALproc's signature should match that of the declaration (substituting REALbasic types for plugin SDK types as appropriate. See the REALbasic Types To Plugin Types excerpt). The first parameter should always be a REALobject which represents the implicit \"me\" parameter, however, this parameter may be NULL depending on the *method definition usage. If this definition is for use with an interface declaration, then this field is optional.
• setter Function: this field is deprecated and should not be used in new plugins. Instead, the \"declaration\" field should specify an assigns parameter (though you may want to consider making a computed property instead). This field should always be NULL.
• declaration: the method's declaration using REALbasic syntax. This declaration should not include scope information, and must use legal syntax and identifiers. Note that this string must be an ANSI string, not Unicode.
• mFlags: (optional) a bitmask of flags which describes extra information about the method. Valid flags include:
  • REALconsoleSafe -- this method is safe to call in console projects as well as desktop projects.
  • REALconsoleOnly -- this method is safe to call in console projects only
  • REALScopeGlobal -- this method is global when defined in a module, or public otherwise
  • REALScopePublic -- this method is public (both in a module, as well as a class)
  • REALScopeProtected -- this method is protected when defined in a class, or public when defined in a module
  • REALScopePrivate -- this method is private

Note that the scope flags are only useful for methods which are not defined in an interface (as interface methods are always public methods). Also note that if a scope flag is not set, then the default scoping rules apply based on how the method is used. In all cases, the default scope is Public (note that this includes Modules, where Public is not the same as Global).

REALproperty

This structure is used by a plugin to define a property or a computed property. The difference between the two fundamental types is that a computed property defines a REALproc for the getter and/or setter, while the non-computed property specifies REALstandardGetter and/or REALstandardSetter.

• group: the "group" to which the property belongs when it is displayed in the properties listbox in the IDE. Note that this string must be an ANSI string (not Unicode).
• name: the name of the property, which must be a legal REALbasic identifier. Note that this string must be an ANSI string (not Unicode).
• type: the property's type. See the REALbasic Types to Plugin Types excerpt for more information about type mapping. This string must be an ANSI string, not Unicode.
• flags: a bitmask of flags to describe the property. Valid flags include:
  • REALpropRuntimeOnly -- this property can only be assigned to at runtime; it is not displayed in the IDE at design time
  • REALconsoleSafe -- this property is safe to call in console projects as well as desktop projects.
  • REALconsoleOnly -- this property is safe to call in console projects only
  • REALScopeGlobal -- this property is global when defined in a module, or public otherwise
  • REALScopePublic -- this property is public (both in a module, as well as a class)
  • REALScopeProtected -- this property is protected when defined in a class, or public when defined in a module
  • REALScopePrivate -- this property is private

Note that if a scope flag is not set, then the default scoping rules apply based on how the property is used. In all cases, the default scope is Public (note that this includes Modules, where Public is not the same as Global).

• getter: a REALproc for a computed property's getter, which should be declared as @Type@ GetterName( REALobject, long ). The second parameter is the value specified in the "param" field. Use REALstandardGetter and the "param" field to create a non-computed property (see "param" field for more information).
• setter: a REALproc for a computed property's setter, which should be declared as void SetterName( REALobject, long, @Type@ ). The second parameter is the value specified in the "param" field. Use REALstandardSetter and the "param" field to create a non-computed property (see "param" field for more information).
• param: (optional) when defining a computed property, this is a general-purpose field used to pass extra information into the getter and setter procedures. When defining a non-computed property, this field specifies the offset in the class' instance data to the property's value. In this case, it is recommended that you use the FieldOffset macro to fill out this field. For instance, FieldOffset( ClassData, mInstanceMember ). When defining a non-computed property, this field is not optional.
• editor: this field is deprecated and should be set to NULL
• enumCount: (optional) the number of entries in the "enumEntries" array. This field is not optional if the "enumEntries" field is non-NULL.
• enumEntries: (optional) an array of null-terminated strings describing possible "enumeration" names for this property which are displayed in the IDE. The value associated with the enumeration is based on the array index (so the first item in the enumeration name array has an integer value of 0). Note that these strings must be ANSI (not Unicode). Also note that this field (and the enumCount field) are ignored for any code item aside from a class definition.

Warning: REALstandardGetter for double does not work (at least in versions up to RS 2011r4.3)

REALevent

This structure is used to declare an event for a class to expose (also known as an event definition in REALbasic parlance). declaration: the events's declaration using REALbasic syntax. This declaration must use legal syntax and identifiers. Note, this string must be ANSI, not Unicode.

• forSystemUse: reserved, must be zero.

REALeventInstance

This structure is used to define an event for a class to implement (also known as an event handler in REALbasic parlance). declaration: the event's declaration using REALbasic syntax. This declaration must use legal syntax and identifiers, and must also match an event definition from the class' superclass. Note, this string must be ANSI, not Unicode.

• implementation: a REALproc to handle the event once it is fired. Note that the first parameter of this function must be a REALobject for the implicit "me" parameter for the class. See the REALbasic Types to Plugin Types section for more information about type mapping.

REALconstant

This structure is used to delcare a constant for a class or module. All constant type information is derived from the constant's declaration, which means that constant values must be valid REALbasic values (ie -- the same rules apply to plugins defining constants as apply to REALbasic users making constants in the IDE). declaration: a legal REALbasic constant declaration, without the Const keyword, in the form "name = value". For string values, the the value field must be quoted according to REALbasic syntax. Note that this string must be ANSI, not Unicode.

• reserved1: reserved, must be zero
• mFlags: (optional) a bitmask of flags which describes extra information about the constant. Valid flags include:
  • REALScopeGlobal -- this constant is global when defined in a module, or public otherwise
  • REALScopePublic -- this constant is public (both in a module, as well as a class)
  • REALScopeProtected -- this constant is protected when defined in a class, or public when defined in a module
  • REALScopePrivate -- this constant is private

Note that if a scope flag is not set, then the default scoping rules apply based on how the constant is used. In all cases, the default scope is Public (note that this includes Modules, where Public is not the same as Global).

REALstructure

This structure is used to declare a REALbasic structure code item.

• name: the name of the structure, which must be a legal REALbasic identifier. Note that this string must be an ANSI string, not Unicode.
• mFlags: (optional) a bitmask of flags which describes extra information about the structure. Valid flags include:
  • REALScopeGlobal -- this structure is global when defined in a module, or public otherwise
  • REALScopePublic -- this structure is public (both in a module, as well as a class)
  • REALScopeProtected -- this structure is protected when defined in a class, or public when defined in a module
  • REALScopePrivate -- this structure is private

Note that if a scope flag is not set, then the default scope is Public.

• fields: an array of fields that the structure declares. These fields must be legal REALbasic structure declarations, in the form "Name as StructureType." Note that some REALbasic types are not legal in structures (such as objects, or unbounded arrays). See the REALbasic Types to Plugin Types section for more information about type mapping. These strings must be an ANSI string, not Unicode.
• numFields: the number of items in the "fields" array

REALenum

This structure is used to declare a REALbasic enumeration.

• name: the name of the enumeration, which must be a legal REALbasic identifier. Note this string must be ANSI, not Unicode.
• type: (optional) the type of the enumeration. Currently, only integer types are supported (such as Integer, Int8, etc). If this field is NULL, then the type is assumed to be an Int32.
• mFlags: (optional) a bitmask of flags which describes extra information about the enumeration. Valid flags include:
  • REALScopeGlobal -- this enumeration is global when defined in a module, or public otherwise
  • REALScopePublic -- this enumeration is public (both in a module, as well as a class)
  • REALScopeProtected -- this enumeration is protected when defined in a class, or public when defined in a module
  • REALScopePrivate -- this enumeration is private

Note that if a scope flag is not set, then the default scope is Public.

• fields: an array of fields that the enumeration declares. These fields must be legal REALbasic enumeration declarations, in the form "Name = Value" or "Name." If a value is not specified, then the value is determined based on the standard REALbasic enumeration rules.
• numFields: the number of items in the "fields" array

REALcontrolBehaviour

This structure is a set of callback functions which are called when the IDE or framework needs to query the plugin for more information about a REALcontrol. It is the preferred way to implement many control events instead of using REALeventInstance and REALevent arrays.

• constructorFunction: called when the control is first created and provides a place for you to setup initial values for the control. Called at design time as well as at runtime.
• destructorFunction: called before the control is destroyed and provides a place for you to release memory for the control's internal data. Called at design time as well as runtime.
• redrawFunction: called when the control needs to be redrawn. Called at design time as well as runtime.
• clickFunction: called when the control has been clicked on. This is akin to the MouseDown event in REALbasic. Called only at runtime. Return true from this function will allow REALbasic to fire the "mouseDragFunction" and "mouseUpFunction" when appropriate.
• mouseDragFunction: called during a mouse drag operation where the control has captured the mouse. Called only at runtime. Note that this function will be called only if you return true from the "clickFunction."
• mouseUpFunction: called when the mouse button has been released. Called only at runtime. Note that this function will be called only if you return true from the "clickFunction."
• gainedFocusFunction: this callback is fired when the control has gained focus. Note that this function will only be called if your control can accept focus. Called only at runtime.
• lostFocusFunction: this callback is fired when the control has lost focus. Note that this function will only be called if you control can accept focus, and already has the focus. Called only at rumtime.
• keyDownFunction: called when the user has pressed a key while you control has focus. Called only at runtime.
• openFunction: this function is called after the control's underlying pane has been opened and is akin to the Open event in REALbasic. Called at design time (immediately after the "constructorFunction") as well as at runtime (once the pane has been created).
• closeFunction: this function is called before the control's underlying pane has been destroyed and is akin to the "Close" event in REALbasic. Called at design time (immediately before the "destructorFunction" ) as well as at runtime (just before the pane is destroyed).
• backgroundIdleFunction: this callback is called at periodic intervals as a way for a plugin control to update itself. For instance, a progress wheel indicator could use this event in place of a custom timer as a way to update its view. Called only at runtime.
• drawOffscreenFunction: called as a way to draw the control into an offscreen buffer, such as a call to RectControl.DrawInto would require. Called at design time as well as at runtime. Note that the IDE prefers this callback over the "redrawFunction" when displaying your control in the IDE.
• setSpecialBackground: this callback is called when the runtime needs to determine whether a control has a special background to allow the control the chance to draw it. Called only at runtime, and only affects the Mac and Linux.
• constantChanging: deprecated and should be set to NULL
• droppedNewInstance: deprecated and should be set to NULL
• mouseEnterFunction: this function is called when the mouse enters the control area. Called only at runtime.
• mouseExitFunction: this function is called when the mouse leaves the control area. Called only at runtime.
• mouseMoveFunction: this function is called when the mouse moves within the control's area. Called only at runtime.
• stateChangedFunction: called when the control's state has changed. This callback is passed a bitmask of information describing the change. Called only at runtime. Possible bitmask values are:
  • kActivationChanged -- the control has been activated or deactivated
  • kEnabledChanged -- the control has been enabled or disabled
  • kVisibilityChanged -- the control has been shown or hidden
  • kBoundsChanged -- the control has been moved or resized
• actionEventFunction: an "action" has occurred that the control should be aware of. For instance, a button has been clicked, or a popup menu's selection has changed. This event is generally only fired for a plugin when a 'RCtl' Carbon event has fired, and so only affects the Mac.
• controlHandleGetter: used to get the OS control handle for the plugin control, and is akin to the "Handle as Integer" property on REALbasic controls and windows. Called at design time as well as runtime.
• mouseWheelFunction: called when the mouse wheel has been scrolled. Called only at runtime.
• enableMenuItemsFunction: called to allow a plugin to enable or disable menu items the plugin controls. This callback is only called when the plugin control has focus, or is a parent of a control which has focus. Called only at runtime.
• menuItemActionFunction: allows a plugin to handle menu actions. This callback is only called when the plugin control has focus, or is a parent of a control which has focus. Called only at runtime.
• controlAcceptFocus: This callback is called whenever the framework wishes to know whether your control can accept focus or not. If you have the REALcontrolAcceptFocus flag specified in the control definition, then this method is never called since it is assumed the control can always accept focus. Called only at runtime.
• keyUpFunction: called when the user has released a key while the control has focus. Called only at runtime.