SDK:Menu Command Plug-in Events

.SDK|SDK ..SDK:Types|SDK Types ..SDK:Using the SDK|Using the SDK ..VCOM:VCOM (Vectorworks Component Object Model)|VCOM Basics ..VCOM:Class Reference|VCOM Class Reference

Menu Command Events

The menu command main function will be called by VectorWorks, and will be passed one of several values for the action parameter indicating the task to be performed. Basic and Chunk menu commands must respond to the following values for the action parameter:

kMenuInitGlobals

A workspace containing the plug-in has been loaded. This is the plug-in’s opportunity to allocate and initialize all persistent data. A Macintosh handle to the data should be assigned to the userData parameter so that it can be used later for other actions. The message parameter is unused. This action should always return 0. This action will not be called again until a kMenuDisposeGlobals is passed.

kMenuDisposeGlobals

A workspace containing the plug-in has been deselected. The menu command should finalize all outstanding actions and free any allocated data and resources. The message parameter is unused. This action should always return 0.

kMenuDoInterface

The user has selected the menu command. The menu command should take whatever action is appropriate to implement its functionality. For basic menu commands the message parameter is unused. For chunks, the message parameter is a pointer to a MenuChunkInfo structure with the following fields:

mc->menuID;     // Menu id of the menu containing this chunk
mc->itemID;     // Item number of item before chunk’s first item
mc->chunkIndex; // Index of the chunk item selected
                // where 1 is first chunk item.
mc->modifiers;  // Modifiers from the mousedown event

Chunks should avoid using the modifier field because it may prevent the chunk from being called by a VectorScript.

The menu command should return kMenuDidNotChangeDoc if it did not change the document (this allows VectorWorks to activate and deactivate the save command when appropriate).

Chunks receive the following additional action values:

kMenuItemEnabled

This action occurs when the menu item is called from a VectorScript using the DoMenuTextByName procedure. This action allows the system to efficiently determine whether a given menu item is enabled in order to return appropriate errors when the menu function is called from VectorScript or some other script system.

The message parameter is 0 if this is a basic menu item or the chunk index of the desired item if it’s a chunk. You should examine the message parameter, efficiently determine whether this item is enabled or disabled, and return kMenuItemEnabled or kMenuItemDisabled. If the chunk index is not legal, (for example if it’s larger than the number of items in your chunk), return kMenuNoSuchItem.

kMenuCheckHilite

When the user clicks in the menu bar, this action is sent to all chunks in the menu system to allow them to prepare for display to the user. You can set the enabled state, set check marks, and change the text style for any or all of the items in your chunk. If your chunk is variable, you can delete items or add VectorWorks SDK Manual 12 new items in response to the current state of the drawing. You can use any standard menu manager routines to set up your chunk for display to the user.

Since all this must happen after the user clicks the mouse but before the menu is displayed, this is a time critical section of code. You should make every effort to avoid doing unnecessary work when you get this action.

The message parameter is a pointer to a MenuChunkInfo structure with the following fields:

mc->menuID;    // The menu id of the menu containing this chunk
mc->itemID;    // The itemID of the first item in the chunk
mc->chunkSize; // The number of items in this chunk
mc->modifiers; // The modifiers from the mousedown event

Return true if this call is necessary, false otherwise. (Return true if any items were disabled.)

Note: Avoid using the modifiers field of the MenuChunkInfo. Your menu item cannot be called correctly from VectorScript or other script systems if it depends on this information.

Warning: The resource fork of your plug-in file is not open when your code gets this message (for speed reasons). Your code cannot load resources from its file or make calls to code outside the main segment. This is a severe restriction, so be very careful when implementing the code for this action.

kMenuNotify

This action notifies the menu chunk that a particular VectorWorks internal event has occurred. The menu must have previously registered for the notification. This is typically done in the kMenuInitGlobals action. For example, to register for the “Document Changed” notification you would call:

GS_RegisterMenuForCallback(cbp,GS_GetMyMenuCommandIndex(cbp),'DOCC');

The menu will continue to receive a kMenuNotify action every time the active document changes until it unregisters by calling the function:

GS_UnregisterMenuForCallback(cbp,GS_GetMyMenuCommandIndex(cbp),'DOCC');

Using SDK:GS_RegisterMenuForCallback, SDK:GS_UnregisterMenuForCallback and SDK:GS_GetMyMenuCommandIndex to register the callback.

The message parameter for this action indicates which event has occurred. The message is a 32-bit value of type OSType that can be represented as a four-character code. For example, the menu can test the message value as follows:

if (message == 'DOCC') {
    (*(MyInfoHandle)userData)->needsDocRebuild = true;
}

The menu can respond to the notification immediately or it can set a global flag for use later (as shown in the example above). Often it is best to postpone any significant work until it is required.

This action should always return 0.

Warning: The resource fork of your plug-in file is not open when your code gets this message (for speed reasons). Your code cannot load resources from its file or make calls to code outside the main segment. This is a severe restriction, so be very careful when implementing the code for this action.

kMenuAddItems

The menu that contains this chunk has been constructed up to the item before your chunk. Add any items you want in your chunk to the end of this menu.

This action is only passed to dynamic and variable-dynamic chunks. Basic menu commands and plain chunks do not receive this action. It occurs once, immediately after kMenuInitGlobals and before any other action. If a variable-dynamic chunk can determine all of its items at this point it should do so.

The message parameter is a pointer to a MenuChunkInfo structure with the fields:

mc->menuID;     // Menu id of the menu containing this chunk
mc->itemID;     // Item number of item before the chunk’s first item VectorWorks SDK Manual 13
mc->chunkIndex; // unused
mc->modifiers;  // unused

Typecast the message parameter and then use it to retrieve the MenuHandle to your menu. Using this handle, you can add your chunk’s items to the end of the menu with AppendMenu as follows:

MenuChunkInfoPtr mc = (MenuChunkInfoPtr) message;
MenuHandle myMenu = GetMenuHandle(mc->menuID);
AppendMenu(myMenu, "\pItem One");
AppendMenu(myMenu, "\pItem Two");
AppendMenu(myMenu, "\pItem Three");

If you would like to display the special characters ; ! > / ( in your menu item, you must use the following technique:

AppendMenu(myMenu, "\pdummy");
SetItem(myMenu, mc->itemID+1, "\pCalculate miles / gallon");

This action should always return 0.

If the items in your variable-dynamic chunk can change during the execution of VectorWorks then the MenuHandle can be updated during the kMenuCheckHilite action.

Note: Very few of Diehl Graphsoft’s menu commands are implemented as chunks, as the basic behavior is almost always sufficient.

See Also

Overview | SDK:Menu Command Plug-in Resources | SDK:Menu Command Plug-in Main Function | SDK:Menu Command Plug-in Events