DspPopupMenu

Creates a popup menu consisting of a number of menu items. Multiple calls to this function enable you to add new items and create sub menus, building a system of linked, Windows-style menus.

Menu items can be displayed as checked and/or disabled. You can also specify a bitmap to display as a menu icon.

This function is first called to build the menu's items and links, and then called again to display it on the screen. In this final call, you have the option to specify the coordinates at which the menu will display, or let it default to the current cursor position.

Syntax

DspPopupMenu(iMenuNumber, sMenuItems [, XPos] [, YPos] )

iMenuNumber:

An integer representing the menu you are adding items to. The first menu created is Menu 0. If left unspecified, this parameter defaults to -1, causing the menu to be displayed on the screen.

Multiple function calls with the same iMenuNumber allow you to build up entries in a particular menu. For example, the following four function calls with iMenuNumber = 1 build up 8 entries in Menu 1:

• DspPopupMenu(1, "Selection A>2, Selection B>3");
• DspPopupMenu(1, "Selection C>2, Selection D");
• DspPopupMenu(1, "Selection E>2, Selection F>3");
• DspPopupMenu(1, "Selection G>2, Selection H");

sMenuItems:

A comma-separated string defining the items in each menu. The default value for this parameter is an empty string, which will get passed to the function in the call to display the menu.

The (!), (~), and (,) symbols control display options for menu items.

For example, !Item1 disables Item1; ~Item2 checks Item2; and ,Item3 inserts a separator above Item3. To insert a link from a menu item to a sub menu, use the (>) symbol. For example, : Item4>1 means Item4 links to menu 1.

To insert a bitmap to the left of a menu item as its icon, use the following notation: [Icon]Item5 Inserts the bitmap Icon.BMP to the left of Item5. [Icon] needs to be placed before the Item name, but after any disable (!) or check (~) symbols you may wish to specify.

Bitmap files used for menu icons need to be saved in the project directory so that they can be found by CitectSCADA.

XPos:

The x-coordinate (relative to the page) at which the menu will be displayed. This parameter is optional. If it is left unspecified, the menu will display at the cursor's current position.

YPos:

The y-coordinate (relative to the page) at which the menu will be displayed. This parameter is optional. If it is left unspecified, the menu will display at the cursor's current position.

Return Value

The selected menu item as an integer. This comprises the menu number (return value div 100), and the position of the item in the menu (return value mod 100). For example, a return value of 201 indicates that the first item in Menu 2 was selected, and a return value of 3 indicates that the third item in Menu 0 was selected.

The return value is limited to a maximum of 65535, that is 655 menus and 35 items on the menu. Above this limit the function returns 0.

Example1

!Example 1 illustrates one menu with three menu items.

FUNCTION BuildPopupMenus()

	INT iSelection;

	DspPopupMenu(0, "Item 1,!Item 2,~Item 3");

	iSelection = DspPopupMenu(-1, "", 150, 300);

	! The above builds a menu with three items:

	! 'Item 1' will be shown as normal, 'Item 2' will be shown as disabled,

	! and 'Item 3' will be shown as checked.

	! The menu will be displayed at position (150, 300).

END

Example 2

!Example 2 illustrates the creation of two menus which are linked. 

FUNCTION BuildLinkedPopupMenus()

	INT iSelection;

	DspPopupMenu(0, "Item A,Item B>1,Item C");

	DspPopupMenu(1, "Item B1,,[Trend]Item B2,,Item B3");

	iSelection = DspPopupMenu();

	! The above will build two menus - Menu 0 and Menu 1

	! Item B on Menu 0 links to Menu 1.

	! 'Item B2' will be shown with Trend.BMP at its left.

	! The menu will be displayed at the cursor's position.

	! If 'Item A' is selected, iSelection will equal 1

	! If 'Item C' is selected, iSelection will equal 2

	! If 'Item B1' is selected, iSelection will equal 101

	! If 'Item B2' is selected, iSelection will equal 102

	! If 'Item B3' is selected, iSelection will equal 103

END

See Also

Display Functions