Plug-in Developers Guide

• Plug-in Basics
• Writing a Plug-in
• The Plug-in API
• Plug-in Deployment

Welcome to the DreamFactory Plug-In Developer's Guide. This guide discusses plug-in basics, how to write a new plug-in, the plug-in API, and plug-in deployment. This information is only of interest to C and C++ programmers wishing to fundamentally extend DreamFactory's object format. Most developers will not need this information, and can write anything they need with the 17 standard user interface objects DreamFactory Software provides.

Throughout this document you will see sections labeled as an "Important Note" in bold type. Read these sections carefully, they identify important issues for the DreamFactory author.

Plug-in Basics

DreamFactory supports the node hierarchy with system commands and functions. This is the shared functionality every node has in common. For example, the system command nodevisibleset() will hide or show any node in the project. Every node is also associated at birth with a plug-in that provides unique functionality specific to that node. There are 16 standard plug-ins that implement common user interface objects and basic rich-media functionality:

This guide discusses the ability to write new, non-standard plug-ins that implement additional user interface capabilities or provide access to new data formats. Possible new plug-ins might be written for 3D objects, Adobe Acrobat display, a Flash Player, HTML rendering, or other special purpose capabilities.

The plug-ins are polymorphic DLLs (on Windows) or Code Fragments (on Macintosh) that reside in the "plugins" folder in the DreamFactory installation. DreamFactory plug-ins control how a node is drawn and behaves. The plug-in can be a container that clips all children and/or has a coordinate system. Plug-ins can also implement non-visual functionality, like a math library. Each plug-in exposes an unlimited number of new commands and functions to the scripting language; these routines become first-class additions to the DreamFactory language. Downloaded projects recognize when a plug-in they depend on is not available locally, and the plug-in library is silently updated with an additional download of the DLL or Code Fragment.

The diagram below shows the overall software architecture of the DreamFactory virtual machine. There are 1500 commands and functions available to the author, close to 1200 of these are implemented by the various standard plug-ins, and these are mainly for controlling the visual appearance of nodes at runtime.

The plug-ins themselves are written in "Pure C" and call upon a large set of library routines implemented by DreamFactory. The next section deals with the commands and functions that DreamFactory calls in the body of the plug-in to draw the node, hit test the node, and implement the various scripting commands and functions that the node exposes. The section after that deals with the "callbacks" from the plug-in back into DreamFactory. This allows the nodes to be drawn together on the same page, manage project media data together, share system memory jointly, and implement other common functionality.

Back to top

Writing a Plug-in

This section documents the files in the example plug-ins and discusses the standard functions that are called by the DreamFactory virtual machine. There are two examples. The first is a basic "hello world" plug-in that is as simple as possible; the second is the "list" plug-in from the standard library. The discussion below deals mainly with the "hello world" plug-in, the "list" plug-in is provided as a more complex example.

In each plug-in there is a "src" folder with the source files, an "inc" folder with include files, a "mac" folder with the Code Warrior Project for Macintosh, a "win" folder with the Visual Studio 6.0 Project for Microsoft Windows, and a "shared" folder with additional source and include files. Here are the included source and header files:

There is also a "shared" folder. These files are shared between all plug-ins and DreamFactory itself. Don't change files in the shared folder, they are provided as standard interfaces for writing any plug-in.

The most important file for a new plug-in is the "main.c" file. This hold the entry points for DreamFactory to call the plug-in. These functions are passed to the Virtual Machine in an array when the plug-in is first opened. The functions handle opening, closing, drawing, hit testing, scripting, copy, paste, and the general management of the plug-in's data. The entry points must be implemented in the manner shown; we recommend modifying the example file. Here are the entry points discussed in order:

static ptr retname(void);
static long retversion(void);

These functions return the plug-in name and version. Be sure to change the name of the plug-in from "list" or "hello" to something unique. The version should be 0x00010000 for 1.0, or for example 0x00010005 for version 1.5, etc. The version number should be increased when the plug-in is changed, this will trigger a download by any project that uses the latest version.

static ptr errstring(portptr, short);
static ptr paramnote(portptr, long, short);
static void listroutines(codetablptr *, long *);

The errstring() routine will return a plug-in error string given an error code. This is to give users a special error in the error dialog. The errors are defined in the file "main.h." The paramnote() function will return a pointer to a special message bar string for scripting. For example, the draw.styleset() draw plug-in command will list available draw styles as you type. The listroutines() message returns a pointer to the "codetabl" structure that documents all of your scripting additions for this plug-in. These codes are maintained in the "main.h" file. You should only ADD codes to this list for backwards compatibility with projects that have used this plug-in. The scripts in the projects reference these codes by ID Number and those references are persistent. The ID Numbers are stored in "main.h." The first item in this table is the ID Number for the command or function, the second item is false/true if this is a command/function, the next item is the short name of the command/function, and the last item is the full description. Please observe DreamFactory's description syntax in the last item for consistency.

static plugptr openplug(portptr);
static void closeplug(portptr, plugptr);

These routines are called when the plug-in instance is created. You should allocate a pointer and store information in the structure on openplug(), the pointer should be de-allocated on closeplug(). This information will be passed in the plugptr parameter for other functions. Define the plugptr in the decl.h header.

static projptr openproj(portptr, plugptr);
static void closeproj(portptr, plugptr, projptr);

These routines are called when the project instance is created. You should allocate a pointer and store information in the structure on openproj(), the pointer should be de-allocated on closeproj(). This information will be passed in the projptr parameter for other functions. Define the projptr in the decl.h header.

static nodeptr opennode(portptr, plugptr, projptr, pathptr, long);
static void closenode(portptr, plugptr, projptr, nodeptr, pathptr, long);

These routines are called when the node instance is created. You should allocate a pointer and store information in the structure on opennode(), the pointer should be de-allocated on closenode(). This information will be passed in the nodeptr parameter for other functions. Define the nodeptr in the decl.h header.

static void shownode(portptr, plugptr, projptr, nodeptr, pathptr, long);
static void hidenode(portptr, plugptr, projptr, nodeptr, pathptr, long);

These routines are called when the node instance is hidden or shown. You should take care of any special actions that need to be accomplished when this happens.

static void destroydata(portptr, plugptr, projptr, pathptr, long);
static long createdata(portptr, plugptr, projptr, pathptr, rect *);
static ftabptr declarefont(portptr, plugptr, projptr, pathptr, long);
static void sizedata(portptr, plugptr, projptr, pathptr, long, long *);
static long copydata(portptr, plugptr, projptr, nodeptr, pathptr, long, pathptr);

The destroydata() routine is called when the node instance is about to be destroyed. You should take care of any special actions that need to be accomplished when this happens. The createdata() function is called when a node is created, you must create a virtual object and return the ID Number in the return parameter. Some nodes will create multiple objects, the first object must hold the sub-object-IDs. There is a full description of virtual objects below in the plug-in API section. The declarefont() function returns a simple structure with all of the fonts used by the node. This allows DreamFactory to copy referenced fonts in cut-copy-paste operations. The sizedata() function returns the total size of the node. The copydata() function copies data from one node to another using the virtual object functions.

static short callroutine(portptr, plugptr, projptr, passptr, long);

The callroutine() function is used to call all of the scripted routines for this plug-in. Some are functions and some are commands. Use the argument fetchers (discussed in the API section) to retrieve and type-convert the arguments. Results are returned in the passptr as well. Plug-in scripted commands and functions often reference the plug-in data for that node. By convention, the node reference will be a string in the first argument. The API command gluegetnodedataid() will return the virtual object ID to the referenced node. Plug-ins cannot reference nodes that were not created by that plug-in. This function calls more detailed scripted language handlers in the "work.c" file in the example plug-ins provided.

static void drawdata(portptr, plugptr, projptr, nodeptr, pathptr, long, rect *);

The destroydata() function actually draws the plug-in. The last "rect" parameter holds the area that needs to be updated. All clipping is handled by the virtual machine, so probably all that is needed is to draw your plug-in according to the data and properties of the current node.

static short hitestdata(portptr, plugptr, projptr, nodeptr, pathptr, long, point);

The hittestdata() function hit-tests the plug-in, and returns "true" if the given mouse is in the plug-in. This is a high-level hit test routine that simply returns true if there is any hit in the current node. More detailed hit testing is accomplished with other scripted commands. For example, most plug-ins implement a "hittest" function. In the "list" plug-in the "hittest" function returns the index number of the item that is being clicked in.

static void realizedata(portptr, plugptr, projptr, nodeptr, pathptr, long, rect *, rect *, rect *, point *);

The realizedata() function updates the various rectangles. The function should do nothing and return quickly if the node has not been changed. If there have been changes (say from scripting or automatic animation) then the function should calculate the new draw bounds rectangle, and if applicable, the new clip rectangle and node origin.

Back to top

The Plug-in API

This section documents the API functions that are calls from the plug-in back into DreamFactory. A major reason that the plug-ins themselves are small in size is the API does most of the work. These functions allow the typical DreamFactory plug-in to be written in "Pure C" and to be instantly portable as written to other platforms. The fact that the plug-ins are usually not linked with any library is also very helpful in keeping them small. This is also good for security because all of the DreamFactory callbacks are implemented inside the Project sandbox. Therefore a plug-in that has no external system calls and is not linked with any library is guaranteed to be sandbox safe.

All of the routines below begin with the "glue" key word. This is an easy way to identify all of the callbacks into DreamFactory. The "dfacptr", "plugptr", and "nodeptr" are pointers into the DreamFactory instance variables, the plug-in instance variables, and the node instance variables respectively. These are defined in the "decl.h" header. Some of the routines below use various other data structures. These are define in the "glue.h" header. All of these commands and functions are accessed from an array, like a COM object in Windows. The array layout is defined in "pass.h" but DreamFactory provides macros to call all of the various functions automatically. Future versions of DreamFactory will extend this API array of function, older functions will be left intact for backwards compatibility.

Memory

These functions implement all the familiar memory pointer and handle manipulations. Use the virtual object function gluehasmem() to test for space in the shared heap for large allocations. Allocating memory beyond this limit will result in a fatal error.

void gluesetptrsize(dfacptr thedfac, ptr *theptr, long size)
handle gluenewhandle(dfacptr thedfac, long size)
ptr gluenewptr(dfacptr thedfac, long size)
ptr gluelockhandle(dfacptr thedfac, handle thehand)
void glueunlockhandle(dfacptr thedfac, handle thehand)
void gluefatalerror(dfacptr thedfac, short err)
void gluesethandlesize(dfacptr thedfac, handle thehand, long size)
long gluegethandlesize(dfacptr thedfac, handle thehand)
void glueblockmove(ptr src, ptr dst, long size)
void gluedisposehandle(dfacptr thedfac, handle thehand)
void gluedisposeptr(dfacptr thedfac, ptr theptr)
void gluedfpath2native(dfacptr thedfac, char *dfpath, char *nativepath)
void gluenative2dfpath(dfacptr thedfac, char *dfpath, char *nativepath)
void gluehand2hand(dfacptr thedfac, handle *thehand)

short glueaddvir(dfacptr thedfac, pathptr thepath, long *theid, handle temphand, swapfn swapfx)
short gluehasmemvir(dfacptr thedfac, long size, short *hasit)
short gluegetvir(dfacptr thedfac, pathptr thepath, long theid, handle *thehand, swapfn swapfx)
short glueputvir(dfacptr thedfac, pathptr thepath, long theid)
short gluedeletevir(dfacptr thedfac, pathptr thepath, long theid)
short gluechangevir(dfacptr thedfac, pathptr thepath, long theid, short critical)
short gluegetleafdataid(dfacptr thedfac, char *thename, pathptr *myfile, long *theid, leefptr *theleaf)
short glueprojectislocked(pathptr thepath)
short gluesizevir(dfacptr thedfac, pathptr thepath, long theid, long *thesize)

Text Files

These functions implement all text file IO. Be aware that these functions (and all the API callbacks) operate in the sandbox for the current project.

short glueopentextfileraw(dfacptr thedfac, char *thename, short wantwrite)
short glueopentextfile(dfacptr thedfac, char *thepath, char *thename, short wantwrite)
long gluereadtextfile(dfacptr thedfac, handle *thestrings)
void glueclosetextfile(dfacptr thedfac)
short gluecreatetextfileraw(dfacptr thedfac, char *thepath)
short gluecreatetextfile(dfacptr thedfac, char *thepath, char *thename)
void gluewritetextfile(dfacptr thedfac, ptr theptr, long size)

Strings

These functions implement many common string manipulations. In general, pascal strings have a length of 256 unsigned characters. This is the maximum length for a pascal string, and the first length byte should be unsigned. Strings that are type char are zero terminated and have an arbitrary length. The maximum length for file names and path names and URL's is defined in the "glue.h" header. You must observe these lengths to prevent buffer overruns.

short gluecstrislong(char *thestring)
short gluecstrisdouble(char *thestring)
short gluepstrislong(unsigned char *thestring)
short gluepstrisdouble(unsigned char *thestring)
short gluecstrequalpstr(char *thesrc, unsigned char *thedst)
short gluecstr2big(dfacptr thedfac, char *thestring, big *thebig)
void gluebig2cstr(dfacptr thedfac, big thebig, char *thestring)
short gluecstr2pattern(dfacptr thedfac, char *thestring, unsigned char *thepat)
void gluepattern2cstr(dfacptr thedfac, unsigned char *thepat, char *thestring)
short gluecstr2rect(dfacptr thedfac, char *thestring, rect *therect)
void gluerect2cstr(dfacptr thedfac, rect *therect, char *thestring)
long gluecstrlen(char *thesrc)
void gluecstrcpy(char *thesrc, char *thedst)
void gluecstrcat(char *thesrc, char *thedst)
short gluecstrequal(char *thesrc, char *thedst)
short glueequalchars(char *thesrc, char *thedst, long size)
void gluepstrcpy(unsigned char *thesrc, unsigned char *thedst)
void gluepstrcat(unsigned char *thesrc, unsigned char *thedst)
short gluepstrequal(unsigned char *thesrc, unsigned char *thedst)
void gluecstr2pstr(char *thesrc, unsigned char *thedst)
void gluepstr2cstr(unsigned char *thesrc, char *thedst)
void gluecleanpstr(unsigned char *thestring, short maxsize)
void gluecleancstr(char *thestring, short maxsize)
long gluepstr2long(unsigned char *thestring)
float gluepstr2float(unsigned char *thestring)
void gluelong2pstr(long thelong, unsigned char *thestring)
void gluefloat2pstr(float thefloat, unsigned char *thestring, short decimalplaces)
long gluecstr2long(char *thestring)
float gluecstr2float(char *thestring)
void gluelong2cstr(long thelong, char *thestring)
void gluefloat2cstr(float thefloat, char *thestring, short decimalplaces)
long gluecstrhash(char *thestring)
long gluepstrhash(unsigned char *thestring)
double gluepstr2double(unsigned char *thestring)
void gluedouble2pstr(double thedouble, unsigned char *thestring, short decimalplaces)
double gluecstr2double(char *thestring)
void gluedouble2cstr(double thedouble, char *thestring, short decimalplaces)

short gluecreatedir(dfacptr thedfac, char *thepath)
short gluedeletedir(dfacptr thedfac, char *thepath)
short glueflushfile(dfacptr thedfac, filedataptr thefile)
short glueclosefile(dfacptr thedfac, filedataptr thefile)
short glueseekfile(dfacptr thedfac, filedataptr thefile, long offset)
short gluesetendofile(dfacptr thedfac, filedataptr thefile, long offset)
short gluerenamefile(dfacptr thedfac, char *oldname, char *newname)
short gluecopyfile(dfacptr thedfac, char *srcstring, char *dststring)
short gluefileistype(dfacptr thedfac, char *pathname, long thetype)
short glueopenfile(dfacptr thedfac, char *pathname, filedataptr thefile)
short gluegetendofile(dfacptr thedfac, filedataptr thefile, long *logeof)
short glueopenreadonly(dfacptr thedfac, char *pathname, filedataptr thefile)
short gluereadfile(dfacptr thedfac, filedataptr thefile, ptr pdata, unsigned long size)
short gluewritefile(dfacptr thedfac, filedataptr thefile, ptr pdata, unsigned long size)
short gluecreatefile(dfacptr thedfac, char *pathname, long type, long creator, filedataptr thefile)
short gluecreatetempfile(dfacptr thedfac, char *filename, long type, long creator, filedataptr thefile)
void gluevolumename(char *thepath, char *thevolume)
void gluefilename(char *thepath, char *thefile)
void gluepathname(char *fullpath, char *pathname)
short glueunlockfile(dfacptr thedfac, char *thepath)
short gluedeletefile(dfacptr thedfac, char *thepath)
short gluegetfirstfile(dfacptr thedfac, char *thepath)
short gluegetfileinfo(dfacptr thedfac, char *thepath, short *isopen, short *islocked)
short gluegetdiskfreespace(dfacptr thedfac, char *thepath, long *size)
short gluegetnextfile(dfacptr thedfac, char *thepath, short *isfolder)
short gluegetfile(dfacptr thedfac, char *thepath, char *thename, long thetype, short wantwrite)
short glueputfile(dfacptr thedfac, char *thepath, char *thename, long thetype)
short glueunzipfiles(dfacptr thedfac, char *zipfilename, char *destdirname)
short gluezipfiles(dfacptr thedfac, long totalfiles, char *filenames[], char *zipfilename)

Rectangles

These functions are simple rectangle manipulation utilities. The gluepointinline() function implements hit testing for lines.

void gluemaprect(rect *ans, rect *src, rect *dst)
void gluemappoint(point *ans, rect *src, rect *dst)
short gluepointinline(point start, point end, point test, short region)
void gluepoint2rect(point thepoint1, point thepoint2, rect *therect1)
void gluesetrect(rect *therect1, short top, short left, short bottom, short right)
void glueinsetrect(rect *therect1, short hor, short ver)
void glueoffsetrect(rect *therect1, short hor, short ver)
short glueequalrect(rect *therect1, rect *therect2)
short gluepointinrect(point thepoint, rect *therect)
short glueequalpoint(point thept1, point thept2)
short gluesectrect(rect *therect1, rect *therect2, rect *destrect)
void glueunionrect(rect *therect1, rect *therect2, rect *destrect)
short glueemptyrect(rect *therect1)

void gluedrawfont(dfacptr thedfac, fontptr thefont, long thesize, char *thestring, point thepoint, big thecolor)
void gluedrawfontcstr(dfacptr thedfac, fontptr thefont, char *thestring, point thepoint, big thecolor)
void gluedrawfontpstr(dfacptr thedfac, fontptr thefont, unsigned char *thestring, point thepoint, big thecolor)
void glueboxfont(dfacptr thedfac, fontptr thefont, long thesize, char *thestring, point thepoint, rect *thebounds)
void glueboxfontcstr(dfacptr thedfac, fontptr thefont, char *thestring, point thepoint, rect *thebounds)
void glueboxfontpstr(dfacptr thedfac, fontptr thefont, unsigned char *thestring, point thepoint, rect *thebounds)
long widthfont(dfacptr thedfac, fontptr thefont, long thesize, char *thestring)
long widthfontcstr(dfacptr thedfac, fontptr thefont, char *thestring)
long widthfontpstr(dfacptr thedfac, fontptr thefont, unsigned char *thestring)
fontptr gluegetfont(dfacptr thedfac, char *thename, short thesize)
void glueputfont(dfacptr thedfac, fontptr thefont)
short gluedumpfont(dfacptr thedfac, char *thename, short thesize);
short gluemakefont(dfacptr thedfac, char *thename, short thesize, short grayscale)
short *glueinfofont(fontptr thefont, short *fontascent, short *lineheight)
long gluegetcarettime(void)

ptr glueinfobuffer(dfacptr thedfac, short)
void gluedomesticstart(dfacptr thedfac, bigmap *tempmap, short hor, short ver)
void gluedomesticstop(dfacptr thedfac)
void gluesetcliprect(dfacptr thedfac, rect *therect)
void gluerestorecliprect(dfacptr thedfac)
void glueforeignstop(dfacptr thedfac)
short glueforeignstart(dfacptr thedfac, rect *localrect, rect *globalrect, rect *cliprect, ptr *baseaddr, long *rowbytes)
polyptr gluerecttopoly(dfacptr thedfac, rect *theoval)
polyptr glueovaltopoly(dfacptr thedfac, rect *theoval)
polyptr glueroundrecttopoly(dfacptr thedfac, rect *therect, short radhor, short radver)
void gluefadepoly(dfacptr thedfac, polyptr thepoly, big forecolor, point forepoint, big backcolor, point backpoint)
void glueradialpoly(dfacptr thedfac, polyptr thepoly, big forecolor, point forepoint, big backcolor, point backpoint)
void gluefaderect(dfacptr thedfac, rect *therect, big forecolor, point forepoint, big backcolor, point backpoint)
void glueradialrect(dfacptr thedfac, rect *therect, big forecolor, point forepoint, big backcolor, point backpoint)
void gluefadeoval(dfacptr thedfac, rect *therect, big forecolor, point forepoint, big backcolor, point backpoint)
void glueradialoval(dfacptr thedfac, rect *therect, big forecolor, point forepoint, big backcolor, point backpoint)
void gluefaderoundrect(dfacptr thedfac, rect *theroundrect, short radiushor, short radiusver, big forecolor, point forepoint, big backcolor, point backpoint)
void glueradialroundrect(dfacptr thedfac, rect *theroundrect, short radiushor, short radiusver, big forecolor, point forepoint, big backcolor, point backpoint)
void glueinvertroundrect(dfacptr thedfac, rect *theroundrect, short radiushor, short radiusver)
void gluepaintroundrect(dfacptr thedfac, rect *theroundrect, short radiushor, short radiusver, big thecolor)
void glueframeroundrect(dfacptr thedfac, rect *theroundrect, short radiushor, short radiusver, big thecolor, short linewidth, short lineheight)
void gluepatternroundrect(dfacptr thedfac, rect *theroundrect, short radiushor, short radiusver, big forecolor, big backcolor, unsigned char *thepat)
void glueframepatternroundrect(dfacptr thedfac, rect *theroundrect, short radiushor, short radiusver, big forecolor, big backcolor, unsigned char *thepat, short linewidth, short lineheight)
void glueinvertline(dfacptr thedfac, point startpt, point stoppt, short linewidth, short lineheight)
void gluepaintline(dfacptr thedfac, point startpt, point stoppt, big thecolor, short linewidth, short lineheight)
void gluepatternline(dfacptr thedfac, point startpt, point stoppt, big forecolor, big backcolor, unsigned char *thepat, short linewidth, short lineheight)
void glueinvertoval(dfacptr thedfac, rect *theoval)
void gluepaintoval(dfacptr thedfac, rect *theoval, big thecolor)
void glueframeoval(dfacptr thedfac, rect *theoval, big thecolor, short linewidth, short lineheight)
void gluepatternoval(dfacptr thedfac, rect *theoval, big forecolor, big backcolor, unsigned char *thepat)
void glueframepatternoval(dfacptr thedfac, rect *theoval, big forecolor, big backcolor, unsigned char *thepat, short linewidth, short lineheight)
void glueinvertpoly(dfacptr thedfac, polyptr thepoly)
void gluepaintpoly(dfacptr thedfac, polyptr thepoly, big thecolor)
void glueframepoly(dfacptr thedfac, polyptr thepoly, big thecolor, short linewidth, short lineheight)
void gluepatternpoly(dfacptr thedfac, polyptr thepoly, big forecolor, big backcolor, unsigned char *thepat)
void glueframepatternpoly(dfacptr thedfac, polyptr thepoly, big forecolor, big backcolor, unsigned char *thepat, short linewidth, short lineheight)
void gluepaintrect(dfacptr thedfac, rect *therect, big thecolor)
void gluepatternrect(dfacptr thedfac, rect *therect, big forecolor, big backcolor, unsigned char *thepat)
void glueinvertrect(dfacptr thedfac, rect *therect)
void glueframerect(dfacptr thedfac, rect *therect, big thecolor, short linewidth, short lineheight)
void glueframepatternrect(dfacptr thedfac, rect *therect, big forecolor, big backcolor, unsigned char *thepat, short linewidth, short lineheight)
void gluedrawscale(dfacptr thedfac, handle temphand, point tempoint, short ink, short width, short height)
void gluedrawstep(dfacptr thedfac, handle temphand, rect *therect, short mask)
short gluepointindrawstep(dfacptr thedfac, handle temphand, rect *thebounds, point testpoint)
void gluedrawrich(dfacptr thedfac, handle temphand, rect *therect)
short gluepointinrotatestep(dfacptr thedfac, handle temphand, point destpoint, short width, short height, short angle, point testpoint)
void gluerotatestep(dfacptr thedfac, handle temphand, point destpoint, short width, short height, short angle, short mask)
void gluerotaterich(dfacptr thedfac, handle temphand, point destpoint, short width, short height, short angle)
void gluerotatepoly(polyptr thepoly, rect *therect, short angle)
void gluecreatebigmap(dfacptr thedfac, bigmap *thebigmap, short width, short height)
void gluedestroybigmap(dfacptr thedfac, bigmap *thebigmap)
void gluedrawbigs(dfacptr thedfac, bigmap *thebigmap, short width, short height, rect *therect)
void gluerotatebigs(dfacptr thedfac, bigmap *thebigmap, point destpoint, short newwidth, short newheight, short angle)
void gluedrawsprite(dfacptr thedfac, handle temphand, point tempoint, short ink, short fliph, short flipv)
void gluescalebounds(dfacptr thedfac, handle temphand, point tempoint, short width, short height, rect *therect, point *thereg)
void gluespritebounds(dfacptr thedfac, handle temphand, point tempoint, short fliph, short flipv, rect *therect, point *thereg)
short gluepointinsprite(dfacptr thedfac, handle temphand, point tempoint, short fliph, short flipv, point testpoint)
short gluepointinscale(dfacptr thedfac, handle temphand, point tempoint, short width, short height, point testpoint)
void gluescreeninfo(dfacptr thedfac, short *width, short *height, short *depth, short *is555, rect *outside)
short gluepointinpoly(dfacptr thedfac, polyptr thepoly, point testpt)
short gluepointinoval(dfacptr thedfac, rect *therect, point testpt)
short gluepointinroundrect(dfacptr thedfac, rect *therect, short radhor, short radver, point testpt)
void gluescalebig2big(dfacptr thedfac, bigmap *srcbits, bigmap *dstbits, rect *srcrect, rect *dstrect)
polyptr gluearctopoly(dfacptr thedfac, rect *therect, short startangle, short stopangle)
void gluefadearc(dfacptr thedfac, rect *thearc, short startangle, short stopangle, big forecolor, point forepoint, big backcolor, point backpoint)
void glueradialarc(dfacptr thedfac, rect *thearc, short startangle, short stopangle, big forecolor, point forepoint, big backcolor, point backpoint)
void glueinvertarc(dfacptr thedfac, rect *thearc, short startangle, short stopangle)
void gluepaintarc(dfacptr thedfac, rect *thearc, short startangle, short stopangle, big thecolor)
void glueframearc(dfacptr thedfac, rect *thearc, short startangle, short stopangle, big thecolor, short linewidth, short lineheight)
void gluepatternarc(dfacptr thedfac, rect *thearc, short startangle, short stopangle, big forecolor, big backcolor, unsigned char *thepat)
void glueframepatternarc(dfacptr thedfac, rect *thearc, short startangle, short stopangle, big forecolor, big backcolor, unsigned char *thepat, short linewidth, short lineheight)
short gluepointinarc(dfacptr thedfac, rect *therect, short startangle, short stopangle, point testpt)

short gluestep2bigmap(dfacptr thedfac, handle temphand, bigmap *imagbits)
short gluesprite2bigmap(dfacptr thedfac, handle temphand, bigmap *imagbits)
handle gluemakestep(dfacptr thedfac, picthandle temphand, short blocksize)
handle gluemakebeststep(dfacptr thedfac, picthandle temphand, short dither)
handle gluemakesprite(dfacptr thedfac, picthandle temphand, short dither, short perctred)
handle gluemakestepraw(dfacptr thedfac, bigmap *imagbits, short blocksize)
handle gluemakebeststepraw(dfacptr thedfac, bigmap *imagbits, short dither)
handle gluemakespriteraw(dfacptr thedfac, bigmap *imagbits, short dither, short perctred)
void glueclosepictfile(dfacptr thedfac)
picthandle gluegetpictfile(dfacptr thedfac, short num)
void gluedumppictfile(dfacptr thedfac, picthandle temphand)
short gluecountpictfile(dfacptr thedfac)
short glueopenpictfile(dfacptr thedfac, char *thename)
short gluepictfile2bigmap(dfacptr thedfac, picthandle temphand, bigmap *thebits)
short gluebigmap2pictfile(dfacptr thedfac, bigmap *thebits, picthandle *temphand)
void glueinfopictfile(dfacptr thedfac, picthandle temphand, big *theclut, rect *thebounds, short *depth)
short glueexportpictfilestop(dfacptr thedfac)
short glueexportpictfilestart(dfacptr thedfac, char *thefile, short series)
short glueexportbigpictfile(dfacptr thedfac, bigmap *thebits)
void glueselectpictformat(dfacptr thedfac)
handle gluemakerich(dfacptr thedfac, picthandle temphand, short quality)
handle gluemakerichraw(dfacptr thedfac, bigmap *imagbits, short quality)
short gluerich2bigmap(dfacptr thedfac, handle temphand, bigmap *imagbits)
short gluemakepicture(dfacptr thedfac, picthandle temphand, bigmap *imagbits)
void gluesavepictscrap(dfacptr thedfac, picthandle temphand)
short glueloadpictscrap(dfacptr thedfac, picthandle *temphand)

Swap Functions

The swap functions implement byte-order swapping mainly for Macintosh. They also provide object validation. You must write swap functions for your persistent node data structures as well, they are called by the virtual object manager.

void glueswapbig(big *pb)
void glueswapshort(short *ps)
void glueswaplong(long *pl)
void glueswaprect(rect *pr)
void glueswapfloat(float *pf)
void glueswapdouble(double *pd)
short glueswapstep(dfacptr thedfac, handle temphand, short tonative)
short glueswapsprite(dfacptr thedfac, handle temphand, short tonative)
short glueswaprich(dfacptr thedfac, handle temphand, short tonative)

void glueurlgetfilename(char *theurl, char *pathname, char *filename)
short glueurlcracker(char *theurl, char *theserv, char *thefile, short *thehttp, long *theport)
short glueopeninternet(dfacptr thedfac, char *theurl, char *theuser, char *thepass, inet *theinet)
short gluecloseinternet(dfacptr thedfac, inet *theinet)
short gluedateinternet(dfacptr thedfac, char *theurl, char *theuser, char *thepass, timerec *thetime)
short glueclosereadinternet(dfacptr thedfac, inet *theinet)
short glueclosewriteinternet(dfacptr thedfac, inet *theinet, void *responseinfo, long responsesize, long *responseread, short *content)
short glueopenreadinternet(dfacptr thedfac, char *theurl, inet *theinet, long *total, short *content)
short glueopenwriteinternet(dfacptr thedfac, char *theurl, inet *theinet, long total)
short gluereadinternet(dfacptr thedfac, inet *theinet, void *thebytes, long size, long *read)
short gluewriteinternet(dfacptr thedfac, inet *theinet, void *thebytes, long size, long *written)
void gluesavetextscrap(dfacptr thedfac, ptr theptr, long size)
short glueloadtextscrap(dfacptr thedfac, handle *thedata, long *thesize)
long glueinternetdata2textdata(char *srcptr, long srcsize, char *dstptr, short content)
long gluetextdata2internetdata(char *srcptr, long srcsize, char *dstptr, short content)

Argument Fetchers

These functions are used to fetch and type convert the raw DreamFactory input to the scripting commands. They use the same types as all the DreamFactory language: long, text, float, double, and binary.

short gluefetchlong(passptr thepass, short thearg, long *thelong)
short gluefetchtext(passptr thepass, short thearg, ptr *thestring)
short gluefetchfloat(passptr thepass, short thearg, float *thefloat)
short gluefetchlogic(passptr thepass, short thearg, long *thelogic)
short gluefetchbinary(passptr thepass, short thearg, ptr *thedata, long *thesize)
short gluefetchdouble(passptr thepass, short thearg, double *thedouble)

void gluedumpsound(dfacptr thedfac, soundrunptr thesound)
short glueexportwave(dfacptr thedfac, handle thedata, char *filename)
short glueswapsound(dfacptr thedfac, handle temphand, short tonative)
short glueimportwave(dfacptr thedfac, char *filename, long *thesize, handle *thedata, short islooped, short compressionmethod)
soundrunptr glueloadsound(dfacptr thedfac, pathptr thepath, long theid)
void gluestopallsound(dfacptr thedfac)
void gluestoponesound(dfacptr thedfac, soundrunptr thesound)
short gluesoundisplaying(dfacptr thedfac, soundrunptr thesound)
void glueplaysinglesound(dfacptr thedfac, soundrunptr thesound)
void glueplaymultiplesound(dfacptr thedfac, soundrunptr thesound)
short gluegetsoundvol(dfacptr thedfac, soundrunptr thesound)
short gluegetsoundpan(dfacptr thedfac, soundrunptr thesound)
short gluegetsoundloop(dfacptr thedfac, soundrunptr thesound)
long gluegetsoundprior(dfacptr thedfac, soundrunptr thesound)
void gluesetsoundvol(dfacptr thedfac, soundrunptr thesound, short vol)
void gluesetsoundpan(dfacptr thedfac, soundrunptr thesound, short pan)
void gluesetsoundprior(dfacptr thedfac, soundrunptr thesound, long priority)
void gluesetsoundloop(dfacptr thedfac, soundrunptr thesound, short loop)
void glueinfowave(dfacptr thedfac, handle thedata, short *compressionmethod, short *bytespersample, long *samplerate, long *decompressedsize, long *durationinms, long *packedsize)
void gluestopwave(dfacptr thedfac)
void gluestartwave(dfacptr thedfac, long channels)
short gluegetwavevol(dfacptr thedfac)
long gluewavechannels(dfacptr thedfac)
void gluesetwavevol(dfacptr thedfac, short thevol)
handle glueunpackwave(dfacptr thedfac, handle sourcedata, long desiredsamplingrate, short desiredbytespersample)
void glueselectwaveformat(dfacptr thedfac)
handle gluerecordsound(dfacptr thedfac, long therate, short thebytes, long maxmstorcd, long *handlesize)
handle gluepackwave(dfacptr thedfac, handle sourcedata, long sourcesize, long samplerate, short bytespersam, short compmeth)
short gluesoundcompmeth(dfacptr thedfac, long therate, short bytespersam)

Cursors

These functions manipulate the standard system cursors.

void gluesetcursor(dfacptr thedfac, char *thename)
void glueshowcursor(dfacptr thedfac)
void gluehidecursor(dfacptr thedfac)

Environment

These functions return information about the DreamFactory environment.

short gluetinyfootprint(dfacptr thedfac)
void gluemachinename(char *thename)
unsigned long gluegetms(void)
long glueelapsedms(unsigned long basetime, unsigned long newtime)

short gluepointinhandles(rect *therect, point thepoint)
void gluedrawhandles(dfacptr thedfac, rect *therect)
long gluewhichhandle(rect *therect, point thepoint)
void gluedrawfontstyle(dfacptr thedfac, fontptr thefont, char *thestring, point thepoint, big thecolor, short thestyle)

Back to top

Plug-in Deployment

Finished plug-ins are easy to deploy. First, simply drag the compiled plug-in into the plug-ins folder and restart DreamFactory. Depending on your development environment, many times the Visual Studio or Code Warrior project can be debugged in the plug-ins folder while running. When you are sure that the plug-in is working, add the new capability to one of your projects. This project will automatically download the plug-in client side. Check the pluginstausget() and pluginstatusset() system commands for including or excluding a plug-in from a certain project.

You will also need the help text file and the default script text file for the new plug-in. The help file should follow the format of other plug-in and system help files. The default script file can be whatever a new node with this plug-in requires. These files must be stored on the deployment server in the proper folders. See the DreamFactory Enterprise installation Guide for more information. The plug-ins should also be "zipped" with the zip utility. So for example, a Macintosh plug-in for reading PDF files might be titled "adobe.zip" and the Windows DLL might be titled "adobe.dll.zip." The name of the plug-in inside DreamFactory will be "adobe" and must match the name that the plug-in returns.

The structure of files locally for DreamFactory is mirrored on the deployment folder. All of the standard plug-ins are installed from either the "installmac" or "installwin" zip files. New custom plug-ins or updates must come from special folders on the deployment server. The Windows DLL and/or Macintosh Code Fragment must be stored in a "plugins" folder. The help text file must be in a folder titled "help." And lastly the default script file must be in a "scripts" folder. As you write new plug-ins simply add them to these folders on the deployment server. The exact same method can be used to upgrade existing plug-ins with a higher version number. If the downloaded project needs a plug-in with a higher version number, the appropriate files will be downloaded from the "plugins", "scripts", and "help" folders on the deployment server. DreamFactory fully takes care of and manages the problem with different plug-ins on different machines written by different people. The only possible problem is plug-ins that have name collisions, so be sure to give new plug-ins a unique name.

Back to top