TrackPopupMenuEx Function

Declare Function TrackPopupMenuEx Lib "user32.dll" (ByVal hMenu As Long, ByVal fuFlags As Long, ByVal x As Long, ByVal y As Long, ByVal hwnd As Long, lptpm As TPMPARAMS) As Long

Platforms

Description & Usage

TrackPopupMenuEx displays a popup menu at a specified point. The function also tracks the menu, updating the selection highlight until the user either selects an item or otherwise closes the menu. By default, the function sends a WM_COMMAND message to the parent window, notifying it of the selection. However, flags specified in the fuFlags parameter can change this behavior.

Return Value

If fuFlags contains the TPM_RETURNCMD flag, the function returns the identifier of the menu item that the user selected. If an error occurs or the user does not select an item, the function instead returns 0.

If fuFlags does not contain the TPM_RETURNCMD flag, the function returns a nonzero value if the function is successful. If an error occured, the function returns 0. Regardless of fuFlags, use the GetLastError to get the error code.

Visual Basic-Specific Issues

None.

Parameters

hMenu
A handle to the popup menu to display and track.
fuFlags
A combination of the following flags specifying the positioning of the popup menu and other behavior of the function:
TPM_CENTERALIGN
Position the popup menu so that its horizontal center occurs at the coordinate specified by x.
TPM_LEFTALIGN
Position the popup menu so that its left edge occurs at the coordinate specified by x.
TPM_RIGHTALIGN
Position the popup menu so that its right edge occurs at the coordinate specified by x.
TPM_BOTTOMALIGN
Position the popup menu so that its bottom edge occurs at the coordinate specified by y.
TPM_TOPALIGN
Position the popup menu so that its top edge occurs at the coordinate specified by y.
TPM_VCENTERALIGN
Position the popup menu so that its vertical center occurs at the coordinate specified by y.
TPM_NONOTIFY
Do not send a WM_COMMAND message to the popup menu's parent window to notify it of the user's selection.
TPM_RETURNCMD
Have TrackPopupMenuEx return the identifier of the menu item that the user selected.
TPM_LEFTBUTTON
Only allow the user to select a menu item using the left mouse button (or the keyboard).
TPM_RIGHTBUTTON
Allow the user to select a menu item using either mouse button (or the keyboard).
TPM_HORIZONTAL
If the popup menu cannot be shown at the desired coordinates without intruding upon the exclusion rectangle, preserve the horizontal positioning instead of the vertical.
TPM_VERTICAL
If the popup menu cannot be shown at the desired coordinates without intruding upon the exclusion rectangle, preserve the vertical positioning instead of the horizontal.
x
The x-coordinate of the point where the popup menu is to be displayed, relative to the screen.
y
The y-coordinate of the point where the popup menu is to be displayed, relative to the screen.
hwnd
A handle to the window that owns the popup menu. This window will receive the WM_COMMAND message. The window must be specified even if fuFlags contains the TPM_NONOTIFY flag.
lptpm
Specified additional information about the positioning of the popup menu, specifically regarding the exclusion rectange. The exclusion rectangle is a region of the screen in which the popup menu will not appear.

Constant Definitions

Const TPM_CENTERALIGN = &H4
Const TPM_LEFTALIGN = &H0
Const TPM_RIGHTALIGN = &H8
Const TPM_BOTTOMALIGN = &H20
Const TPM_TOPALIGN = &H0
Const TPM_VCENTERALIGN = &H10
Const TPM_NONOTIFY = &H80
Const TPM_RETURNCMD = &H100
Const TPM_LEFTBUTTON = &H0
Const TPM_RIGHTBUTTON = &H2
Const TPM_HORIZONTAL = &H0
Const TPM_VERTICAL = &H40

Example

' This code is licensed according to the terms and conditions listed here.

' Declarations and such needed for the example:
' (Copy them to the (declarations) section of a module.)
Public Declare Function CreatePopupMenu Lib "user32.dll" () As Long
Public Declare Function DestroyMenu Lib "user32.dll" (ByVal hMenu As Long) As Long
Public Type MENUITEMINFO
	cbSize As Long
	fMask As Long
	fType As Long
	fState As Long
	wID As Long
	hSubMenu As Long
	hbmpChecked As Long
	hbmpUnchecked As Long
	dwItemData As Long
	dwTypeData As String
	cch As Long
End Type
Public Const MIIM_STATE = &H1
Public Const MIIM_ID = &H2
Public Const MIIM_TYPE = &H10
Public Const MFT_SEPARATOR = &H800
Public Const MFT_STRING = &H0
Public Const MFS_DEFAULT = &H1000
Public Const MFS_ENABLED = &H0
Public Declare Function InsertMenuItem Lib "user32.dll" Alias "InsertMenuItemA" (ByVal _
	hMenu As Long, ByVal uItem As Long, ByVal fByPosition As Long, lpmii As _
	MENUITEMINFO) As Long
Public Type RECT
	left As Long
	top As Long
	right As Long
	bottom As Long
End Type
Public Type TPMPARAMS
	cbSize As Long
	rcExclude As RECT
End Type
Public Declare Function TrackPopupMenuEx Lib "user32.dll" (ByVal hMenu As Long, ByVal _
	fuFlags As Long, ByVal x As Long, ByVal y As Long, ByVal hWnd As Long, lptpm As _
	TPMPARAMS) As Long
Public Const TPM_LEFTALIGN = &H0
Public Const TPM_TOPALIGN = &H0
Public Const TPM_NONOTIFY = &H80
Public Const TPM_RETURNCMD = &H100
Public Const TPM_LEFTBUTTON = &H0
Public Type POINT_TYPE
	x As Long
	y As Long
End Type
Public Declare Function GetCursorPos Lib "user32.dll" (lpPoint As POINT_TYPE) As Long
Public Declare Function SetRectEmpty Lib "user32.dll" (lpRect As RECT) As Long

' When the user clicks button Command1, have a very simple popup menu appear.  The
' menu only has two options, divided by a separator bar.  The menu is created when
' needed and is destroyed after its use.

' The following application-defined constants are used to name the menu item
' identifiers used by this example.  They are not actually part of the API; instead, they are
' used just to eliminate "magic numbers."
Private Const ID_ABOUT = 101
Private Const ID_SEPARATOR = 102
Private Const ID_EXIT = 103

Private Sub Command1_Click()
	Dim hPopupMenu As Long    ' handle to the popup menu to display
	Dim mii As MENUITEMINFO   ' describes menu items to add
	Dim tpm As TPMPARAMS      ' identifies the exclusion rectangle
	Dim curpos As POINT_TYPE  ' holds the current mouse coordinates
	Dim menusel As Long       ' ID of what the user selected in the popup menu
	Dim retval As Long        ' generic return value
	
	' Create the popup menu that will be displayed.
	hPopupMenu = CreatePopupMenu()
	' Add the menu's first item: "About This Problem..."
	With mii
		' The size of this structure.
		.cbSize = Len(mii)
		' Which elements of the structure to use.
		.fMask = MIIM_STATE Or MIIM_ID Or MIIM_TYPE
		' The type of item: a string.
		.fType = MFT_STRING
		' This item is currently enabled and is the default item.
		.fState = MFS_ENABLED Or MFS_DEFAULT
		' Assign this item an item identifier.
		.wID = ID_ABOUT
		' Display the following text for the item.
		.dwTypeData = "&About This Example..."
		.cch = Len(.dwTypeData)
	End With
	retval = InsertMenuItem(hPopupMenu, 0, 1, mii)
	' Add the second item: a separator bar.
	With mii
		.fType = MFT_SEPARATOR
		.fState = MFS_ENABLED
		.wID = ID_SEPARATOR
	End With
	retval = InsertMenuItem(hPopupMenu, 1, 1, mii)
	' Add the final item: "Exit".
	With mii
		.fType= MFT_STRING
		.wID = ID_EXIT
		.dwTypeData = "E&xit"
		.cch = Len(.dwTypeData)
	End With
	retval = InsertMenuItem(hPopupMenu, 2, 1, mii)
	
	' Determine where the mouse cursor currently is, in order to have
	' the popup menu appear at that point.
	retval = GetCursorPos(curpos)
	
	' Make the exclusion rectangle empty because there's no need for it here.
	With tpm
		' Size of the structure.
		.cbSize = Len(tpm)
		' Make the exclusion rectangle empty.
		retval = SetRectEmpty(.rcExclude)
	End With
	
	' Display the popup menu at the mouse cursor.  Instead of sending messages
	' to window Form1, have the function merely return the ID of the user's selection.
	menusel = TrackPopupMenuEx(hPopupMenu, TPM_TOPALIGN Or TPM_LEFTALIGN Or TPM_NONOTIFY _
		Or TPM_RETURNCMD Or TPM_LEFTBUTTON, curpos.x, curpos.y, Form1.hWnd, tpm)
	
	' Before acting upon the user's selection, destroy the popup menu now.
	retval = DestroyMenu(hPopupMenu)
	Select Case menusel
	Case ID_ABOUT
		' Use the Visual Basic MsgBox function to display a short message in a dialog
		' box.  Using the MessageBox API function isn't necessary.
		retval = MsgBox("This example demonstrates how to use the API to display " & _
			 "a pop-up menu.", vbOkOnly Or vbInformation, "Windows API Guide")
	Case ID_EXIT
		' End this program by closing and unloading Form1.
		Unload Form1
	End Select
End Sub

See Also

TrackPopupMenu

Category

Menus

Back to the Function list.
Back to the Reference section.


Last Modified: June 4, 2000
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000
Go back to the Windows API Guide home page.
E-mail: vbapi@vbapi.com Send Encrypted E-Mail
This page is at http://www.vbapi.com/ref/t/trackpopupmenuex.html