REALbasic Plugin
Volume Number: 15
Issue Number: 10
Column Tag: Programming
REALbasic Plug-in Programming
by Erick J. Tejkowski
Extend REALbasic to suit your needs
REALbasic is an object-oriented, Basic-flavored, rapid application development
environment. With it you can build and compile Macintosh and Windows applications.
The environment comes complete with numerous classes, objects, properties, and
methods for the programmer to use. Many different aspects of Mac/PC programming
are included in the REALbasic environment, for example windows, QuickTime, sockets,
and threads to name a few. Sometimes, however, your application requires something
that REALbasic cannot provide. To gain this functionality, the programmer has to tap
other resources. For example, REALbasic allows the inclusion of Applescripts,
Hypercard XCMDs, and shared libraries. Furthermore, REALbasic can also be expanded
with the use of native plugins. In this article, we will examine the methods used in
developing plugins for REALbasic using Metrowerks CodeWarrior.
To begin, we will prepare the compiler for REALbasic plugins. Then, we are on to
coding. In the first code example, we will examine some sample code for a
method-based plugin. The second example will look at code for a basic custom control.
Finally, we will wrap it up by including some discussion on the potential uses of
REALbasic plugins.
The Setup
A REALbasic plugin is a code resource. It can come in 68K or PPC flavors, but unless
your plugin requires some specific speed enhancements or other PPC specific code,
most people prefer to make 68K versions, as this allows everyone to take advantage of
the plugin. There are also some specific differences between REALbasic 1 and 2
versions of plugins. For this article, we will only consider REALbasic 2 plugins, as it
is the most current release, but most of the information will pertain to REALbasic 1
plugin development, although there are some distinct differences. Interestingly, some
REALbasic 1 plugins work with REALbasic 2, but never vice versa.
Since the plugin is a code resource, CodeWarrior needs some special adjustments
before we can begin work on our first REALbasic plugin. To begin, create a folder
named MyRBPlugin. To this folder add the file named PluginMain.cpp and the folder
entitled Includes. These can be found in the REALbasic plugin SDK on REALsoftware's
web site. See the Bibliography for more information. Next, launch CodeWarrior and
create a new project with the MacOS:C_C++:MacOSToolbox:68K stationery. Uncheck
the Create Folder check box. Name the project MyPlug.pi (option-p) and put it in your
MyRBPlugin folder. Remove the SillyBalls.c, and SillyBalls.rsrc files.
Select New from the File menu and create a new document. Save it in your MyRBPlugin
folder with the name MySource.cpp. Select Add Window from the Project menu, which
will add MySource.cpp to your project. Select Add Files... from the Project menu and
add the PluginMain.cpp file you copied to your folder earlier. Your project should
resemble Figure 1.
Figure 1.MyPlug.pi project window..
Your project target might not look exactly the same as Figure 1. Your target might be
named Mac OS Toolbox DEBUG 68K instead of plugin68k. To change this, you need to
make some changes to the preference settings. It just so happens that this is also where
code resource settings are made. This leads us to our next step.
Open the Project Settings dialog from the Edit menu. Select the Target Settings in the
Target submenu. Change the Target Name to plugin68k. Next, select the Access Paths
item. Select User Paths and click the Add button. Choose the folder entitled Includes
that you copied to your project folder earlier. Now, select 68K Target and name your
plugin. Name it myPlugin68K. Make sure that Code Resource is selected from the
Project popup menu. Change the Creator to SfTg, the Type to RBPl, the ResType to
PL68, and the ResID to 128. Figure 2 recaps the 68K Target settings.
Figure 2.68K Target Settings.
Finally, in the 68K Processor settings, check the following checkboxes: 68020
Codegen, MPW C Calling Conventions, 4-Byte Ints, and 8-Byte Doubles. Click the Save
button and relink the project if necessary.
Additional Resources
These settings will work for both code examples to be discussed later. To build the
custom control in Listing 2, though, one more step is required. A control in REALbasic
also needs some additional resources. Start your favorite resource editor and create a
new file named MyRsrc.rsrc. To this file, add a 'PICT' resource with an ID of 128. This
is the unselected appearance of the control on the REALbasic toolbar. A 'PICT' resource
with an ID of 129 is the selected appearance of the control (i.e. the appearance as the
control is dragged to a window). Both of these resources should have pixel dimensions
of 28 wide by 24 high to appear properly in the REALbasic toolbar. In addition to the
required 'PICT' resources, our control is going to make use of some icon resources.
These icon resources will be used to draw the custom switch we are going to create.
Add a resource of type 'icl8' with a high number, to avoid collisions with REALbasic's
own resources. For our example use 1280. This is the appearance of the switch when
used in a REALbasic application. Draw whatever you would like here or use the
resource example available on the MacTech web site. This resource will be the "off
position. Since we are using an icon here, the dimensions are 32 wide by 32 high. Once
you have completed the artwork for your switch, drag the 'icl8' to the 'ICN#' and
'icl4' boxes on the right. You need not worry about the other sizes, as they are not
important for this example. Since we are building a toggle style switch as our custom
control, you will also need to add another icon resource. This resource will be the "on
position. Create it just as you created the "off" position, but give it a number of 1290.
An example resource file might look something like Figure 3.
Figure 3.An Example Switch and Its Associated Icons.
In addition to the icon resources, REALbasic plugins require you to indicate which
user-defined resources will be used in the control. To do this, you must create a
'PLRm' resource, which lists all of the accessory resources you will use. To enter the
data for 'PLRm' resources, you must first make a copy of the necessary 'TMPL'
resource. The template resource can be found in the REALbasic plugin SDK or by
opening a copy of REALbasic itself. Once this 'TMPL' resource has been added to your
file, you can proceed to add the necessary 'PLRm' resources. When creating PLRm
resources, the first entry is the four-letter signature for the particular resource you
are adding. The second entry is the resource number you will be using. More info on
this topic is also available in the SDK. Figure 4 shows what the 'PLRm' resource looks
like for our project.
Figure 4.The ‘PLRm’ resource.
Once you have added these extra resources, save the file. We will come back to it later
in the article when we build the custom control. Your plugin environment is now set.
On to programming!
Source Code
Our first example is going to perform three functions. It will convert an integer to
Roman numerals and vice versa as well as convert an integer to an ordinal number.
MySource.cpp begins with a few #includes necessary for our plugin and functions
called within our plugin. You will also notice some structs, which will be used later in
the code.
#include "rb_plugin.h
#include
#include
#include
//for Roman numerals
struct numeral {
long val;
int ch;
};