The Import/Export Library: 2.3 Using Impex: The ExportControl Object

| Up: GEOS SDK TechDocs| Up | Prev: 2.2 The ImportControl Object | Next: 3 Writing Translation Libraries

Applications which use the Impex library will generally have a single ExportControl 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 GCN list. Applications should disable this object (with MSG_GEN_SET_NOT_ENABLED) whenever they are not able to prepare data for export; for example, some applications will choose to disable file exporting whenever the "Cut" and "Copy" functions are disabled.

The ExportControl 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 ExportControlClass Instance Data.

Code Display 16-2 ExportControlClass Instance Data

/* ECI_attrs is a word-length record which stores attribute information for the
 * ImportControl object. It has only one flag, ECA_IGNORE_INPUT. */
    @instance ExportControlAttrs					ECI_attrs = 0;
/* ECI_dataClasses is a word-length record which indicates what Metafile formats
 * are supported by the application. The application must set this field. */
    @instance ImpexDataClasses					ECI_dataClasses = 0;
/* ECI_destination and ECI_message indicate what message should be sent when the
 * ExportControl object is preparing to export 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					ECI_destination;
    @instance word					ECI_message;
/* Applications may wish to add their own UI objects to the Export 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_EXPORT_CONTROL_APP_UI.
 */
    @vardata optr 					ATTR_EXPORT_CONTROL_APP_UI;
/* Controller features flags */
typedef ByteFlags 			ExportControlFeatures;
#define EXPORTCF_BASIC			0x01
typedef	ByteFlags 			ExportControlToolboxFeatures;
#define EXPORTCTF_DIALOG_BOX				0x01

ECI_attrs

ExportControlAttrs, MSG_EXPORT_CONTROL_GET_ATTRS, MSG_EXPORT_CONTROL_SET_ATTRS

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

ECA_IGNORE_INPUT
If this flag is on, the ExportControl 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_EXPORT_CONTROL_GET_ATTRS to the ImportControl. To change this field, send MSG_EXPORT_CONTROL_SET_ATTRS to the ImportControl.

MSG_EXPORT_CONTROL_GET_ATTRS

ExportControlAttrs	 MSG_EXPORT_CONTROL_GET_ATTRS();

This message retrieves the current setting of the ExportControl's ECI _attrs field.

Source: Unrestricted.

Destination: Any ExportControl object.

Return: The ExportControl's ECI _attrs field.

Interception: This message should not be intercepted.

MSG_EXPORT_CONTROL_SET_ATTRS

void	MSG_EXPORT_CONTROL_SET_ATTRS(
        ExportControlAttrs		attrs);

This message changes the current settings of an ExportControl's ECI _attrs field.

Source: Unrestricted.

Destination: Any ExportControl object.

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

Interception: This message should not be intercepted.

ECI_dataClasses

MSG_EXPORT_CONTROL_GET_DATA_CLASSES, MSG_EXPORT_CONTROL_SET_DATA_CLASSES

When you declare an Export object, you must specify what kind of Metafiles your application is able to create. You do this by setting the value of the ECI _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 ExportControl will use only those export libraries which expect text Metafile input. More than one bit may be set; when the ExportControl sends its notification, it will tell the application what type of data it expects to export.

To find out the current settings of the ECI _dataClasses field, send MSG_EXPORT_CONTROL_GET_DATA_CLASSES. To change the settings of this field, send MSG_EXPORT_CONTROL_SET_DATA_CLASSES.

MSG_EXPORT_CONTROL_GET_DATA_CLASSES

ImpexDataClasses	 MSG_EXPORT_CONTROL_GET_DATA_CLASSES();

This message retrieves the current setting of the ExportControl's ECI _dataClasses field. This tells you what kind of data can be exported.

Source: Unrestricted.

Destination: Any ExportControl object.

Return: The ExportControl's ECI _dataClasses field.

Interception: This message should not be intercepted.

MSG_EXPORT_CONTROL_SET_DATA_CLASSES

void	MSG_EXPORT_CONTROL_SET_DATA_CLASSES(
        ImpexDataClasses 		dataClasses);

This message changes the current settings of an ExportControl's ECI _dataClasses field.

Source: Unrestricted.

Destination: Any ExportControl object.

Parameters: dataClasses The new settings for the ECI _dataClasses field.

Interception: This message should not be intercepted.

The ExportControl Action

MSG_EXPORT_CONTROL_GET_ACTION, MSG_EXPORT_CONTROL_SET_ACTION

The ExportControl does most of its work transparently to the application. It interacts with the rest of the application after the user selects the name, location, and format of the exported file. At this point the ExportControl creates a temporary transfer file and sends a notification message to the application; the notification message passes the file handle and the format expected. The application responds by creating a VM chain in the transfer file and filling it with the data to export, formatted in the appropriate Metafile format. The ExportControl can then call the translation library to create the output file.

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

ITP_impexOD
The object to which the application should send its acknowledgment message. In this case, it is the optr of the ExportControl.
ITP _returnMsg
The acknowledgment message to send when the export has been completed. In this case, it is MSG_EXPORT_CONTROL_EXPORT_COMPLETE.
ITP _dataClass
An ImpexDataClasses record with one flag set. This flag indicates what type of Metafile should be prepared.
ITP _transferVMFile
The VMFileHandle of the temporary transfer file.
ITP _transferVMChain
A null handle. When the application has created the transfer VM chain, it should write the VMBlockHandle of the head of the chain to this field. If the application fails for any reason, it should leave this field as a null handle.
ITP _internal
This field is for use by the ExportControl and should not be changed by the application.

The recipient of the message should take any appropriate action; usually this entails translating the current selection into the Metafile format and writing it to a VM chain. When the application is finished, it should call ImpexImportExportCompleted() . This routine will send the appropriate acknowledgment message to the ExportControl object (in this case, MSG_EXPORT_CONTROL_EXPORT_COMPLETE ). This routine takes one parameter, namely the itp pointer which was passed to the object. The ITP _transferVMChain field of the ImpexTranslationParams structure should be set to the handle of the head block in the VM chain. If the application was unable to prepare the data for export, it should clear this field.

The ExportControl object will have created a temporary file for the application to use. This file will be entirely empty when the application gets it. The ExportControl will ignore everything in the file except for the VM chain indicated by ITP _transferVMChain ; thus, an application can feel free to allocate blocks in the VM file for scratch space. The ExportControl will destroy the file when the translation library has finished preparing the output file.

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

MSG_EXPORT_CONTROL_GET_ACTION

void	MSG_EXPORT_CONTROL_GET_ACTION(
        ObjectState *		retValue);

This message retrieves the values of an ExportControl's ECI _destination and ECI _message fields. These fields indicate what action the ExportControl will take when it needs to have data prepared for export.

Source: Unrestricted.

Destination: Any ImportControl object.

Parameters: retValue A pointer to an ObjectState structure.

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

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

Interception: This message should not be intercepted.

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

typedef struct {
	int	notUsed;
	word	message;		/* Message sent */
	optr	destOD;		/* Destination of message */
} ObjectState;

MSG_EXPORT_CONTROL_SET_ACTION

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

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

Source: Unrestricted.

Destination: Any ExportControl object.

Parameters: recipient Set ECI _destination to this value.

message
Set ECI _message to this value.

Interception: This message should not be intercepted.

Adding to the Import Dialog Box

When the user selects the "Export" trigger or tool, the Export 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_EXPORT_CONTROL_APP_UI. When the ExportControl 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.2 The ImportControl Object | Next: 3 Writing Translation Libraries