Plugin SDK Dynamic Access Reference

From Real Software Documentation

Contents 1 REALnewInstanceWithClass 2 REALGetClassRef 3 REALLoadFrameworkMethod 4 REALLoadObjectMethod 5 REALGetPropValue@Type@ 6 REALSetPropValue@Type@ 7 REALGetEventInstance

REALnewInstanceWithClass

This function creates a new instance from the given class reference. This is akin to using the "new" operator in REALbasic. Space for the object is allocated, and the object's initializer and constructor are called before this function returns the object. Note that when you use REALnewInstanceWithClass, you must call REALGetClassRef from within your PluginEntry to let the REALbasic compiler know the plugin has a class reliance. Also note that the non-"flat C" version of the plugins SDK redefines this method as REALnewInstance. You should cache all of the required class references for making new instances from the PluginEntry method. By doing this, the compiler will know what dependencies to include for the plugin, and object creation will be faster.

REALobject REALnewInstanceWithClass( REALclassRef classRef );

• classRef: a reference to the class, retrieved from REALGetClassRef

Return Value a new instance of the specified class, or NULL if the class cannot be located. Note that if this function returns null unexpectedly, it is most likely because you forgot to call REALGetClassRef from the PluginEntry to register the dependency.

REALGetClassRef

Retrieves a class reference object from the given class name. This reference can then be used in a subsequent call to REALnewInstanceWithClass as a way to create a new instance of the class. This function is also used to register class dependencies with the compiler. This is required so that the compiler's dead-stripper does not accidentally strip out required classes from the user's executable.

REALclassRef REALGetClassRef(const char *className);

• className: the name of the class to retrieve. This parameter must be an ANSI string (not Unicode).

Return Value an opaque pointer to a class reference. Note that you should not make any assumptions about the data contained within this opaque structure.

REALLoadFrameworkMethod

Loads a global method from the REALbasic framework. Note that this function can only be used to load global methods from REALbasic itself. It cannot be used to load arbirary global functions in the user's project or global methods from another plugin. Also note that you should always check for NULL before attempting to call the returned function.

void *REALLoadFrameworkMethod( const char *prototype );

• prototype: the prototype for the REALbasic global method to load. The prototype must be a legal REALbasic prototype. Parameter names are ignored when considering matching prototypes. All other *modifiers (such as ByVal, Optional, etc) are important, and will influence prototype matching.

Return Value a function pointer for the loaded method. For more information about converting REALbasic type definitions to plugin types, see the REALbasic Types To Plugin Types section.

REALLoadObjectMethod

Loads an object method from the given object. Note that you should always check for NULL before attempting to call the returned function. Also note that the first parameter to the returned function will always be a REALobject (for the implicit "me" parameter). This function can explicitly load a method from the superclass (instead of the most derived class) by specifying "Super" in the prototype, like: "Super.Connect()" instead of "Connect()". This function cannot currently be used to load shared methods, nor can it return functions which rely on non-intrinsic REALbasic classes (read: user-created objects). It also cannot load methods which contain multi-dimensional arrays.

void *REALLoadObjectMethod(REALobject object, const char *prototype);

• object: the REALbasic object from which to load the method. This parameter cannot be NULL.
• prototype: The prototype for the REALbasic object method to load. The prototype must be a legal REALbasic prototype. Parameter names are ignored when considering matching prototypes. All other modifiers (such as ByVal, Optional, etc) are important, and will influence prototype matching.

Return Value a function pointer for the loaded method. For more information about converting REALbasic type definitions to plugin types, see the REALbasic Types To Plugin Types section.

REALGetPropValue@Type@

This function retrieves a property value from the given object. There is one version of REALGetPropValue for each of the following REALbasic datatypes: Int64, Int32, Int16, Int8, UInt64, UInt32, UInt16, UInt8, Single, Double, Object and String. If the property is a color, then you should use the Int32 version of this API. If the property holds a currency value, then you should use the Int64 version of this API. If the property holds a Boolean value, then you should use the Int8 version of this API. The "flat C" version of the plugins SDK has one function for each datatype to get the property value. However, unless you need to use the "flat C" version of the SDK, you can simply use the REALGetPropValue macro instead of differentiating based on type. This function will also attempt to load a value from a getter method, or from a variant. If the object is a variant, you can get the value by using the variant getter methods as the property name. Also, you can query for the variant's type by passing "Type" as the property name.

As of REALbasic 2008r1, there are now versions of this API for the following REALbasic datatypes: Ptr, CString, WString, PString, and CFStringRef.

Boolean REALGetPropValue@Type@(REALobject object, const char *propName, @Type@ *value);

• object: the object from which to retrieve the property value. This parameter cannot be NULL.
• propName: the name of the property to retrieve from the object. Note that this can be a "special" name such as "Type" for a variant object. It will also to retrive a property value from a computed property's getter method.
• value: a pointer of the appropriate type where the value is stored.

Return Value true if the property was retrieved, or false if the property could not be located.

REALSetPropValue@Type@

This function assigns a value to a property in the given object. There is one version of REALSetPropValue for each of the following REALbasic datatypes: Int64, Int32, Int16, Int8, UInt64, UInt32, UInt16, UInt8, Single, Double, Object and String. If the property is a color, then you should use the Int32 version of this API. If the property holds a currency value, then you should use the Int64 version of this API. If the property holds a Boolean value, then you should use the Int8 version of this API. The "flat C" version of the plugins SDK has one function for each datatype to get the property value. However, unless you need to use the "flat C" version of the SDK, you can simply use the REALSetPropValue macro instead of differentiating based on type. This function will also attempt to assign a value into a setter method, or from a variant. If the object is a variant, you can set the value by using the variant setter methods as the property name.

As of REALbasic 2008r1, there are now versions of this API for the following REALbasic datatypes: Ptr, CString, WString, PString, and CFStringRef.

Boolean REALSetPropValue@Type@(REALobject object, const char *propName, @Type@ value);

• object: the object to assign the property value into. This parameter cannot be NULL.
• propName: the name of the property to set. Note that this can be a "special" name such as "IntegerValue" for a variant object. It will also to assign a property value into a computed property's setter method.
• value: the value to assign into the object

Return Value true if the property was assigned, or false if the property could not be located.

REALGetEventInstance

Retrieves a function pointer to an event implementation from a class or control. A plugin class exposes a REALevent to the user, who then implements it. The author uses this function as a way to get the implementation from the event declaration. Note, while the first parameter to this function is a REALcontrolInstance, it can also be used to load event instances from a non-control object as well. In that case, pass in the REALobject you wish to load the event instance from, and typecast it as a REALcontrolInstance. Also note that the first parameter to an event instance is always the control or object instance (implicit "me" parameter).

void *REALGetEventInstance(REALcontrolInstance instance, REALevent *event);

• instance: the object to load the event implementation from
• event: the event to load from the object

Return Value a function pointer for the loaded event instance. For more information about converting REALbasic type definitions to plugin types, see the REALbasic Types To Plugin Types section. This function will return NULL if the user has not implemented the given event, so be certain to check for NULL before calling the event instance.