Embedding

Documents from one program can be "embedded" in a document by another program using a simple mechanism called IOA, Independent Object Architecture.

Definition of Independent Object

An Independent Object is a file in X11 Bitmap format, which illustrates the state of an IOA server at some point. Typically this will be a screenshot of a document.

The file may also contain a comment which describes how the server program can be invoked in a way which brings back its state at the time of the object creation. The format of the comment is: 

/*
EmBeDcommand string
*/
The command string will, when handed over to the shell, start the server with whatever parameters are appropriate. For example, if an object is created from Siag with the document heaven.siag loaded, the command string will be: 
siag heaven.siag

Definition of IOA Server

An IOA server is a program which is capable of creating Independent Objects. It should also add the description comment to the file as described above.

Definition of IOA Client

An IOA client is a program which is capable of reading and displaying Independent Objects. It should also be able to extract the description comment and invoke the server that created the object.

Fully conforming servers and/or clients must implement the "should" capabilities. It is possible for a program to be a server, a client or both.

Reference Implementation

There is a reference implementation of this specification which makes adding IOA to an application very easy. This was inspired by the DND library, which adds Drag and Drop with almost no extra coding. The implementation consists of two C source files, embed.c and embed.h. These are in the common subdirectory of the Siag source tree.

Return Values

#define EMBED_OK 0
#define EMBED_ERR 1
Conditions that may give the return EMBED_ERR include out of memory, specified object file does not exist, tag does not refer to a loaded object.

Functions

int embed_init(Widget toplevel)
Called before any other functions. 
char *embed_load(char *filename)
Loads an object. Returns the file name if successful, otherwise NULL. This is used as a tag to the object in subsequent calls to embedding functions. 
int embed_unload(char *tag)
Unloads a previously loaded object. 
int embed_open(char *tag)
Starts the creating server program according to the description comment. If there is no description comment, as is the case with X11 Bitmap files created by nonconforming applications, the file is loaded into the application bitmap. 
int embed_save(char *filename, char *command, Pixmap bitmap)
A new object file is created, using filename as file name, command as the description (without the "EmBeD") and bitmap as the bitmap of depth 1 which should be displayed by a client. 
int embed_print(FILE *fp, char *tag, int x, int y)
Creates Postscript code to print the object at offset x,y on a page. This is not yet implemented, only the outline rectangle is drawn. 
int embed_size(char *tag, unsigned int width, unsigned int height)
Returns the width and height of the object. 
int embed_draw(Drawable d, int x, int y, char *tag)
Draws the object on the specified drawable.

Conforming Applications

Siag and Pathetic Writer use the reference implementation to create and use objects. Egon Animator will do so when it is ready.

Many applications created before the IOA specification are capable of creating and/or displaying X11 Bitmaps, including XPaint, Netscape, Chimera and XV.

Discussion about File Formats

The most basic use for this feature is for plain images, with no regard to the "objectisms". However, the XBM format is not very good for this purpose. It is black-and-white and uses a lot of disk space even for small pictures. There are a few other candidates for the job, but none that have all these three properties: The format which comes closest is XPM, which is almost an X standard. Would be almost perfect, were it not for the fact that Netscape can't display XPM. Chimera can, however.

XPM shares with XBM the property that the file format is plain C which can trivially be #included in a C program. This makes it monumentally simple to create a basic object server.

Ulric Eriksson - July 1997 - ulric@edu.stockholm.se