[15.2] How do I use XObjects?

In order to use an XObject, you must first open the XObject resource or DLL file that contains the XObject code. On the Mac it is possible to embed XObjects in the resource fork of the Director movie, which removes the need to open the file first, but this is generally frowned upon these days as it makes the movie platform-dependent. (On the other hand, movies using XObjects are often platform dependent by definition anyway, so this may be a moot point). To open the XObject file, use :

  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 era

How 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 type

It'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 #noTardis

Just 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)