MKI_PlugInCommand (Callback) Changed in Version 2023.1

www.CAD6.com

C++ Syntax

__int32

MKI_PlugInCommand(

__int32 f_nCommandID,

__int32 f_nExecMode,

void* f_pData );

typedef __int32

(*MKI_PLUGINCOMMAND_PROC)(

__int32 f_nCommandID,

__int32 f_nExecMode,

void* f_pData );

This procedure is called each time the user selects a command of this plug-in by either selecting it in the menu, in the popup menu, via the toolbox or by pressing a key assigned to the command. It may also be called if the user loads or saves a drawing or actives another drawing.

Parameters

f_nCommandID

[__int32] The meaning of this value depends on the specified f_nExecMode. The following list shows all meanings depending on the value of f_nExecMode:

MKI_EXECMODE_USER

MKI_EXECMODE_SYSTEM

MKI_EXECMODE_HELP

MKI_EXECMODE_MENU_INIT

f_nCommandID identifies the plug-in command selected by the user. The value of f_nCommandID is either zero (if the plug-in has only one command without a submenu) or a value between one and the number of commands listed in the f_pCommandData array of the plug-in's MKI_PLUGIN_ID structure.

MKI_EXECMODE_BUTTON_HELP New in Version 2023.1

MKI_EXECMODE_BUTTON_LCLICK Renamed in Version 2023.1

MKI_EXECMODE_BUTTON_MCLICK Renamed in Version 2023.1

MKI_EXECMODE_BUTTON_RCLICK Renamed in Version 2023.1

f_nCommandID identifies the plug-in button clicked by the user. The value of f_nCommandID is a value between zero and the number of commands listed in the f_pButtonData array of the plug-in's MKI_PLUGIN_ID structure minus 1.

MKI_EXECMODE_UNDO

MKI_EXECMODE_REDO

f_nCommandID is the undo count that shall be restored, i.e. the undo count that was valid when the plug-in stored the corresponding undo or redo information.

MKI_EXECMODE_CLEAR_UNDO

f_nCommandID is the lower undo count window border.

MKI_EXECMODE_INTERFACE New in Version 2013.0

It's up to you to document all possible interface commands (i.e. recognized values of f_nCommandID and their meaning).

MKI_EXECMODE_GET_PROFILE

MKI_EXECMODE_SET_PROFILE

MKI_EXECMODE_STATUS

MKI_EXECMODE_READY

MKI_EXECMODE_RUNNING

f_nCommandID is unused.

MKI_EXECMODE_LOAD_COMPLETE New in Version 2019.1

f_nCommandID is 0 if either a complete drawing was loaded or a new drawing was created, and 1 for a merging or pasting operation (in which case all new objects merged / pasted have MKI_FLAG_PREVIOUS set in their header flag).

If the plug-in is either an import or export filter, f_nCommandID will always be zero except for MKI_EXECMODE_INTERFACE.

f_nExecMode

[__int32] This value indicates what action has to be performed concerning the specified command or drawing. Possible values are:

MKI_EXECMODE_USER

The command identified by f_nCommandID has been selected by the user and shall be started now. If the command requires parameter input before being able to start, those parameters have to be edited now!

If the plug-in is either an import or export filter, only the parameter dialog shall be displayed, no further action shall be performed.

MKI_EXECMODE_SYSTEM

The command identified by f_nCommandID is restarted by the serving application, e.g. after another temporary command has been executed. In this case, parameters should not be edited before starting the command!

If the plug-in is either an import or export filter, no action shall be performed at all.

MKI_EXECMODE_HELP

The user wants to view the help text for the command identified by f_nCommandID.

If the plug-in is either an import or export filter, the help file index shall be displayed.

MKI_EXECMODE_GET_PROFILE

The user is currently loading a new drawing, the plug-in should now read any plug-in-related data from the current drawing. At this time, only the header has been loaded, objects and blocks are not yet in memory!

MKI_EXECMODE_SET_PROFILE

The user wants to save the drawing, so the plug-in should now write any plug-in-related data to the drawing in memory which will then be part of the drawing file written.

MKI_EXECMODE_MENU_INIT

The serving application needs to know whether the menu entry corresponding to f_nCommandID shall be checked or grayed.

MKI_EXECMODE_STATUS

Used by the serving application or other plug-ins to request this plug-in’s status.

MKI_EXECMODE_READY New in Version 6.21

Notification from the serving application that all plug-ins have been loaded and initialized. It is now possible to enumerate all plug-ins and to establish inter-plug-in links or references. Do not display dialogs unless absolutely necessary. If so, please make sure to make any dialog or message box "topmost" (e.g. by stating MB_TOPMOST with the MessageBox call). For standard dialog display, please wait for the MKI_EXECMODE_RUNNING notification.

Note: That the serving application itself is not yet fully operational, i.e. most interface commands will not work at this time. Any changes to the plug-in's data will become effective automatically since neither menus nor command structures have been built yet.

MKI_EXECMODE_BUTTON_HELP New in Version 2023.1

Help for the button identified by f_nCommandID has been requested by the user by pressing F1.

MKI_EXECMODE_BUTTON_LCLICK Renamed in Version 2023.1

The button identified by f_nCommandID has been selected by the user using the left mouse button.

MKI_EXECMODE_BUTTON_MCLICK Renamed in Version 2023.1

The button identified by f_nCommandID has been selected by the user using the middle mouse button.

MKI_EXECMODE_BUTTON_RCLICK Renamed in Version 2023.1

The button identified by f_nCommandID has been selected by the user using the right mouse button.

MKI_EXECMODE_UNDO New in Version 6.30

The user has called the "undo" command, and the plug-in shall now restore any undo-related data for the resulting undo count in f_nCommandID.

MKI_EXECMODE_REDO New in Version 6.30

The user has called the "redo" command, and the plug-in shall now restore any redo-related data for the resulting undo count in f_nCommandID.

MKI_EXECMODE_CLEAR_UNDO New in Version 6.30

The undo count "window" has moved. The plug-in should delete any undo information for undo counts that are either smaller than f_nCommandID or larger than Data.

MKI_EXECMODE_RUNNING New in Version 6.40

Notification from the serving application that it is now fully operational, i.e. all plug-ins have been loaded and initialized, all menus have been created, and all interface commands can be used.

Note: Do not load a drawing at this time if another one is already in memory, i.e. check if the first character of the current drawing's filename is MKI_CHAR_SYSTEM ('*').

MKI_EXECMODE_INTERFACE New in Version 2013.0

Another plug-in wants to access a custom interface command of this plug-in. Use this value to implement any kind of externally accessible functions that other plug-ins may access.

It's up to you to document all possible interface commands (i.e. recognized values of f_nCommandID and their meaning) and if Data must point to a specific type of data.

MKI_EXECMODE_LOAD_COMPLETE New in Version 2019.1

Informs the plug-in that the user has loaded a new drawing, created a new drawing, or merged / pasted objects from the clipboard or a different drawing (see description of f_nCommandID). This is the time to check all of this plug-in's extended objects for possible unique IDs or such and fix them if necessary.

f_pData New in Version 6.30

The interpretation depends on the value of f_nExecMode:

MKI_EXECMODE_USER Changed in Version 2013.2

For import and export filters:

[__int32] If zero, the filter shall display the options dialog for loading or saving, respectively. If nonzero, the filter shall display the options dialog for importing or exporting, respectively. If the options are the same in both cases, ignore this value.

For all other plug-ins:

[void*] Unused, will usually be nullptr.

MKI_EXECMODE_LBUTTON

MKI_EXECMODE_MBUTTON

MKI_EXECMODE_RBUTTON

[MKI_INTRECT_PTR] Address of a MKI_INTRECT containing the surrounding rectangle of the button in screen coordinates. This can e.g. be used to display a tracking popup menu next to the button.

MKI_EXECMODE_CLEAR_UNDO

[__int32] Upper undo count window border.

MKI_EXECMODE_RUNNING

[HWND] Handle of the application's main window.

MKI_EXECMODE_INTERFACE New in Version 2013.0

[void*] It's up to you to document if Data must point to a specific type of data based on f_nCommandID.

MKI_EXECMODE_SYSTEM

MKI_EXECMODE_HELP

MKI_EXECMODE_GET_PROFILE

MKI_EXECMODE_SET_PROFILE

MKI_EXECMODE_MENU_INIT

MKI_EXECMODE_STATUS

MKI_EXECMODE_READY

MKI_EXECMODE_UNDO

MKI_EXECMODE_REDO

MKI_EXECMODE_LOAD_COMPLETE New in Version 2019.1

[void*] Unused, will usually be nullptr.

Return Value

The interpretation of the return value depends on the current f_nExecMode:

MKI_EXECMODE_USER

Should return any non-zero value if the task has been finished (or at least initialized) successfully, else zero if not.

MKI_EXECMODE_MENU_INIT

Should return either MF_CHECKED (menu item shall be checked), MF_GRAYED (menu item shall be grayed), zero (menu item is active, but not checked), or any bit-wise OR combination of these values.

MKI_EXECMODE_STATUS

Should return any non-zero value if the plug-in is fully initialized and working (i.e. the serving application or another plug-in may call its other callback functions), else zero if not.

MKI_EXECMODE_INTERFACE New in Version 2013.0

Must return a non-zero value if the interface command was syntactically correct and thus executed (no matter if successfully or not), else zero if not. If you need to return more detailed information on an interface command's outcome, please include a corresponding status value to the data type pointed to by Data for that command.

MKI_EXECMODE_SYSTEM

MKI_EXECMODE_LBUTTON

MKI_EXECMODE_MBUTTON

MKI_EXECMODE_RBUTTON

MKI_EXECMODE_GET_PROFILE

MKI_EXECMODE_SET_PROFILE

MKI_EXECMODE_HELP

MKI_EXECMODE_READY

MKI_EXECMODE_UNDO

MKI_EXECMODE_REDO

MKI_EXECMODE_CLEAR_UNDO

MKI_EXECMODE_RUNNING

MKI_EXECMODE_LOAD_COMPLETE New in Version 2019.1

The return value is ignored, should be zero.

Comment

The name of the procedure has to be exactly MKI_PlugInCommand. For an example of MKI_PlugInCommand, see the Basic Plug-In Code.