Editing Extended Objects (How to Create a Plug-In) Changed in Version 2023.0

If a plug-in creates custom "extended objects", it must also provide a set of methods that allow users to edit those objects' geometrical data, properties, texts, and attributes using the application's commands and general editing dialogs.

Extended Object Information

To provide information about extended objects, the plug-in must handle the following commands in the MKI_PlugInNotify procedure:

MKI_NOTIFY_EXT_GET_TITLEPTR

Is called whenever the application needs a short and static, general description of the given type of extended object, such as "3D Extrusion".

MKI_NOTIFY_EXT_GET_CONTENT

Is called whenever the application needs a detailed description of the extended object. The plug-in must provide a textual, detailed description of this very object to be used in the dialog's caption or at the cross-hairs.

Extended Object Modification

To enable modification of extended objects, the plug-in must handle the following commands in the MKI_PlugInNotify procedure:

General Notifications

MKI_NOTIFY_EXT_INIT

The object Ext was either freshly created or modified and shall be (re-)initialized, i.e. a new display list shall be created.

MKI_NOTIFY_MODIFY_INIT

Is called every time then the application is about to start an undo-aware multi entity modification process in the progress of which any extended object might be modified.

MKI_NOTIFY_MODIFY_FINISH

Is called when the undo-aware multi entity modification process previously started was successfully finished.

MKI_NOTIFY_MODIFY_FINISH

Is called when the undo-aware multi entity modification process previously started was canceled (by the user or due to an error).

Matrix Application (Move, Rotate, Scale, etc.)

MKI_NOTIFY_EXT_CREATE

Is called whenever an extended object has been created, i.e. allocated or duplicated in memory. Initialize any necessary object data.

MKI_NOTIFY_EXT_MOVE

Is called whenever an extended object shall be moved, i.e. it shall be multiplied with a matrix.

MKI_NOTIFY_EXT_HIDE

Is called whenever an extended object is "hidden", i.e. temporarily deleted by the undo structure. Any resource linked to that object will usually remain valid as it can become visible again at a later time.

MKI_NOTIFY_EXT_SHOW

Is called whenever an extended object becomes "visible" again by the undo structure. Any resource linked to that object can be checked and updated if necessary.

MKI_NOTIFY_EXT_DESTROY

Is called whenever an extended object shall be destroyed, i.e. permanently removed from memory. Any resource linked to that object shall be freed now.

Property Editing

MKI_NOTIFY_PROPERTY_INIT

Is called once after the user has selected all objects whose properties shall be edited. At this time, the plug-in must prepare for a concurrent property editing of all extended object types it knows, e.g. allocate memory used to store those properties locally during editing.

Each separate property should have an accompanying modification flag that indicates whether this very property shall be applied to all objects or not (see UseFlag and UseProp members in the MKI_MULTI_XPROPERTY structure as an example). All those flags shall be set to "do not modify" initially.

MKI_NOTIFY_PROPERTY_SETALL

Is only called if the user wants to copy properties from one object to others. Set all modification flags for multi-entity editing of the stated extended object type to "modify".

MKI_NOTIFY_PROPERTY_FILL

Is called once for each extended object before the application's main property editing dialog is displayed in order to request the initial properties to fill the dialog with. All standard properties available shall be copied to the MKI_MULTI_INFO structure, all custom parameters shall be copied to the locally allocated memory.

MKI_NOTIFY_PROPERTY_SINGLE

Is called once each time the user clicks the "Special" button in the application's main property editing dialog and selects a specific type of extended object. The plug-in shall display a dialog that allows editing the locally stored properties for a single object of the type given.

Set all modification flags for multi-entity editing of the stated extended object type to "modify".

MKI_NOTIFY_PROPERTY_MULTIPLE

Is called once each time the user clicks the "Special" button in the application's main property editing dialog and selects a specific type of extended object. The plug-in shall display a dialog that allows editing the locally stored properties for multiple objects of the type given.

Make sure to handle the modification flags for multi-entity editing of the stated extended object type correctly in this dialog, setting only those to "modify" whose properties shall actually be applied to all objects afterwards.

MKI_NOTIFY_PROPERTY_APPLY

Is called once for each extended object when the user leaves the application's main property editing dialog by clicking "OK". The plug-in shall apply all properties stored locally and all standard properties in the MKI_MULTI_INFO structure to the given object, based on the respective modification flag. This object will be a copy of the object originally selected by the user.

MKI_NOTIFY_PROPERTY_EXIT

Is called once after the application's main property editing dialog closed by clicking "OK" or "Cancel". Free any memory you allocated in MKI_NOTIFY_PROPERTY_INIT.

Text Handling / Editing

MKI_NOTIFY_EXT_GET_SHORTTEXT

Return a brief of the textual content for display and identification purposes.

MKI_NOTIFY_FIND_TEXT

Return the complete textual contents for searching purposes.

MKI_NOTIFY_EDIT_TEXT_SINGLE

Is called if the user chooses the extended object for text editing. The plug-in shall display a dialog that allows text editing for one single text within an extended object. If the object contains more than one text, use the identification point to determine which text to offer for editing.

MKI_NOTIFY_EDIT_TEXT_MULTI

Is called if the user chooses the extended object for text editing. The plug-in shall display a dialog that allows text editing for all contained texts of the extended object at once, if possible.

MKI_NOTIFY_VIEW_TEXT_MULTI

The plug-in shall display a dialog that displays all texts within an extended object at once, if possible. We recommend you use the same dialog as for MKI_NOTIFY_EDIT_TEXT_MULTI, but with all text controls being set to read-only.

Attribute Handling / Editing

MKI_NOTIFY_FIND_ATTRIBUTE

The plug-in shall return the textual value of an "attribute" of the extended object if existing.

MKI_NOTIFY_EDIT_ATTRIBUTE

The plug-in shall display a dialog that allows attribute editing for a single attribute.

For detailed information on parameters and return values, please refer to MKI_NOTIFY_*.

The creation and maintenance of extended objects is quite complex, so it's not possible to give a short example that is still complete. For further experience, you can find a complete example of a plug-in creating and maintaining extended objects in the sources of SAMPLE_.DLL. This implementation includes additional code for language-dependent data libraries and the implementation of a dialog window for parameter editing.

Example

Let's have a look at how the usual sequence for the command "Modify > Move / Copy Objects > Offset" would be when Duplicate option is not active ("moving"):

1.The user selects the command, chooses the entities to be moved or copied, enters the reference point and the target point.

2.The application sends MKI_NOTIFY_MODIFY_INIT to all affected plug-ins to prepare them for the coming changes.

3.In order to be able to undo the operation at a later time, the application creates an invisible duplicate of all affected entities. All duplicated objects will be marked as created (a MKI_NOTIFY_EXT_CREATE will be sent for each of them) and all previously existing objects will be marked as hidden (a MKI_NOTIFY_EXT_HIDE will be sent for each of them).

4.The application applies the movement (a matrix operation) to all affected entities. For each extended object, it sends MKI_NOTIFY_EXT_MODIFY to the responsible plug-in. The plug-in can either perform the operation by itself (returning MKI_NOTIFY_RESULT_DONE) or tell the application to directly apply the operation to the extended object's display matrix (returning MKI_NOTIFY_RESULT_IGNORE).

5.After all entities were modified, the application sends MKI_NOTIFY_MODIFY_FINISH to all affected plug-ins to tell them that the operation is done.

If the Duplicate option were active instead of inactive ("copying"), there is only one change: In step 3, two copies of each entity will be created, so MKI_NOTIFY_EXT_CREATE will be sent twice as often.

If the operation was canceled (by the user or due to an error such as lack of memory), step 5 would send MKI_NOTIFY_MODIFY_CANCEL instead of MKI_NOTIFY_MODIFY_FINISH. The plug-in can usually handle both of them identically since the application will take care of cleaning up (in the result of which the plug-in may receive MKI_NOTIFY_EXT_HIDE and/or MKI_NOTIFY_EXT_DESTROY messages).

If the operation was finished and, at any later time, the user chooses to undo the operation, this is what will happen:

A.All original, unmodified objects that were marked as hidden become visible again, a MKI_NOTIFY_EXT_SHOW will be sent for each of them.

B.All newly created, modified objects that were marked as created become invisible, a MKI_NOTIFY_EXT_HIDE will be sent for each of them.

After several operations (once the maximum number of undo steps is reached), objects marked as invisible during an operation will reach their end of life and will be permanently deleted and removed from memory. For each of them, a MKI_NOTIFY_EXT_DESTROY will be sent prior to actually deleting them.