XObjects are Director's native standalone code format, using much the same object-oriented structure as factories. XCMDs (external commands) and XFCNs (external functions) are Mac code resource formats originally devised for HyperCard and subsequently adopted by a number of other applications. DLLs (dynamic link libraries) are the Windows standard format for standalone code.
OpenXLib "myXObject"where "myXObject" is the pathname to the file, including any volume or drive specifications as necessary. Once the file is open, you can query the XObjects it contains (they should be XFactories really, but I digress) to find out how they're used by typing
XObjectName(mDescribe)in the message window. Note that this method is only meaningful when sent to the XFactory code itself, not to any XObjects you create from it. The result of mDescribe will generally look something like this:
-- Factory: TimeTravel ID:3456 -- TimeTravel XObject v1.0 -- © Oswald Bastable 1901 -- I mNew -- Creates a new time machine X mDispose -- Disposes of the time machine XIII mJump, year, month, day -- Travels to the chosen time S mGetEra -- Returns the name of the present eraHow do we interpret this? Just as in Lingo, anything preceded by two hyphens is a comment. The first describes what the XFactory is called and its resource ID. Subsequent comment lines are provided by the author(s) to give various details about the XFactory -- what it does, what version it's at, who wrote it, etc. Some mDescribes are substantially more helpful than others where comments are concerned.
Each line starting with a group of capital letters and a method name (which will almost always start with an "m") declares one of the messages that XObjects created from the XFactory will accepting, specifying what other parameters are required. Usually there will be a set of names for the parameters that are vaguely descriptive, but this is not always the case. By purely a convetion. The only required elements are the letters and the name. So what do they tell us?
The first letter specifies a return type, while any letters immediately following it are parameter types. The types they represent are as follows:
X No return value I Integer S String L Handle to list of integers P Picture handle O XObject instance V variable number and type of arguments and variable return typeIt's unlikely that you'll encounter many objects that use other than X, I and S, though P and V are used occasionally. If V is used, it is the only specifier, and it's up to the XObject authors to provide details of what arguments and return types the method can use.
Looking again at the methods listed for the TimeTravel XObject above, we see that mDispose takes no arguments and returns no value, mGetEra takes no arguments and returns a string, and mJump takes three integer arguments and returns nothing. mNew in this case is listed as returning an integer, though other objects may declare it with return type X. Both are somewhat disingenuous, since a call to mNew will usually return an XObject instance. The return type in this case is what you get if mNew is unable to create the XObject -- usually some kind of error code.
Before you can use any of the methods of the XObject, you must first create an XObject instance by calling mNew and assigning the result to a variable
set tardis = TimeTravel(mNew)Because XObject creation may fail arbitrarily for reasons you may not have any control over, it's always a good idea to check that you actually have an object before using it :
if not objectP(tardis) return #noTardisJust like factory and child objects, you can create as many XObject instances as you like and each should operate in splendid isolation, completely unaffected by the others (actually, this is often not true: many XObjects, particularly those that control a global resource like the monitor display or an external device, may only be instantiated once -- but usually this will be documented in mDescribe if it is the case).
Once you've successfully created as many XObject instances as you want, you should close the XObject library file :
closeXLib "myXObject"You don't have to do this right away, but you have to remember to do it eventually, and now's as good a time as any.
Thereafter, you use the XObject just like any other object created from a factory (that is to say, *not* just like objects birthed from a parent script):
tardis(mJump, 1963, 11, 22) set currentEra = tardis(mGetEra)Finally, when you're done with it, you have to dispose of the XObject instance explicitly or it'll just hang around using up memory and getting in the way :
tardis(mDispose)
ftp://198.64.7.253/Directorso just download 'em instead! (If you really want to know, email me and I'll send you the details, but -- trust me on this -- it's boring.)
The Macintosh XDK is supposed to be being revamped, but in the meantime it is available direct from Macromedia for US$50. Many people (myself included) have complained that this woefully inadequate and antiquated product is well past it's use-by date, but you can't really write an XObject without it.
If you have version 1.1 of the XDK, be sure to update it to version 1.2 with the updater available online (it should be on the Direct-L ftp site, ftp://198.64.7.253/Director), or see the bugfixes in 15.10 above.
-- if the XObject method mDraw is mDescribed thus: -- XP mDraw me, myPicHandle -- you can pass it a PicHandle like this: mDraw( myDrawXObject, the picture of cast blah ) -- similarly Xobjects could return pictures: -- PS mReadTIFF me, fileName -- which you could use thus: set the picture of cast blah = mReadTIFF(myTiff15Object, "myPic.tiff")(before anyone asks, I'm not aware of any XObjects that allow for importing TIFF files!)
Maricopa Center for Learning and Instruction (MCLI)
The Internet Connection at MCLI is
Alan Levine --}
Comments to
levine@maricopa.edu
URL: http://www.mcli.dist.maricopa.edu/director/faq/faq15.html