SetRightButtonMenu method
Creates a menu to be displayed when the user clicks the right mouse button in the document window.
- Method
- short SetRightButtonMenu(
- Parameters
- pMenuData
- Specifies the data to be used to create a menu. If this parameter is null, any existing menu is deleted.
- pErrorPosition
- Points to a variable to receive an error position if the menu cannot be created. In that case, the variable is set to type VT_I4.
- Description
- This menu replaces any existing menu. The format of the menu is
determined by the data specified by the pMenuData parameter.
Complex menus containing commands, separators, and submenus can be
created.
The menu data consists of a set of menu items separated by a newline character (X'0A'). There can be a maximum of ARS_OLE_MAX_MENU_ITEMS items, each of which can contain no more than ARS_OLE_MAX_MENU_ITEM_LEN characters. The items must appear in the order in which they are to be displayed in the menu.
Each item is described by keywords and values. A keyword and its associated value must be separated by an equal sign. Each keyword/value pair must be separated by at least one space. The recognized keywords are:- level
- A number that indicates the nesting level of the item. The first
item must be level 0 (zero). Each subsequent nesting level must add
1 (one). The nesting level can be increased only when specifying a
popup submenu.
This keyword must be provided.
- id
- The user command number to be associated with the item. The ID
is the number that is reported for the UserCommand event when the
user chooses that menu item. Two special IDs are defined:
- If ID is specified as ARS_OLE_MENU_ID_SEPARATOR, a separator item is created.
- If ID is specified as ARS_OLE_MENU_ID_POPUP, a popup submenu is created. In this case, the following item should have a level one greater that the level specified for this item.
This keyword must be provided.
- enabled
- The enabled keyword must have a value of 1 (one) or 0 (zero).
If 1 (one), the item is enabled; if 0 (zero), disabled.
This keyword is optional and is ignored for separator items. The default is for the item to be enabled.
- checked
- The checked keyword must have a value of 1 (one) or
0 (zero). If 1 (one), the item is checked; if 0 (zero), clear.
This keyword is optional and is ignored for separator items. The default is for the item to be clear.
- text
- The text keyword specifies the text of the item. The text, which might include embedded blanks,
must be contained in single quotation marks. If a single quote is part of the
text, two consecutive single quotation marks must be specified.
The text might contain the normal Windows special characters, such as an & (ampersand) to indicate that the following character is to be underlined.
This keyword is optional and is ignored for separator items.
If the menu data is not valid, an error position is returned through the pErrorPosition parameter. The position is zero-based and is relative to the first character of the menu data. The position will normally identify the first character of the item which contains an error.
The following examples show the use of the keywords.
Data Menu level=0 id=368 text='Copy Text'
level=0 id=44 text='Item1'\n
level=0 id=1\n
level=0 id=45 text='Item2'
level=0 id=32457 text='Item1'\n
level=0 id=0 text='Popup1'\n
level=1 id=32458 text='Item2'\n
level=1 id=32459 text='Item3'\n
level=0 id=1\n
level=0 id=0 text='Popup2'\n
level=1 id=32460 enabled=0 text='Item4'\n
level=1 id=1\n
level=1 id=32461 checked=1 text='Item5'
- Return Value
- Refer to return codes.
- See Also
- UserCommand event
C/C + +
The following example shows how to create a right button menu that contains the command Copy Text. CArsOle * pArsCtrl;
short rc;
VARIANT var;
.
.
.
rc = pArsCtrl->SetRightButtonMenu( "level=0 id=368 text='Copy Text'", var );
if ( rc != ARS_OLE_RC_SUCCESS )
ERROR;
.
.Visual Basic
Dim rc As Integer
Dim var As Variant
.
.
rc = ArsOle.SetRightButtonMenu ("level=0 id=368 text='Copy Text'", var)
If rc <> ARS_OLE_RC_SUCCESS Then
MsgBox "ERROR"
End
End If