The Import/Export Library: 2.2 Using Impex: The ImportControl Object

Up: GEOS SDK TechDocs| Up | Prev: 2.1 Common Impex Concepts | Next: 2.3 The ExportControl Object

Applications which use the Impex library will generally have a single ImportControl object. This object is usually a child of the File menu; however, applications may put it wherever they want. They should also place it on the application object's GAGCNLT_SELF_LOAD_OPTIONS General Change Notification list. Applications should disable this object (with MSG_GEN_SET_NOT_ENABLED) whenever they are not prepared to accept imported data; for example, some applications will choose to disable file importing whenever they are unable to open a new document.

The ImportControl object is subclassed from GenControlClass (by way of ImportExportClass , as noted above). It thus has all the functionality of that class. It also has a few instance data fields of its own; they are shown in ImportControlClass Instance Data.

Code Display 16-1 ImportControlClass Instance Data

/* ICI_attrs is a word-length record which stores attribute information for the
 * ImportControl object. It has only one flag, ICA_IGNORE_INPUT. */
    @instance ImportControlAttrs					ICI_attrs = 0;
/* ICI_dataClasses is a word-length record which indicates what Metafile formats
 * are supported by the application. The application must set this field. */
    @instance ImpexDataClasses					ICI_dataClasses = 0;
/* ICI_destination and ICI_message indicate what message should be sent when the
 * ImportControl object has finished importing a file. The application must set
 * these fields. The message must take a single argument, namely a pointer to an
 * ImpexTranslationParams structure in ss:bp (on the stack). */
    @instance optr					ICI_destination;
    @instance word					ICI_message;
/* Applications may wish to add their own UI objects to the Import dialog box.
 * They can do so by defining a generic tree (the top object of which must be not
 * "usable"), and putting an optr to the top object in ATTR_IMPORT_CONTROL_APP_UI.
 */
    @vardata optr 					ATTR_IMPORT_CONTROL_APP_UI;
/* Controller features flags */
typedef ByteFlags 			ImportControlFeatures;
#define IMPORTCF_BASIC			0x01
typedef	ByteFlags 			ImportControlToolboxFeatures;
#define IMPORTCTF_DIALOG_BOX				0x01

ICI_attrs

ImportControlAttrs, MSG_IMPORT_CONTROL_GET_ATTRS, MSG_IMPORT_CONTROL_SET_ATTRS

ICI _attrs is a word-length record of type ImportControlAttrs . This record contains only one flag:

ICA_IGNORE_INPUT
If this flag is on, the ImportControl will consume all input to the application while the import occurs. By default, this flag is off.

To find out the current setting of this field, send MSG_IMPORT_CONTROL_GET_ATTRS to the ImportControl. To change this field, send MSG_IMPORT_CONTROL_SET_ATTRS to the ImportControl.

MSG_IMPORT_CONTROL_GET_ATTRS

ImportControlAttrs	 MSG_IMPORT_CONTROL_GET_ATTRS();

This message retrieves the current setting of the ImportControl's ICI _attrs field.

Source: Unrestricted.

Destination: Any ImportControl object.

Return: The ImportControl's ICI _attrs field.

Interception: This message should not be intercepted.

MSG_IMPORT_CONTROL_SET_ATTRS

void	MSG_IMPORT_CONTROL_SET_ATTRS(
        ImportControlAttrs		attrs);

This message changes the current settings of an ImportControl's ICI _attrs field.

Source: Unrestricted.

Destination: Any ImportControl object.

Parameters: attrs The new settings for the ICI _attrs field.

Interception: This message should not be intercepted.

ICI_dataClasses

MSG_IMPORT_CONTROL_GET_DATA_CLASSES, MSG_IMPORT_CONTROL_SET_DATA_CLASSES

When you declare an Import object, you must specify what kind of Metafiles your application is prepared to accept. You do this by setting the value of the ICI _dataClasses field. This field is a word-length record of type ImpexDataClasses (described in ImpexTranslationParams). If (for example) only the IDC_TEXT bit is set, the ImportControl will use only those import libraries which produce text Metafile output. More than one bit may be set; when the ImportControl sends its notification, it will tell the application what type of data is being imported.

To find out the current settings of the ICI _dataClasses field, send MSG_IMPORT_CONTROL_GET_DATA_CLASSES. To change the settings of this field, send MSG_IMPORT_CONTROL_SET_DATA_CLASSES.

MSG_IMPORT_CONTROL_GET_DATA_CLASSES

ImpexDataClasses	 MSG_IMPORT_CONTROL_GET_DATA_CLASSES();

This message retrieves the current setting of the ImportControl's ICI _dataClasses field. This tells you what kind of data can be imported.

Source: Unrestricted.

Destination: Any ImportControl object.

Return: The ImportControl's ICI _dataClasses field.

Interception: This message should not be intercepted.

MSG_IMPORT_CONTROL_SET_DATA_CLASSES

void	MSG_IMPORT_CONTROL_SET_DATA_CLASSES(
        ImpexDataClasses 		dataClass);

This message changes the current settings of an ImportControl's ICI _dataClasses field.

Source: Unrestricted.

Destination: Any ImportControl object.

Parameters: dataClass The new settings for the ICI _dataClasses field.

Interception: This message should not be intercepted.

The ImportControl Action

MSG_IMPORT_CONTROL_GET_ACTION, MSG_IMPORT_CONTROL_SET_ACTION, ImpexImportExportCompleted()

The ImportControl does most of its work transparently to the application. It interacts with the rest of the application only when the user has selected a file to import and the appropriate translation library has produced a VM chain. At this point the ImportControl sends a notification message to the application. The application responds by copying the data from the VM chain and sending back an acknowledgment message. The ImportControl can then destroy the temporary VM transfer file.

The application determines what message will be sent, and to what object, by setting the ICI _destination and ICI _message fields. Whatever object will receive the message should define an appropriate message. The ImportControl will send this message with a single parameter: itp , a pointer to an ImpexTranslationParams structure (see ImpexTranslationParams). The fields of the structure have the following meanings in this case:

ITP_impexOD
The object to which the application should send its acknowledgment message. In this case, it is the optr of the ImportControl.
ITP _returnMsg
The acknowledgment message to send when the import has been completed. In this case, it is MSG_IMPORT_CONTROL_IMPORT_COMPLETE.
ITP _dataClass
An ImpexDataClasses record with one flag set. This flag indicates what type of Metafile has been prepared.
ITP _transferVMFile
The VMFileHandle of the temporary transfer file.
ITP _transferVMChain
The VMBlockHandle of the lead block in the VM chain containing the imported data.
ITP _internal
For use by the ImportControl and should not be changed by the application.

The recipient of the message should take any appropriate action; usually this entails copying the data from the VM chain, as if it were pasting data from the Clipboard. When the application is finished, it should call ImpexImportExportCompleted() . This routine takes one parameter, namely the itp pointer which was passed to the object. (The ImpexTranslationParams structure should not have been changed.) ImpexImportExportCompleted() reads the appropriate message and destination from the ImpexTranslationParams and sends the proper acknowledgment message (which in this case is MSG_IMPORT_CONTROL_IMPORT_COMPLETE ).

Applications which use the object model of document control will often set ICI _destination to TO_APP_TARGET; this will make it send its messages to the target object. The application can find out the ImportControl's action by sending it MSG_IMPORT_CONTROL_GET_ACTION . The application can change the ImportControl's action by sending it MSG_IMPORT_CONTROL_SET_ACTION .

MSG_IMPORT_CONTROL_GET_ACTION

void	MSG_IMPORT_CONTROL_GET_ACTION(
        ImpexAction *		retValue);

This message retrieves the values of an ImportControl's ICI _destination and ICI _message fields. These fields indicate what action the ImportControl will take when it is finished preparing a file for import.

Source: Unrestricted.

Destination: Any ImportControl object.

Parameters: retValue A pointer to an ImpexAction structure.

Return: The value of ICI _message (i.e. the message sent by the ImportControl).

recipient
A pointer to an ImpexAction structure describing the message sent.

Interception: This message should not be intercepted.

Structures: The message and recipient are written to an ImpexAction structure:

typedef struct {
	word	message;		/* message sent */
	word	unused;
	optr	destOD;		/* Destination of message */
} ImpexAction;

MSG_IMPORT_CONTROL_SET_ACTION

void	MSG_IMPORT_CONTROL_SET_ACTION(
        optr	destOD,	/* Send messages to this object. */
        word	ICImsg);	/* Send this message to the above recipient. */

This message changes the values of an ImportControl's ICI _destination and ICI _message fields. These fields indicate what action the ImportControl will take when it is finished preparing a file for import.

Source: Unrestricted.

Destination: Any ImportControl object.

Parameters: destOD Set ICI _destination to this value.

ICImsg
Set ICI _message to this value.

Interception: This message should not be intercepted.

Adding to the Import Dialog Box

When the user selects the "Import" trigger or tool, the Import controller brings up a dialog box. The application can, if it wishes, add UI objects to this box. It does so by defining a tree of generic objects (the top object of which must be set "not usable"). It must place an optr to the top object in the tree in ATTR_IMPORT_CONTROL_APP_UI. When the ImportControl builds the dialog box, it will add that optr as one of the children in the tree and set it "usable".


Up: GEOS SDK TechDocs| Up | Prev: 2.1 Common Impex Concepts | Next: 2.3 The ExportControl Object