Adding a Menu Item

Pressing the right mouse button upon the Menu Item Tree brings up the popupmenu. New menu items can be inserted by selecting Add command from the menu. Menu item can also be added by pressing Insert button when the Menu Item Tree has the focus.

Command Type

A Command type must be defined for each item. Type must be selected from the Command Type combobox and it can be one of following values

Identifier and Display Name

A Display name is required for each item except separator items. Character '&amp' is not displayed and means that the next character after it will be an underlined shortcut key.

Display name can also be defined using the resource filename and resource Id. For instance, string #RsrcFileName#RsrcId means that a resource string with identifier RsrcId from a resource file RsrcFileName must be loaded.

Each Menu Item should have an unique identifier within a parent menu item.

If the unique identifier is the same as one of ProjectWise menu macros (in string format) this command will replace ProjectWise Explorer's standard menu command. If command replaces ProjectWise standard command and display name (or help text) is left empty, then the default display name (help text) is used.

See Menu Definitions for the list of Standard Menu Identifiers.

To remove ProjectWise standard menu command, one can set Unique Item Identifier to the standard menu command identifier and set the ignore mask for it.

Often it is more appropriate to use hook function instead of replacing command using the menu editor. See ProjectWise SDK Reference for more information about hook functions and their prototypes. For example if it is desired to execute custom function every time document is deleted the hook function is appropriate for the case. When using menu replacement the custom function is executed only when document delete is selected from ProjectWise menu. When using hook function (hook identifier is AAHOOK_DELETE_DOCUMENT) the custom function will be called every time aaApi_DeleteDocument() function is called (not matter if it is called by menu command or if it is called directly).

DLL Name, Function Name, and Help text

The command specific text, appearing in ProjectWise Explorer's Status Bar, can be defined for each command item (project, document or generic command).

If an "Ole Automation DLL" check box is not checked, then the "DLL Name" editbox contains the filename (without path) of a DLL containing the function. The "Function Name" editbox contains the name of exported function to be executed when the menu item command is executed.

If an "Ole Automation DLL" check box is checked then the "Class Name" editbox contains the name of an OLE Automation Class owning the function. The "Function Name" editbox contains the name of a public function to be executed by specified menu item.

All ProjectWise menu items are maintained at a runtime by the ProjectWise Menu Registry. If "Long Parameter List" check box is checked then the first function's parameter (document, project or generic command) is the menu registry handle and the second is section handle of the menu item. The menu item section can be accessed by ProjectWise registry functions.

Function prototypes

Below there are examples of functions prototypes called by specified menu commands. For all functions the following return values are valid:

Return values:

	0	The command completed successfully
	IDCANCEL	The operation was cancelled by the user
	<0	For added commands, a negative value indicates an error occurred while performing the operation. For a command that replaces a standard ProjectWise menu command, a negative value indicates that the default ProjectWise command was executed.

The prototype for a Generic Command, short parameter list (standard dll and OLE Automation dll):

int WINAPI CustomGenericCmd ( void );

The prototype for a Generic Command, long parameter list (standard dll and OLE Automation dll):

int WINAPI CustomGenericCmd
(
void*     hRegistry,
unsigned long hCommand
);

The prototype for a Project Command, short parameter list (standard dll and OLE Automation dll):

int WINAPI CustomProjectCmd
(
long  project_no
);

The prototype for a Project Command, long parameter list (standard dll and OLE Automation dll):

int WINAPI CustomProjectCmd
(
void*  hRegistry,
unsigned long hCommand,
long   project_no
);

The prototype for a Document Command, short parameter list (standard dll):

int WINAPI CustomDocumentCmd
(
unsigned int count,
long*  pProjects,
long*  pDocuments
);

The prototype for a Document Command, long parameter list (standard dll):

int WINAPI CustomDocumentCmd
(
void*     hRegistry,
unsigned long hCommand,
unsigned int count,
long*     pProjects,
long*     pDocuments
);

The prototype for a Document Command, short parameter list (OLE Automation dll):

int WINAPI CustomDocumentCmd
(
VARIANT*  project_array,
VARIANT*  document_array
);

The prototype for a Document Command, long parameter list (OLE Automation dll):

int WINAPI CustomDocumentCmd
(
void*     hRegistry,
unsigned long hCommand,
VARIANT*   project_array,
VARIANT*   document_array
);

Ignore Mask, Required Mask, and State Function

Required mask and Ignored mask can be defined for each command item or popup item. These bit masks are affecting menu item visibility at runtime. The masks can be defined in the mask dialog.

Menu item is displayed if each bit in required mask is valid and none of ignore mask's bits are valid at the moment the menu is called.

Mask can be zero or it can contain one or more of following mask bits:

(For each bit it is defined a command type the bit can be used with. D - document, P - Folder, G - Generic)

Example

To make a menu item visible when there is one logical set selected check in the required mask "Document Set Selected" and "Logical Set" bits and in the ignored mask check "More than One" bit.

State function prototype

int WINAPI CustomStateFunction
(
UINT uiCmdId,
ULONG ulState
);

Parameters:

[in]	uiCmdId	Standard ProjectWise menu command identifier.
[in]	ulState	State mask. It can be a combination of the document select flags

Return values:

	0	The command will be displayed.
	AAMS_UNDEFINED	Indicates error.
	AAMS_*	One of the Menu Item State Flags