SDK:Menu Command Plug-in Resources

From Vectorworks Developer
Revision as of 15:39, 12 August 2013 by Root (talk | contribs) (1 revision)
Jump to navigation Jump to search

.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 Definition Resource

All plug-in menus are defined by their MITM 128 resource, which is contained in the plug-in menu file.

This resource is an extension of the item format used in MMNU resources so they don’t have to be parsed separately. As such, the MITM structure contains some data that is unused. The fields described below are used by chunks. All other fields should be 0.

MITM

Definition

type 'MITM' {
   unsigned integer;	/* needs flags */
   unsigned integer;	/* needs not flags */
   pstring;		/* title */
   decimal integer;	/* command ID */
   decimal byte;	/* icon ID */
   unsigned hex byte;	/* chunk flags (should be unsigned) */
   decimal byte;	/* key equivalent */
   unsigned hex byte;	/* key flags (unused) */
   decimal byte;	/* mark char or sub-menu ID */
   hex byte;		/* style flags */
   unsigned longint;	/* product flags */
   unsigned integer;	/* mode flags */
   unsigned integer;	/* version created */
   unsigned integer;	/* version modified */
   unsigned integer;	/* version retired */
};

Example

resource 'MITM' (128, "VWPluginWiz1Menu") {
    /* needs flags */			0x00,
    /* needs not flags */		0x00,
    /* title */				"VWPluginWiz1 Menu:Samples",
    /* command ID */			0,
    /* icon ID */			0,
    /* chunk flags (unsigned) */	0x00,
    /* key equivalent */		0,
    /* key flags (unused) */		0x00,
    /* mark char or sub-menu ID */	0,
    /* style flags */			0x00,
    /* product flags */			0,
    /* mode flags */			0,
    /* version created */		0,
    /* version modified */		0,
    /* version retired */		0
};

Fields

The fields of the MITM resource are defined as follows:

Needs and NeedsNot

Note The MITM resources has to be 128 for the plug-in to be recognized as menu command.

These two fields each contain one word of flags, which determine the default highlighting behavior of the menu item. Needs specifies conditions which must exist for the menu item to be available, and NeedsNot specifies conditions which must not exist. The meaning of each bit of the two flag fields is identical:

Bit Meaning
0 VectorWorks Document is active.
1 Reserved
2 Reserved
3 Reserved
4 Reserved
5 Reserved
6 Reserved
7 There are one or more objects selected.
8 There is more than one object selected.
9 The selection contains at least one 2D object.
10 The selection contains at least one 3D object.
11 The current layer is in plan projection.
12 Reserved
13 Reserved
14 Reserved
15 Reserved

If Needs = 0 and NeedsNot = 0 then the item is always active.

If Needs and NeedsNot both have a corresponding flag set, the item is always inactive. The reserved flags should not be set and in particular Needs = 0xFFFF and NeedsNot = 0xFFFF is a reserved setting.

You may wish to inspect the flag fields for VectorWorks’ internal menu items by using ResEdit and inspecting the MITM resources in the VectorWorks application.

For menu chunks, the Needs and NeedsNot flags will enable and disable every item in the chunk.

Before the selected menu bar is displayed to the user, kMenuCheckHilight actions are sent to all chunks so that they can modify the checked or hilighted state of each of their items.

Title

This string determines which name the user will see when in VectorWorks or Workspace Editor, and is also the string that can be changed to localize the plug-in for other languages.

The actual file name of the plug-in should never be changed, however, because this is how VectorWorks finds the plug-in.

commandID

These are private fields used by VectorWorks and should always be 0.

Chunk

This flag indicates that this menu function implements a menu chunk.

Has Option Equivalent

Unused flag that should be set to False or 0.

Dynamic

This indicates that the chunk is built on the fly rather than being stored in an MMNU resource.

The Dynamic flag only applies to chunks.

Variable

This flag indicates that the chunk can change size while VectorWorks is running. This flag only applies to dynamic chunks. Variable chunks can be placed only at the end of a menu in the Workspace Editor.

Reserved

These four flags are reserved for future use and should be set to False or 0.

iconID

keyEquivalent

keyFlags

mark Char/ sub menu id

style flags

The MITM resource describes a data structure that is a superset of Apple’s item definition contained in the variable length data section of a MENU resource (see “Inside Macintosh: Toolbox Essentials” page 3-154).

As such, the MITM fields with the same name as fields in the MENU usually have the same meaning.

However, in the case of icons, there is a subtle difference. Inside Macintosh states that the iconID should equal the icon’s resource ID -256. In an MITM, though, the iconID should equal the icon’s ID.

For plain chunks (not dynamic), the “mark Char/ sub menu id” field of the MITM must contain the resource id of an MMNU resource which defines the titles of the chunk’s menu items.

For dynamic chunks this field should be 0.

chunk

dynamic

variable

To specify that your menu command accepts one of the extended message sets, set the appropriate flags to true. If your menu command is a chunk, but not variable or dynamic, then you will also need to provide a MMNU resource that describes the items in your chunk. Also, you will need to set the mark Char field to the ID of your MMNU.

Version Created

This field should contain the version number for which the menu item was created. For example, 11 signifies VectorWorks 11, 13 signifies VectorWorks 2008.

This information will be used by the Workspace Editor so that a user may see at a glance all of the new menu items.

Version Modified

This field should contain the version number for which an existing menu item was significantly modified. For example, 11 signifies VectorWorks 11, 13 signifies VectorWorks 2008.

Although not used currently, this information could be used by the Workspace Editor so that a user may see at a glance all of the modified menu items.

Version Retired

This field should contain the version number for which an existing menu item was retired or replaced. For example, 11 signifies VectorWorks 11, 13 signifies VectorWorks 2008.

This information will be used by the Workspace Editor so that a user may see at a glance all of the retired menu items.

MMUN

Defines a menu chunk items.

Definitions

type 'MMNU' {
   decimal      integer;       // Menu ID
   fill         long;
   decimal      integer;       // ID of menu def proc
   fill         word;
   unsigned hex longint;       // needs not flags 
   pstring;                    // Menu Title
   wide array {
      pstring;                 // Item title
            decimal integer;   // command ID 
            decimal byte;      // Icon number
            unsigned hex byte; // Item Flags
            decimal byte;      // key/heirarchical
            unsigned hex byte; // key flags
            decimal byte;      // Marking char or hierarchical
            unsigned hex byte; // Style
      };
      byte = 0;
};

Example

resource 'MITM' (128, "VWPluginWiz1Menu") {
    ...
    /* mark char or sub-menu ID */	64,
    ...
};
resource 'MMNU' (64, "VWPluginWiz1Menu_Chunk") {
    /* Menu ID */		128,
    /* ID of menu def proc */	0,
    /* needs not flags */	0x00,
    /* Menu Title */		"",
    {
        /*  Item title, command ID, Icon number,
         *  Item Flags, key/heirarchical, key flags,
         *  Marking char or hierarchical, Style */
        "item 1...", 0, 0, 0x00, 0, 0x00, 0, 0x00,
        "item 2...", 0, 0, 0x00, 0, 0x00, 0, 0x00,
        "item 3...", 0, 0, 0x00, 0, 0x00, 0, 0x00
    }
};

Fields

See Also

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