home *** CD-ROM | disk | FTP | other *** search
/ Software of the Month Club 1999 November / SOTMC_Nov1999-Ultimate.iso / mac / REALbasic ƒ / Plugins / Plugins SDK / plugin documentation < prev    next >
Encoding:
Text File  |  1998-05-28  |  7.1 KB  |  198 lines  |  [TEXT/R*ch]
  1. Writing REALbasic plugins
  2. =========================
  3.  
  4. REALbasic plugins are code resources that extend the features available to a REALbasic user.
  5.  
  6. The things that can be written with plugins are:
  7. * functions
  8. * controls
  9.  
  10. Plugin file details
  11. ===================
  12.  
  13. A plugin file has the Creator type of: 'SfTg' and a file type of 'RBPl' - there is an icon associated with this by REALbasic - if you upgraded from a previous version, you may need to rebuild your desktop.
  14.  
  15. As for the resources themselves, a 68k plugin has the resource type of 'PL68', and a PPC plugin has the resource type of 'PLPC'. Unless the plugin has strict computational requirements, it's better to just write a 68k plugin - a PPC program will still be able to access it.
  16.  
  17. The first plugin resource in a file must have id 128, the second plugin 129, etc.
  18.  
  19. Plugin file requirements
  20. ========================
  21.  
  22. All plugins must have a routine called 'PluginEntry' - this routine should notify REALbasic about all of the features that the plugin provides.
  23.  
  24. A simple PluginEntry routine might be something like:
  25.  
  26. void PluginEntry(void)
  27. {
  28.     REALRegisterMethod(&add5defn);
  29. }
  30.  
  31. This plugin has defined a single method, and it calls the REALRegisterMethod function to define it.
  32.  
  33. The currently supported registration routines are:
  34. REALRegisterControl - for registering new controls
  35. REALRegisterMethod - for registering new methods
  36.  
  37. A plugin also needs to declare the pluginExports table, which lists all of the routines that are exported from the plugin - this includes both methods, as well as callbacks defined for controls.
  38.  
  39. An example pluginExports table is:
  40.  
  41. REALexport pluginExports[] = {
  42.     { nil, add5func},
  43. };
  44.  
  45. short pluginExportCode = sizeof(pluginExports) / sizeof(REALexport);
  46.  
  47. An entry in the pluginExports table consists of:
  48. * the entry name - just leave this field nil
  49. * the reference to the function that implements the export
  50.  
  51. eg
  52. static int add5func(int v)
  53. {
  54.     return v + 5;
  55. }
  56.  
  57. Declaring new methods
  58. =====================
  59.  
  60. The REALRegisterMethod function passes a reference to a REALmethodDefinition structure.
  61.  
  62. eg
  63. REALmethodDefinition add5defn = {
  64.     0,
  65.     "add5(v as integer) as integer"
  66. };
  67.  
  68. The number (in this case 0) is the index in the pluginExports table for the implementation, and the string gives the interface of the method that is used by REALbasic.
  69.  
  70. Declaring controls
  71. ==================
  72.  
  73. The REALRegisterControl function passes a reference to a REALcontrol structure.
  74.  
  75. eg
  76. REALcontrol boxControl = {
  77.     kCurrentREALControlVersion,
  78.     "box",
  79.     sizeof(boxData),
  80.     REALcontrolAcceptFocus | REALcontrolFocusRing,
  81.     169,
  82.     170,
  83.     boxProperties,
  84.     sizeof(boxProperties) / sizeof(REALproperty),
  85.     boxMethods,
  86.     sizeof(boxMethods) / sizeof(REALmethodDefinition),
  87.     boxEvents,
  88.     sizeof(boxEvents) / sizeof(REALevent),
  89.     &boxBehaviour
  90. };
  91.  
  92. The fields of the REALcontrol structure are as follows:
  93. * version - the version of the plugin architecture that the control was built under - just pass the constant kCurrentREALControlVersion
  94. * name - the name of the control as used in REALbasic
  95. * dataSize - the size of the auxiliary data structure allocated for the control
  96. * flags - any special control flags. In the given example, the control indicates that it accepts focus, and it wants REALbasic to automatically draw a focus ring when it has the focus.
  97. * toolbarPICT - the resource id of a PICT resource of the toolbar icon for the control
  98. * toolbarDownPICT - the resource id of a PICT resource of the depressed version of the toolbar icon
  99. * properties - a reference to the array of property declarations for the control
  100. * propertyCount - the number of properties for the control
  101. * methods - a reference to the array of method declarations for the control
  102. * methodCount - the number of method declarations for the control
  103. * events - a reference to the array of event declarations for the control
  104. * eventCount - the number of event declarations for the control
  105. * behaviour - a reference to the control behaviour table
  106.  
  107. Declaring properties
  108. --------------------
  109.  
  110. REALproperty boxProperties[] = {
  111.     "Appearance", "BackColor", "Color", REALpropInvalidate, FieldOffset(boxData, fillColor)
  112. };
  113.  
  114. A REALproperty has the following fields:
  115. group - the name of the property group that the property should be displayed in
  116. name - the name of the property
  117. type - the name of the type of the property
  118. flags - any special property flags
  119. propertyOffset - the offset of the property in the auxiliary structure for the form
  120.  
  121. (Please note that properties are only data-driven in the current version - code-driven properties should be available in the next version)
  122.  
  123. Declaring methods
  124. -----------------
  125.  
  126. REALmethodDefinition boxMethods[] = {
  127.     { 6, "makered" },
  128.     { 7, "colorComponent(v as integer) as integer" },
  129. };
  130.  
  131. Control methods are declared exactly the same as declaring new global methods.
  132.  
  133. Declaring events
  134. ----------------
  135.  
  136. REALevent boxEvents[] = {
  137.     { "Action" }
  138. };
  139.  
  140. A REALevent structure merely has the declaration for the event, which is in the same form as a method declaration.
  141.  
  142. Control behaviour
  143. -----------------
  144.  
  145. REALcontrolBehaviour boxBehaviour = {
  146.     nil,
  147.     nil,
  148.     &pluginExports[2],
  149.     &pluginExports[3],
  150.     &pluginExports[4],
  151.     &pluginExports[5],
  152.     nil,
  153.     nil,
  154.     nil
  155. };
  156.  
  157. The REALcontrolBehaviour structure references the REALexport entry points that define the behaviour for the control.
  158.  
  159. The entry points are:
  160. initFunction - called when the control is initialized:
  161.     void initFunction(REALcontrolInstance)
  162. disposeFunction - called when the control is disposed:
  163.     void disposeFunction(REALcontrolInstance)
  164. redrawFunction - called when the control needs to be redrawn:
  165.     void redrawFunction(REALcontrolInstance)
  166. clickFunction - called when the control is clicked on:
  167.     Boolean clickFunction(REALcontrolInstance, int x, int y, int modifiers)
  168. mouseDragFunction - called while the mouse is held down after clickFunction returned true:
  169.     void mouseDragFunction(REALcontrolInstance, int x, int y)
  170. mouseUpFunction - called when mouse is released after clickFunction returned true:
  171.     void mouseUpFunction(REALcontrolInstance, int x, int y)
  172. gainedFocusFunction - called when the control gains the focus
  173.     void gainedFocusFunction(REALcontrolInstance)
  174. lostFocusFunction - called when the control loses the focus
  175.     void lostFocusFunction(REALcontrolInstance)
  176. keyDownFunction - called when the user presses a key while the control has the focus:
  177.     Boolean keyDownFunction(REALcontrolInstance, int charCode, int keyCode, int modifiers)
  178.  
  179. Incorporating resources
  180. -----------------------
  181.  
  182. A plugin file can specify additional resources to be incorporated into the built application via a PLRm resource.
  183.  
  184. A PLRm resource is just a list of resource type and id pairs - these resources will be incorporated into any built applications that utilise the plugin.
  185.  
  186. The PLRm resource must have the same id as the associated plugin (usually 128), and a ResEdit TMPL resource for the PLRm resource can be found in the GetFolder.rsrc file (also the REALbasic application itself).
  187.  
  188.  
  189. Version History
  190. r35a
  191. - added faceless control flag REALinvisibleControl
  192. - add more examples
  193. - added REALSelectGraphics
  194. - added REALFolderItemFromFSSpec
  195. - improved performance
  196. - removed requirement to use Mixed Mode Manager to handle events
  197. - added ability in incorporate additional resources
  198.