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
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:
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.
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.
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.
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.
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.
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.
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
_returnMsg
MSG_IMPORT_CONTROL_IMPORT_COMPLETE.
_dataClass
ImpexDataClasses
record with one flag set. This flag indicates what type of Metafile has been prepared.
_transferVMFile
VMFileHandle
of the temporary transfer file.
_transferVMChain
VMBlockHandle
of the lead block in the VM chain containing the imported data.
_internal
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
.
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
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;
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
_message
to this value.Interception: This message should not be intercepted.
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".