툴팁 컨트롤에 대한 정보

도구 설명은 사용자가 도구 또는 다른 UI 요소 위에 마우스 포인터를 일시 중지할 때 자동으로 표시되거나 팝업됩니다. 도구 설명은 포인터 근처에 나타나고 사용자가 마우스 단추를 클릭하거나 도구에서 포인터를 이동하거나 몇 초 동안 기다리면 사라집니다.

다음 그림의 도구 설명 컨트롤은 Windows 데스크톱의 파일에 대한 정보를 표시합니다. 그림 위로 마우스를 이동하면 설명 텍스트가 포함된 라이브 도구 설명도 표시됩니다.

바탕 화면의 파일 위에 표시되는 도구 설명의 텍스트를 보여 주는

이 섹션에서는 툴팁 컨트롤의 작동 방식과 만드는 방법을 설명합니다.

• 도구 설명 동작 및 모양
• 도구 설명 컨트롤 만들기
• 도구 설명 컨트롤 활성화
• 지원 도구
• 텍스트 표시하기
• 메시징 및 알림
• 적중 테스트
• 기본 메시지 처리

도구 설명 동작 및 모양

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

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

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

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

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

아이콘, 제목, 텍스트가 있는 툴팁을 보여주는 스크린샷

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

커서가 일정 시간 동안 도구 위에 위치해야 도구 설명이 표시됩니다. 이 시간 제한의 기본 기간은 사용자의 두 번 클릭 시간에 의해 제어되며 일반적으로 약 1/2초입니다. 기본이 아닌 시간 제한 값을 지정하려면 도구 설명 컨트롤에 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 구조체의 주소가 포함됩니다. 창은 텍스트가 필요한 도구를 결정하기 위해 구조를 검사하고, 문자열을 표시하기 위해 도구 설명 컨트롤에 필요한 정보로 적절한 구조체 멤버를 채웁니다.

많은 애플리케이션은 메뉴 명령에 해당하는 도구가 포함된 도구 모음을 만듭니다. 이러한 도구의 경우 도구 설명 컨트롤이 해당 메뉴 항목과 동일한 텍스트를 표시하는 것이 편리합니다. 시스템은 도구 설명 컨트롤에 전달된 모든 문자열에서 앰퍼샌드(&) 액셀러레이터 문자를 자동으로 제거하고 컨트롤에 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에 채웁니다.

기본 메시지 처리

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