TrackPopupMenuEx 함수(winuser.h)

아티클
03/04/2024

지정된 위치에 바로 가기 메뉴를 표시하고 바로 가기 메뉴에서 항목 선택을 추적합니다. 바로 가기 메뉴는 화면의 아무 곳에나 나타날 수 있습니다.

구문

BOOL TrackPopupMenuEx(
  [in]           HMENU       hMenu,
  [in]           UINT        uFlags,
  [in]           int         x,
  [in]           int         y,
  [in]           HWND        hwnd,
  [in, optional] LPTPMPARAMS lptpm
);

매개 변수

[in] hMenu

형식: HMENU

표시할 바로 가기 메뉴에 대한 핸들입니다. 이 핸들은 CreatePopupMenu 함수를 호출하여 새 바로 가기 메뉴를 만들거나 GetSubMenu 함수를 호출하여 기존 메뉴 항목과 연결된 하위 메뉴에 대한 핸들을 검색하여 가져올 수 있습니다.

[in] uFlags

형식: UINT

함수 옵션을 지정합니다.

다음 플래그 중 하나를 사용하여 함수가 바로 가기 메뉴를 가로로 배치하는 방법을 지정합니다.

값	의미
TPM_CENTERALIGN 0x0004L	x 매개 변수에서 지정한 좌표를 기준으로 바로 가기 메뉴를 가로로 가운데에 맞춥다.
TPM_LEFTALIGN 0x0000L	바로 가기 메뉴를 배치하여 왼쪽이 x 매개 변수로 지정된 좌표에 맞춰지도록 합니다.
TPM_RIGHTALIGN 0x0008L	오른쪽이 x 매개 변수로 지정된 좌표에 맞춰지도록 바로 가기 메뉴를 배치합니다.

다음 플래그 중 하나를 사용하여 함수가 바로 가기 메뉴를 세로로 배치하는 방법을 지정합니다.

값	의미
TPM_BOTTOMALIGN 0x0020L	바로 가기 메뉴를 배치하여 아래쪽이 y 매개 변수로 지정된 좌표와 정렬되도록 합니다 .
TPM_TOPALIGN 0x0000L	y 매개 변수로 지정된 좌표와 위쪽이 정렬되도록 바로 가기 메뉴를 배치합니다.
TPM_VCENTERALIGN 0x0010L	y 매개 변수에 지정된 좌표를 기준으로 바로 가기 메뉴를 세로로 가운데에 지정 합니다.

메뉴에 대한 부모 창을 설정하지 않고도 다음 플래그를 사용하여 사용자 선택 검색을 제어합니다.

값	의미
TPM_NONOTIFY 0x0080L	사용자가 메뉴 항목을 클릭할 때 함수는 알림 메시지를 보내지 않습니다.
TPM_RETURNCMD 0x0100L	함수는 반환 값에서 사용자 선택 영역의 메뉴 항목 식별자를 반환합니다.

다음 플래그 중 하나를 사용하여 바로 가기 메뉴가 추적하는 마우스 단추를 지정합니다.

값	의미
TPM_LEFTBUTTON 0x0000L	사용자는 마우스 왼쪽 단추만 사용하여 메뉴 항목을 선택할 수 있습니다.
TPM_RIGHTBUTTON 0x0002L	사용자는 마우스 왼쪽 단추와 오른쪽 단추가 모두 있는 메뉴 항목을 선택할 수 있습니다.

다음 플래그의 적절한 조합을 사용하여 메뉴의 애니메이션을 수정합니다. 예를 들어 가로 및 세로 플래그를 선택하면 대각선 애니메이션을 얻을 수 있습니다.

값	의미
TPM_HORNEGANIMATION 0x0800L	오른쪽에서 왼쪽으로 메뉴에 애니메이션 효과를 적용합니다.
TPM_HORPOSANIMATION 0x0400L	왼쪽에서 오른쪽으로 메뉴에 애니메이션 효과를 적용합니다.
TPM_NOANIMATION 0x4000L	애니메이션 없이 메뉴를 표시합니다.
TPM_VERNEGANIMATION 0x2000L	메뉴에 아래쪽에서 위쪽으로 애니메이션 효과를 적용합니다.
TPM_VERPOSANIMATION 0x1000L	메뉴에서 위쪽에서 아래쪽으로 애니메이션 효과를 적용합니다.

애니메이션이 발생하려면 SystemParametersInfo 함수가 SPI_SETMENUANIMATION 설정해야 합니다. 또한 메뉴 페이드 애니메이션이 켜진 경우 TPM_NOANIMATION 제외한 모든 TPM_*ANIMATION 플래그가 무시됩니다. 자세한 내용은 SystemParametersInfo의 SPI_GETMENUFADE 플래그를 참조하세요.

다른 메뉴가 이미 표시된 경우 TPM_RECURSE 플래그를 사용하여 메뉴를 표시합니다. 이는 메뉴 내의 상황에 맞는 메뉴를 지원하기 위한 것입니다.

다음 플래그 중 하나를 사용하여 가로 맞춤 또는 세로 맞춤을 수용할지 여부를 지정합니다.

값	의미
TPM_HORIZONTAL 0x0000L	제외된 사각형과 겹치지 않고 지정된 위치에 메뉴를 표시할 수 없는 경우 시스템은 요청된 세로 맞춤 전에 요청된 가로 맞춤을 수용하려고 합니다.
TPM_VERTICAL 0x0040L	제외된 사각형과 겹치지 않고 지정된 위치에 메뉴를 표시할 수 없는 경우 시스템은 요청된 가로 맞춤 전에 요청된 세로 맞춤을 수용하려고 시도합니다.

제외된 사각형은 메뉴가 겹치지 않아야 하는 화면의 일부입니다. lptpm 매개 변수에 의해 지정됩니다.

오른쪽에서 왼쪽 텍스트 레이아웃의 경우 TPM_LAYOUTRTL 사용합니다. 기본적으로 텍스트 레이아웃은 왼쪽에서 오른쪽입니다.

[in] x

형식: int

화면 좌표에서 바로 가기 메뉴의 가로 위치입니다.

[in] y

형식: int

화면 좌표에서 바로 가기 메뉴의 세로 위치입니다.

[in] hwnd

형식: HWND

바로 가기 메뉴를 소유하는 창에 대한 핸들입니다. 이 창은 메뉴에서 모든 메시지를 받습니다. 함수가 반환될 때까지 창은 메뉴에서 WM_COMMAND 메시지를 받지 않습니다. fuFlags 매개 변수에서 TPM_NONOTIFY 지정하는 경우 함수는 hwnd로 식별된 창에 메시지를 보내지 않습니다. 그러나 여전히 hwnd에서 창 핸들을 전달해야 합니다. 애플리케이션의 모든 창 핸들일 수 있습니다.

[in, optional] lptpm

형식: LPTPMPARAMS

메뉴가 겹치지 않아야 하는 화면 영역을 지정하는 TPMPARAMS 구조체에 대한 포인터입니다. 이 매개 변수는 NULL일 수 있습니다.

반환 값

형식: BOOL

fuFlags 매개 변수에서 TPM_RETURNCMD 지정하는 경우 반환 값은 사용자가 선택한 항목의 메뉴 항목 식별자입니다. 사용자가 선택하지 않고 메뉴를 취소하거나 오류가 발생하는 경우 반환 값은 0입니다.

fuFlags 매개 변수에 TPM_RETURNCMD 지정하지 않으면 함수가 성공하면 반환 값이 0이 아니고 실패하면 0이 됩니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.

설명

SM_MENUDROPALIGNMENT GetSystemMetrics를 호출하여 올바른 가로 맞춤 플래그(TPM_LEFTALIGN 또는 TPM_RIGHTALIGN) 및/또는 가로 애니메이션 방향 플래그(TPM_HORPOSANIMATION 또는 TPM_HORNEGANIMATION)를 확인하여 TrackPopupMenu 또는 TrackPopupMenuEx에 전달합니다. 이는 특히 Microsoft 태블릿 PC 애플리케이션을 개발할 때 최적의 사용자 환경을 만드는 데 필수적입니다.

알림 아이콘에 대한 상황에 맞는 메뉴를 표시하려면 애플리케이션이 TrackPopupMenu 또는 TrackPopupMenuEx를 호출하기 전에 현재 창이 포그라운드 창이어야 합니다. 그렇지 않으면 사용자가 메뉴 외부를 클릭하거나 메뉴를 만든 창(표시되는 경우)을 클릭하면 메뉴가 사라지지 않습니다. 현재 창이 자식 창인 경우 (최상위) 부모 창을 포그라운드 창으로 설정해야 합니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 2000 Professional[데스크톱 앱만]
지원되는 최소 서버	Windows 2000 Server[데스크톱 앱만]
대상 플랫폼	Windows
헤더	winuser.h(Windows.h 포함)
라이브러리	User32.lib
DLL	User32.dll
API 세트	ext-ms-win-ntuser-menu-l1-1-1(Windows 8.1 소개)