도구 설명 컨트롤 정보

  • 아티클

도구 설명은 사용자가 도구나 다른 UI 요소 위에 마우스 포인터를 놓으면 자동으로 나타나거나 팝업됩니다. 도구 설명은 포인터 근처에 나타나며 사용자가 마우스 단추를 클릭하거나 포인터를 도구에서 이동하거나 몇 초 동안 기다리면 사라집니다.

다음 그림의 도구 설명 컨트롤은 Windows 바탕 화면에 있는 파일에 대한 정보를 표시합니다. 그림 위로 마우스를 놓으면 설명 텍스트가 포함된 라이브 도구 설명도 표시되어야 합니다.

screen shot showing text in a tooltip that appears over a file on the desktop

이 섹션에서는 도구 설명 컨트롤이 작동하는 방식과 컨트롤을 만드는 방법에 대해 설명합니다.

도구 설명 동작 및 모양

도구 설명 컨트롤은 한 줄의 텍스트 또는 여러 줄을 표시할 수 있습니다. 모서리는 둥글거나 정사각형일 수 있습니다. 만화 말풍선과 같은 도구를 가리키는 줄기가 있을 수도 있고 없을 수도 있습니다. 도구 설명 텍스트는 고정되어 있거나 추적이라고 하는 마우스 포인터와 함께 이동할 수 있습니다. 고정 텍스트는 도구 옆에 표시되거나 현재 위치라고 하는 도구 위에 표시될 수 있습니다. 표준 도구 설명은 고정되어 있고 한 줄의 텍스트를 표시하며 모서리가 정사각형이고 도구를 가리키는 줄기가 없습니다.

공용 컨트롤의 버전 4.70에서 지원하는 추적 도구 설명은 화면에서 위치를 동적으로 변경합니다. 위치를 빠르게 업데이트하면 이러한 도구 설명 컨트롤이 부드럽게 이동하거나 "추적"하는 것처럼 보입니다. 마우스 포인터가 움직일 때 도구 설명 텍스트가 마우스 포인터의 위치를 따르도록 하려는 경우에 유용합니다. 추적 도구 설명에 대한 자세한 내용과 이를 만드는 방법을 보여 주는 코드의 예는 추적 도구 설명을 참조하세요.

공용 컨트롤의 버전 4.70에서도 지원되는 여러 줄 도구 설명은 텍스트를 두 줄 이상에 표시합니다. 긴 메시지를 표시하는 데 유용합니다. 자세한 내용과 여러 줄 도구 설명을 만드는 방법을 보여 주는 예는 여러 줄 도구 설명을 참조하세요.

풍선 도구 설명은 둥근 모서리와 도구를 가리키는 줄기가 있는 상자에 표시됩니다. 한 줄 또는 여러 줄일 수 있습니다. 다음 그림에서는 줄기와 직사각형이 기본 위치에 있는 풍선 도구 설명을 보여 줍니다. 풍선 도구 설명에 대한 자세한 내용과 이를 만드는 방법을 보여 주는 예는 도구 설명 컨트롤 사용을 참조하세요.

screen shot showing a tooltip containing one line of text, positioned above a button on a dialog box

도구 설명에는 다음 그림과 같이 제목 텍스트와 아이콘이 있을 수도 있습니다. 도구 설명에는 텍스트가 있어야 합니다. 제목 텍스트만 있으면 도구 설명이 표시되지 않습니다. 또한 제목이 없으면 아이콘이 나타나지 않습니다.

screen shot showing a tooltip with an icon, title, and text, positioned below a button on a dialog box

텍스트 문자열이 너무 길어서 작은 창에 완전히 표시할 수 없기 때문에 텍스트 문자열이 잘리는 경우가 있습니다. 현재 위치 도구 설명은 다음 그림의 파일 이름과 같이 잘린 개체에 대한 텍스트 문자열을 표시하는 데 사용됩니다. 현재 위치 도구 설명을 만드는 방법을 보여 주는 예는 현재 위치 도구 설명을 참조하세요.

screen shot showing a tooltip containing a file name positioned next to a file icon in a tree control

도구 설명이 표시되기 전에 커서는 일정 시간 동안 툴을 가리키고 있어야 합니다. 이 제한 시간의 기본 기간은 사용자의 더블 클릭 시간에 의해 제어되며 일반적으로 약 0.5초입니다. 기본이 아닌 시간 제한 값을 지정하려면 도구 설명 컨트롤에 TTM_SETDELAYTIME 메시지를 보냅니다.

도구 설명 컨트롤 만들기

도구 설명 컨트롤을 만들려면 CreateWindowEx를 호출하고 TOOLTIPS_CLASS 창 클래스를 지정합니다. 이 클래스는 공용 컨트롤 DLL이 로드될 때 등록됩니다. 이 DLL이 로드되도록 하려면 애플리케이션에 InitCommonControlsEx 함수를 포함합니다. 도구 설명 컨트롤을 최상위로 명시적으로 정의해야 합니다. 그렇지 않으면 부모 창에 가려질 수 있습니다. 다음 코드 조각은 도구 설명 컨트롤을 만드는 방법을 보여 줍니다.

HWND hwndTip = CreateWindowEx(NULL, TOOLTIPS_CLASS, NULL,
                            WS_POPUP | TTS_NOPREFIX | TTS_ALWAYSTIP,
                            CW_USEDEFAULT, CW_USEDEFAULT,
                            CW_USEDEFAULT, CW_USEDEFAULT,
                            hwndParent, NULL, hinstMyDll,
                            NULL);

SetWindowPos(hwndTip, HWND_TOPMOST,0, 0, 0, 0,
             SWP_NOMOVE | SWP_NOSIZE | SWP_NOACTIVATE);

도구 설명 컨트롤의 창 프로시저는 컨트롤의 크기, 위치 및 표시 유형을 자동으로 설정합니다. 도구 설명 창의 높이는 도구 설명 컨트롤에 대한 디바이스 컨텍스트로 현재 선택된 글꼴의 높이를 기반으로 합니다. 너비는 현재 도구 설명 창에 있는 문자열의 길이에 따라 달라집니다.

도구 설명 컨트롤 활성화

도구 설명 컨트롤은 활성 또는 비활성일 수 있습니다. 활성화되면 마우스 포인터가 도구 위에 있을 때 도구 설명 텍스트가 나타납니다. 비활성화되면 포인터가 도구 위에 있더라도 도구 설명 텍스트가 나타나지 않습니다. TTM_ACTIVATE 메시지는 도구 설명 컨트롤을 활성화 및 비활성화합니다.

지원 도구

도구 설명 컨트롤은 여러 도구를 지원할 수 있습니다. 특정 도구를 지원하려면 컨트롤에 TTM_ADDTOOL 메시지를 전송하여 도구 설명 컨트롤에 도구를 등록해야 합니다. 메시지에는 TOOLINFO 구조체의 주소가 포함되어 있으며 도구 설명 컨트롤이 도구에 대한 텍스트를 표시하는 데 필요한 정보를 제공합니다. TOOLINFO 구조체의 uID 멤버는 애플리케이션에 의해 정의됩니다. 도구를 추가할 때마다 애플리케이션에서 고유 식별자를 제공합니다. TOOLINFO 구조체의 cbSize 멤버가 필요하며 구조체의 크기를 지정해야 합니다.

도구 설명 컨트롤은 창(예: 자식 창 또는 컨트롤 창) 및 창의 클라이언트 영역 내의 사각형 영역으로 구현된 도구를 지원합니다. 직사각형 영역으로 구현된 도구를 추가할 때 TOOLINFO 구조체의 hwnd 멤버는 영역을 포함하는 창에 대한 핸들을 지정해야 하며 rect 멤버는 영역 경계 사각형의 클라이언트 좌표를 지정해야 합니다. 또한 uID 멤버는 도구에 대한 애플리케이션 정의 식별자를 지정해야 합니다.

창으로 구현된 도구를 추가할 때 TOOLINFO 구조체의 uID 멤버는 도구에 대한 창 핸들을 포함해야 합니다. 또한 uFlags 멤버는 uID 멤버를 창 핸들로 해석하도록 도구 설명 컨트롤에 지시하는 TTF_IDISHWND 값을 지정해야 합니다.

텍스트 표시

도구 설명 컨트롤에 도구를 추가할 때 TOOLINFO 구조체의 lpszText 멤버는 도구에 대해 표시할 문자열의 주소를 지정해야 합니다. 도구를 추가한 후 TTM_UPDATETIPTEXT 메시지를 사용하여 텍스트를 변경할 수 있습니다.

lpszText의 상위 단어가 0이면 하위 단어는 문자열 리소스의 식별자여야 합니다. 도구 설명 컨트롤에 텍스트가 필요한 경우 시스템은 TOOLINFO 구조체의 hinst 멤버로 식별되는 애플리케이션 인스턴스에서 지정된 문자열 리소스를 로드합니다.

lpszText 멤버에 LPSTR_TEXTCALLBACK 값을 지정하면 도구 설명 컨트롤은 도구 설명 컨트롤이 도구에 대한 텍스트를 표시해야 할 때마다 TOOLINFO 구조체의 hwnd 멤버에 지정된 창에 알립니다. 도구 설명 컨트롤이 TTN_GETDISPINFO 알림 코드를 창으로 보냅니다. 메시지에는 NMTTDISPINFO 구조체의 주소가 포함되어 있으며 창 핸들과 도구에 대한 애플리케이션 정의 식별자가 포함되어 있습니다. 창에서 텍스트가 필요한 도구를 결정하기 위해 구조체를 검사하고 도구 설명 컨트롤이 문자열을 표시하는 데 필요한 정보로 적절한 구조체 멤버를 채웁니다.

참고

표준 도구 설명 텍스트의 최대 길이는 80자입니다. 자세한 내용은 NMTTDISPINFO 구조체를 참조하세요. 여러 줄 도구 설명 텍스트는 더 길 수 있습니다.

 

많은 애플리케이션은 메뉴 명령에 해당하는 도구를 포함하는 도구 모음을 만듭니다. 이러한 도구의 경우 도구 설명 컨트롤이 해당 메뉴 항목과 동일한 텍스트를 표시하는 것이 편리합니다. 컨트롤에 TTS_NOPREFIX 스타일이 있는 경우가 아니면 시스템이 도구 설명 컨트롤에 전달된 모든 문자열에서 앰퍼샌드(&) 가속기 문자를 자동으로 제거하고 첫 번째 탭 문자(\t)에서 문자열을 종료합니다.

도구에 대한 텍스트를 검색하려면 TTM_GETTEXT 메시지를 사용합니다.

메시징 및 알림

도구 설명 텍스트는 일반적으로 마우스 포인터가 영역, 일반적으로 단추 컨트롤과 같은 도구로 정의된 사각형을 가리키고 있을 때 표시됩니다. 그러나 Microsoft Windows는 도구 설명 컨트롤 자체가 아니라 포인터가 포함된 창에 마우스 관련 메시지만 보냅니다. 도구 설명 컨트롤이 적절한 시간과 장소에 도구 설명 텍스트를 표시하려면 마우스 관련 정보가 도구 설명 컨트롤에 전달되어야 합니다.

다음과 같은 경우 메시지가 자동으로 릴레이되도록 할 수 있습니다.

  • 도구가 컨트롤이거나 도구의 TOOLINFO 구조체에서 직사각형으로 정의됩니다.
  • 도구와 연결된 창이 도구 설명 컨트롤과 동일한 스레드에 있습니다.

이 두 조건이 충족되면 TTM_ADDTOOL로 도구 설명 컨트롤에 도구를 추가할 때 도구 TOOLINFO 구조체의 uFlags 멤버에 TTF_SUBCLASS 플래그를 설정합니다. 그러면 필요한 마우스 메시지가 도구 설명 컨트롤에 자동으로 전달됩니다.

마우스 메시지가 컨트롤에 전달되도록 TTF_SUBCLASS를 설정하면 대부분의 목적에 충분합니다. 그러나 도구 설명 컨트롤과 도구 창 사이에 직접적인 연결이 없는 경우에는 작동하지 않습니다. 예를 들어, 도구가 애플리케이션 정의 창에서 사각형 영역으로 구현된 경우 창 프로시저는 마우스 메시지를 받습니다. TTF_SUBCLASS를 설정하면 컨트롤에 전달될 수 있습니다. 그러나 도구가 시스템 정의 창으로 구현된 경우 마우스 메시지는 해당 창으로 전송되며 애플리케이션에서 직접 사용할 수 없습니다. 이 경우 창을 하위 클래스로 지정하거나 메시지 후크를 사용하여 마우스 메시지에 액세스해야 합니다. 그런 다음 TTM_RELAYEVENT를 사용하여 도구 설명 컨트롤에 마우스 메시지를 명시적으로 전달해야 합니다. TTM_RELAYEVENT 사용 방법의 예는 추적 도구 설명을 참조하세요.

도구 설명 컨트롤이 WM_MOUSEMOVE 메시지를 받으면 마우스 포인터가 도구의 경계 사각형에 있는지 여부를 확인합니다. 그렇다면 도구 설명 컨트롤이 타이머를 설정합니다. 시간 초과 간격이 끝나면 도구 설명 컨트롤이 포인터의 위치를 확인하여 포인터가 이동했는지 확인합니다. 그렇지 않은 경우 도구 설명 컨트롤이 도구에 대한 텍스트를 검색하고 도구 설명을 표시합니다. 도구 설명 컨트롤이 릴레이된 단추 업 또는 단추 다운 메시지를 수신하거나 WM_MOUSEMOVE 메시지가 포인터가 도구의 경계 사각형 밖으로 이동했음을 나타낼 때까지 창을 계속 표시합니다.

도구 설명 컨트롤에는 실제로 세 가지 제한 시간이 연결되어 있습니다. 초기 지속 시간은 도구 설명 창이 표시되기 전에 도구의 경계 사각형 내에서 마우스 포인터가 고정되어 있어야 하는 시간입니다. 다시 표시 기간은 포인터가 한 도구에서 다른 도구로 이동할 때 후속 도구 설명 창이 표시되기 전에 지연되는 길이입니다. 팝업 기간은 도구 설명 창이 숨겨지기 전에 표시된 상태로 유지되는 시간입니다. 즉, 도구 설명 창이 표시된 후 경계 사각형 내에서 포인터가 고정되어 있으면 팝업 기간이 끝날 때 도구 설명 창이 자동으로 숨겨집니다. TTM_SETDELAYTIME 메시지를 사용하여 모든 시간 초과 기간을 조정할 수 있습니다.

애플리케이션에 직사각형 영역으로 구현된 도구가 포함되어 있고 컨트롤의 크기나 위치가 변경되는 경우 애플리케이션이 TTM_NEWTOOLRECT 메시지를 사용하여 도구 설명 컨트롤에 변경 내용을 보고할 수 있습니다. 도구 설명 컨트롤은 마우스 포인터가 도구의 경계 사각형이 아니라 도구 위에 있는지 확인하기 위해 도구의 창 핸들을 사용하기 때문에 애플리케이션이 창으로 구현된 도구에 대한 크기 및 위치 변경을 보고할 필요가 없습니다.

도구 설명이 표시되려고 할 때 도구 설명 컨트롤이 소유자 창에 TTN_SHOW 알림 코드를 보냅니다. 소유자 창은 도구 설명이 숨겨지려고 할 때 TTN_POP 알림 코드를 받습니다. 각 알림 코드가 WM_NOTIFY 메시지 컨텍스트에서 전송됩니다.

적중 테스트

TTM_HITTEST 메시지를 사용하면 도구 설명 컨트롤이 특정 지점을 차지하는 도구에 대해 유지 관리하는 정보를 검색할 수 있습니다. 메시지에는 창 핸들, 점의 좌표 및 TOOLINFO 구조체의 주소가 포함된 TTHITTESTINFO 구조체가 포함됩니다. 도구 설명 컨트롤은 도구가 점을 차지하는지 여부를 결정하고 점유하는 경우 도구에 대한 정보로 TOOLINFO를 채웁니다.

기본 메시지 처리

다음 표에서는 도구 설명 컨트롤에 대한 창 프로시저에서 처리하는 메시지를 설명합니다.

메시지 Description
WM_CREATE 도구 설명 컨트롤에 WS_EX_TOOLWINDOW 및 WS_POPUP 창 스타일이 있는지 확인합니다. 또한 메모리를 할당하고 내부 변수를 초기화합니다.
WM_DESTROY 도구 설명 컨트롤에 할당된 리소스를 해제합니다.
WM_GETFONT 도구 설명 컨트롤이 텍스트를 그리는 데 사용할 글꼴의 핸들을 반환합니다.
WM_MOUSEMOVE 도구 설명 창을 숨깁니다.
WM_PAINT 도구 설명 창을 그립니다.
WM_SETFONT 도구 설명 컨트롤이 텍스트를 그리는 데 사용할 글꼴의 핸들을 설정합니다.
WM_TIMER 도구의 위치가 변경되었거나 마우스 포인터가 도구 밖으로 이동한 경우 도구 설명 창을 숨깁니다. 그렇지 않으면 도구 설명 창이 표시됩니다.
WM_WININICHANGE 시스템 메트릭을 기반으로 하는 내부 변수를 초기화합니다.