Synergy Logo
Synergy Solutions
Navigation Bar

MagicText Plugin Development Homepage

MagicText Home Page | Email Questions to: magictext@synsolutions.com | Send Comments Via Web


MagicText Plugin Installation MagicText Plugin SDK

Want to make your own way-cool plugins for MagicText? If you know C and have a Palm OS development kit, it's easy! The SDK contains Codewarrior R/4 and R/5 template projects, sample plugin source code, and complete instructions. A plugin can be as little as 20 lines of code, so it's really easier than you think to make one.

Download the MagicText Plugin SDK now!

Plugin Ideas:


MagicText Plugin Documentation

How to write a Plugin for MagicText Hack.
© 1998-1999 Synergy Solutions, Inc. All Rights Reserved.

PREFACE:
This explanation assumes that you are familiar with PalmOS programming. The
COMPILING and LINKING section is based on CodeWarrior for Mac or PC; however, I
have tried to make the explanation broad enough to be useful for users of other
tools such as GCC. I see no reason why plugins couldn't be created with
these tools.

INTRODUCTION:
MagicText Hack is a HackMaster extension that adds several text editing features to
PalmOS text fields such as multi-tap and drag-and-drop.  Since I'm already
hacking fields, I thought it would be cool to add a system-wide contextual menu
system. So I did! The result was MagicText, the companion application to
MagicText Hack that allows configuration of the contextual menus.  Even cooler, the
contextual menu system is plugin driven. So, any joe with a cool idea can add a
system-wide contextual menu function to their Palm system.  The interface between
MagicText Hack and MagicText is simple; when MagicText Hack senses that the user has
'invoked' the contextual menu, it launches MagicText with a specific launch code
and a parameter block of information about the 'context' of the device at the
time. This 'context' includes if there is an active field, if there is a
selection, etc.  The structure of this 'context' is defined as
PluginContextParamsType. In order for MagicText to actually provide a CONTEXTUAL
menu, it must ask each plugin whether it is available in the current context. So
MagicText, which knows about all installed plugins, calls each plugin with the
pluginCmdInContextQuery command and passes in the parameter block received from
MagicText Hack. The plugin gets the opportunity to relay to MagicText whether or
not it is available under the given conditions. MagicText then creates a list of
all 'in context' plugins and displays the list to the user. On choosing an item,
MagicText then calls the plugin with the parameter block and the pluginCmdNormal
code. Voila! That's it.

OTHER FEATURES:
MagicText allows the user to configure plugins, should that be an option for your
plugin. If you want users to be able to configure settings for your plugin, then
your plugin should also handle the pluginCmdConfigure launch code. No
ContextParams are passed to the plugin during the configuration call.

There is also a pluginCmdDeleting launch code which allows your plugin to do any
cleanup it may need to do should the user choose to delete it.

USING RESOURCES:
Resources which are part of the API:
There are no required resources for this API. One of the optional features of the
CMM manager is support for a small 10x10 icon to be drawn in the Contextual Menu
list. To add an icon to your plugin, simply create a bitmap of size 10x10 and
give it an ID of 27000.

The plugin API also supports a help/about string for your plugin. If you want to
supply one, create it as a string resource ('tSTR') with ID 27000.

Although your plugin will work without the above resources, we highly recommend
using both of these in your plugin to make it more professional and user-friendly.

Additional resources used by your plugin:
Your plugin is allowed to use resources. MagicText's Plugin API automatically
opens your plugin's DB before it is called, so you can use resources as you
normally would in an app. This system also prevents hairy UI resource ID problems
caused by duplicate IDs. For completeness however, you should make all of your
resource ID's in the range assigned to plugins by this API, which is 27000-32767.
MagicText is able to prevent UI conflicts only if you keep all of your resource
IDs above 27000. Please make sure all of your resources have ID's in this range.

CODING:
There is only one entry point for this API. This is the prototype:

typedef Err PluginEntryPointType (Word cmd, PluginContextParamsType* contextP);

Its implementation is similar to that of PilotMain(). At a minimum you must
respond to the pluginCmdNormal and pluginCmdInContextQuery commands. The other
launch codes are optional. Make sure to return errNoError for all launch commands
that you don't handle. Below is a listing of all currently implemented plugin
launch commands:

Command							Params Type					What you should do...			What you should return
-------------------------------------------------------------------------------------------------------------------------
pluginCmdNormal					PluginContextParamsType		Do your plugin stuff!			nothing/errNoError
pluginCmdInContextQuery			PluginContextParamsType		Check the params to see			IN_CONTEXT or NOT_IN_CONTEXT
															if your plugin should be
															available
pluginCmdConfigure				none						Run config options (optional)	nothing/errNoError
pluginCmdDeleting				none						Your DB is about to be			nothing/errNoError
															deleted... cleanup (optional)


You cannot use globals in the same way as you would in a Palm OS application.
Ideally, don't use globals. However, if you do need globals, storing a pointer to
them in a Feature (as is often done for HackMaster hacks) works fine.

COMPILING & LINKING:
I have included in this SDK sample CodeWarrior R/5 and R/4 projects. They are a
great starting point.

A MagicText/CMM (contextual menu manager) plugin is simply a Palm OS code
resource. To actually get this into a PRC to install on the device, it takes 2
projects. One project (MagicText CODE Resource) compiles the code for your plugin
into a PalmOS CODE resource of type 'pCOD' and id '1000'. This project is a
subproject of the 'wrapper' project which compiles the PRC (MagicText Plugin
PRC).  The PRC should have type 'PLUG' and creator 'SSta', which is the creator
code of MagicText.

The name as it appears in the MagicText contextual menu is the name of the Plugin
Database. Optionally, you should add the creator code of the app to the end of the
name, and it will be removed. That is, a plugin whose DB name is 'PasteSSta' will
appear as 'Paste' in the menu. This is a Palm-encouraged practice to help
eliminate name conflicts.

INSTALLATION:
Once your plugin is built, simple install the DB onto the Palm unit, run
MagicText, and press the 'Search' button if your plugin doesn't appear in the
list.

As with our other plugin systems, we will be keeping a repository on the web. If
you have a very cool plugin and want us to bundle it with the MagicText
application, please let me know. There may be money involved in it for you!

If you have any questions or comments about this system, please direct them to
Alan Pinstein, alan@synsolutions.com, 
or call me at 1-800-210-5293.

Happy coding!

Alan Pinstein
Synergy Solutions, Inc.

HOME | ORDER | SOFTWARE | CASES | SUPPORT | CONTACT | LINKS | ABOUT US | PRIVACY POLICY

© 1997-2001 Synergy Solutions, Inc. All rights reserved.

comments to: webmaster@synsolutions.com