Informacje o kontrolkach etykietki narzędzi

Podpowiedzi pojawiają się automatycznie, gdy użytkownik zatrzymuje wskaźnik myszy nad narzędziem lub innym elementem interfejsu użytkownika. Etykietka narzędzia pojawia się w pobliżu wskaźnika i znika, gdy użytkownik klika przycisk myszy, przenosi wskaźnik z dala od narzędzia lub po prostu czeka na kilka sekund.

Okienko podpowiedzi na poniższej ilustracji wyświetla informacje o pliku na pulpicie systemu Windows. Przesuwając mysz nad ilustrację, powinna zostać również wyświetlona etykieta narzędziowa na żywo zawierająca tekst opisowy.

W tej sekcji opisano działanie kontrolek etykietek narzędziowych i jak je tworzyć.

• zachowanie etykietki narzędzia i wygląd
• tworzenie kontrolek etykietek narzędzi
• aktywowanie kontrolek podpowiedzi
• narzędzia pomocnicze
• Wyświetlanie tekstu
• Wiadomości i Powiadomienia
• testowanie trafień
• domyślne przetwarzanie komunikatów

Zachowanie i wygląd etykietki narzędzia

Kontrolki etykietki narzędzi mogą wyświetlać pojedynczy wiersz tekstu lub wiele wierszy. Ich rogi mogą być zaokrąglone lub kwadratowe. Mogą mieć lub nie mieć trzonka, który wskazuje na narzędzia, takie jak dymek komiksowy. Tekst etykietki narzędzia może być nieruchomy lub może poruszać się wraz z wskaźnikiem myszy, nazywanym śledzeniem. Tekst nieruchomy może być wyświetlany obok narzędzia lub może być wyświetlany bezpośrednio na narzędziu, co określane jest jako osadzony. Standardowe etykietki narzędzi są nieruchome, wyświetlają pojedynczy wiersz tekstu, mają kwadratowe narożniki i nie mają elementu macierzystego wskazującego narzędzie.

Podpowiedzi śledzące, które są obsługiwane w wersji 4.70 typowych kontrolek , dynamicznie zmieniają położenie na ekranie. Dzięki płynnej aktualizacji położenia te kontrolki podpowiedzi wydają się przesuwać się bezproblemowo. Są one przydatne, gdy chcesz, aby tekst podpowiedzi śledził położenie wskaźnika myszy podczas jej przesuwania. Aby uzyskać więcej informacji na temat śledzenia etykietek narzędzi i przykład z kodem pokazujący, jak je tworzyć, zobacz Tracking Tooltips.

Wielowierszowe etykietki narzędzi, które są również obsługiwane przez wersję 4.70 wspólnych kontrolek, wyświetlają tekst w więcej niż jednym wierszu. Są one przydatne do wyświetlania długich komunikatów. Aby uzyskać więcej informacji i przykład tworzenia wieloliniowych etykiet narzędziowych, zobacz Wieloliniowe etykiety narzędziowe.

Etykietki narzędzi balonowych są wyświetlane w polu z zaokrąglonymi rogami i ogonkiem, który wskazuje na narzędzie. Mogą być jednowierszowe lub wielowierszowe. Na poniższej ilustracji przedstawiono dymkową etykietę narzędzia z ogonem i prostokątem w ich domyślnych pozycjach. Aby uzyskać więcej informacji na temat etykietek narzędzi balonowych i przykładu pokazującego sposób ich tworzenia, zobacz Using Tooltip Controls.

Etykietka narzędzia może również zawierać tekst tytułu i ikonę, jak pokazano na poniższej ilustracji. Należy pamiętać, że etykietka narzędzia musi zawierać tekst; jeśli zawiera tylko tekst tytułu, etykietka narzędzia nie jest wyświetlana. Ponadto ikona nie jest wyświetlana, chyba że istnieje tytuł.

Czasami ciągi tekstowe są obcięte, ponieważ są zbyt długie, aby były wyświetlane całkowicie w małym oknie. Wbudowane etykiety narzędzi służą do wyświetlania ciągów tekstowych dla obiektów, których zawartość została przycięta, takich jak nazwa pliku na poniższej ilustracji. Aby zapoznać się z przykładem tworzenia podpowiedzi kontekstowych, zobacz In-Place Etykietki narzędzi.

Kursor musi znajdować się nad narzędziem przez pewien czas, zanim zostanie wyświetlona etykietka. Domyślny czas trwania tego limitu czasu jest kontrolowany przez dwukrotny czas kliknięcia użytkownika i zazwyczaj wynosi około jednej połowy sekundy. Aby określić wartość limitu czasu innego niż domyślna, wyślij do kontrolki podpowiedzi komunikat TTM_SETDELAYTIME.

Tworzenie kontrolek etykietki narzędzi

Aby utworzyć kontrolkę etykietki narzędzi, wywołaj CreateWindowEx i określ klasę okna TOOLTIPS_CLASS. Ta klasa jest rejestrowana, gdy wspólna kontrolka DLL jest załadowana. Aby upewnić się, że ta biblioteka DLL jest załadowana, dołącz funkcję InitCommonControlsEx w aplikacji. Musisz jawnie zdefiniować kontrolkę etykietki narzędzia jako najbardziej górną. W przeciwnym razie może być zasłonięte przez okno nadrzędne. Poniższy fragment kodu pokazuje, jak utworzyć kontrolkę tooltip.

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);

Procedura okna kontrolki etykietki narzędzi automatycznie ustawia rozmiar, położenie i widoczność kontrolki. Wysokość okna etykietki narzędzia jest oparta na wysokości czcionki aktualnie wybranej w kontekście urządzenia dla kontrolki etykietki narzędzia. Szerokość różni się w zależności od długości ciągu tekstowego aktualnie w oknie podpowiedzi.

Aktywowanie kontrolek etykietki narzędzi

Kontrolka etykietki narzędzia może być aktywna lub nieaktywna. Gdy jest aktywny, tekst etykietki narzędzia jest wyświetlany, gdy wskaźnik myszy znajduje się na narzędziu. Gdy jest nieaktywny, tekst etykietki narzędzia nie jest wyświetlany, nawet jeśli wskaźnik znajduje się w narzędziu. Komunikat TTM_ACTIVATE aktywuje i dezaktywuje podpowiedź (tooltip).

Narzędzia pomocnicze

Kontrolka etykietki narzędzi może obsługiwać dowolną liczbę narzędzi. Aby obsługiwać określone narzędzie, należy zarejestrować narzędzie za pomocą kontrolki etykietki narzędzia, wysyłając kontrolce TTM_ADDTOOL komunikat. Komunikat zawiera adres struktury TOOLINFO, która zawiera informacje potrzebne kontrolce podpowiedzi do wyświetlania tekstu dla narzędzia. Struktura TOOLINFO , członek uID, jest definiowana przez aplikację. Za każdym razem, gdy dodasz narzędzie, aplikacja udostępnia unikatowy identyfikator. cbSize członek struktury TOOLINFO jest wymagany i musi określać rozmiar tej struktury.

Kontrolka podpowiedzi obsługuje narzędzia zaimplementowane jako okna (takie jak okna podrzędne lub okna sterowania) oraz jako prostokątne obszary w części klienta okna. Po dodaniu narzędzia zaimplementowanego jako prostokątny obszar, człon hwnd w strukturze TOOLINFO musi określić uchwyt okna zawierającego ten obszar, a człon rect musi ustalić współrzędne klienta prostokąta otaczającego obszar. Ponadto członek identyfikatora uID musi określić zdefiniowany przez aplikację identyfikator dla narzędzia.

Po dodaniu narzędzia zaimplementowanego jako okno identyfikator uID elementu członkowskiego TOOLINFO struktury musi zawierać uchwyt okna do narzędzia. Ponadto element członkowski uFlags musi określić wartość TTF_IDISHWND, która nakazuje kontrolce etykietki narzędzia interpretowanie elementu członkowskiego identyfikatora uID jako uchwyt okna.

Wyświetlanie tekstu

Po dodaniu narzędzia do kontrolki podpowiedzi, element członkowski lpszText struktury TOOLINFO musi określić adres ciągu do wyświetlenia dla narzędzia. Po dodaniu narzędzia możesz zmienić tekst przy użyciu komunikatu TTM_UPDATETIPTEXT.

Jeśli wyraz o wysokiej kolejności lpszText wynosi zero, wyraz o niskiej kolejności musi być identyfikatorem zasobu ciągu. Gdy kontrolka podpowiedzi potrzebuje tekstu, system ładuje określony zasób tekstowy z wystąpienia aplikacji, zidentyfikowanego przez element członkowski hinst struktury TOOLINFO.

Jeśli określisz wartość LPSTR_TEXTCALLBACK w elemencie członkowskim lpszText, kontrolka etykietki narzędzia powiadamia okno określone w elemencie członkowskim hwnd struktury TOOLINFOza każdym razem, gdy kontrolka etykietki narzędzia musi wyświetlić tekst dla narzędzia. Kontrolka wskazówkowa wysyła kod powiadomienia TTN_GETDISPINFO do okna. Komunikat zawiera adres struktury NMTTDISPINFO, która zawiera uchwyt okna oraz identyfikator zdefiniowany przez aplikację dla narzędzia. Okno sprawdza strukturę, aby określić narzędzie, dla którego jest potrzebny tekst, i wypełnia odpowiednie składowe struktury informacjami, których potrzebuje kontrolka dymku, aby wyświetlić ciąg.

Notatka

Maksymalna długość tekstu standardowej etykietki narzędzia to 80 znaków. Aby uzyskać więcej informacji, zobacz strukturę NMTTDISPINFO. Tekst wielowierszowej etykietki narzędzia może być dłuższy.

 

Wiele aplikacji tworzy paski narzędzi zawierające narzędzia odpowiadające poleceń menu. W przypadku takich narzędzi kontrolka etykietki narzędzi jest wygodna, aby wyświetlić ten sam tekst co odpowiedni element menu. System automatycznie usuwa znaki akceleratora ampersand (&) ze wszystkich ciągów przekazywanych do kontrolki podpowiedzi narzędziowej i kończy ciąg przy pierwszym znaku tabulacji (\t), chyba że kontrolka ma styl TTS_NOPREFIX.

Aby pobrać tekst narzędzia, użyj komunikatu TTM_GETTEXT.

Wiadomości i Powiadomienia

Tekst etykietki narzędzia jest zwykle wyświetlany, gdy wskaźnik myszy znajduje się nad obszarem, zazwyczaj prostokąt zdefiniowany przez narzędzie, takie jak kontrolka przycisku. Jednak system Microsoft Windows wysyła tylko komunikaty związane z myszą do okna zawierającego wskaźnik, a nie samą kontrolkę etykietki narzędzia. Informacje związane z myszą muszą być przekazywane do kontrolki etykietki narzędzia w celu wyświetlenia tekstu etykietki narzędzia w odpowiednim czasie i miejscu.

Komunikaty mogą być przekazywane automatycznie, jeśli:

• Narzędzie jest kontrolką lub jest definiowane jako prostokąt w strukturze narzędzia TOOLINFO.
• Okno skojarzone z narzędziem znajduje się w tym samym wątku co kontrolka podpowiedzi.

Jeśli te dwa warunki zostaną spełnione, ustaw flagę TTF_SUBCLASS w uFlags element członkowski TOOLINFO narzędzia struktury podczas dodawania narzędzia do kontrolki etykietki narzędzia za pomocą TTM_ADDTOOL. Niezbędne komunikaty myszy będą przekazywane automatycznie do kontrolki etykietki narzędzia.

Ustawienie TTF_SUBCLASS, aby komunikaty myszy były przekazywane do kontrolki, wystarcza w większości przypadków. Jednak nie będzie działać w przypadkach, gdy nie ma bezpośredniego połączenia między kontrolką etykietki narzędzia a oknem narzędzia. Jeśli na przykład narzędzie jest implementowane jako prostokątny obszar w oknie zdefiniowanym przez aplikację, procedura okna odbiera komunikaty myszy. Ustawienie TTF_SUBCLASS jest wystarczające, aby upewnić się, że są przekazywane do kontrolki. Jeśli jednak narzędzie jest implementowane jako okno zdefiniowane przez system, komunikaty myszy są wysyłane do tego okna i nie są bezpośrednio dostępne dla aplikacji. W takim przypadku musisz podklasować okno lub użyć haka komunikatów, aby uzyskać dostęp do komunikatów myszy. Następnie należy jawnie przekazać komunikaty myszy do kontrolki podpowiedzi za pomocą TTM_RELAYEVENT. Aby zobaczyć przykład użycia TTM_RELAYEVENT, proszę zobaczyć Tracking Tooltips.

Gdy kontrolka podpowiedzi narzędzia odbiera komunikat WM_MOUSEMOVE, określa, czy wskaźnik myszy znajduje się w prostokącie ograniczającym narzędzie. Jeśli tak jest, kontrolka etykietki narzędzi ustawia czasomierz. Na końcu przerwy czasowej kontrolka podpowiedzi sprawdza położenie wskaźnika, aby zobaczyć, czy został przeniesiony. Jeśli tak nie jest, kontrolka podpowiedzi pobiera tekst dla narzędzia i wyświetla podpowiedź. Kontrolka dymka narzędzia nadal wyświetla okno, dopóki nie otrzyma komunikatu o opuszczeniu lub naciśnięciu przycisku myszy, albo dopóki komunikat WM_MOUSEMOVE nie wskaże, że wskaźnik został przeniesiony poza prostokąt obramowania narzędzia.

Kontrolka etykietki narzędzia ma faktycznie trzy czasy trwania limitu czasu skojarzone z nim. Czas początkowy to czas, przez jaki wskaźnik myszy musi pozostać nieruchomy w obrębie prostokąta ograniczającego narzędzie, zanim zostanie wyświetlone okno podpowiedzi. Czas ponownego pokazu to długość opóźnienia przed wyświetleniem kolejnych okien etykietek narzędzi, gdy wskaźnik przechodzi z jednego narzędzia do drugiego. Czas wyświetlania okna podręcznego to czas wyświetlania okna etykietki narzędzia przed ukryciem. Oznacza to, że jeśli wskaźnik pozostaje nieruchomy w obrębie prostokąta obwiedni po wyświetleniu okna etykietki narzędzia, okno etykietki narzędzia jest automatycznie ukrywane po zakończeniu czasu wyświetlania. Możesz dostosować wszystkie czasy trwania limitu czasu, używając komunikatu TTM_SETDELAYTIME.

Jeśli aplikacja zawiera narzędzie zaimplementowane jako prostokątny obszar i rozmiar lub położenie kontrolki zmienia się, aplikacja może użyć komunikatu TTM_NEWTOOLRECT, aby zgłosić zmianę kontrolki etykietki narzędzia. Aplikacja nie musi zgłaszać zmian rozmiaru i położenia narzędzia zaimplementowanego jako okno, ponieważ kontrolka etykietki narzędzia używa uchwytu okna narzędzia w celu określenia, czy wskaźnik myszy znajduje się na narzędziu, a nie na prostokątie ograniczenia narzędzia.

Gdy etykietka narzędzia ma być wyświetlana, kontrolka etykietki narzędzia wysyła oknu właściciela kod powiadomienia TTN_SHOW. Okno właściciela otrzymuje kod powiadomienia TTN_POP, gdy etykietka narzędzia ma być ukryta. Każdy kod powiadomienia jest wysyłany w kontekście komunikatu WM_NOTIFY.

Testowanie trafień

Komunikat TTM_HITTEST umożliwia pobranie informacji, które kontrolka etykietki narzędzia utrzymuje na temat narzędzia zajmującego określony punkt. Komunikat zawiera strukturę TTHITTESTINFO, która obejmuje uchwyt okna, współrzędne punktu oraz adres struktury TOOLINFO. Kontrolka podpowiedzi określa, czy narzędzie przyjmuje punkt, a jeśli tak, wypełnia TOOLINFO informacjami o narzędziu.

Domyślne przetwarzanie komunikatów

W poniższej tabeli opisano komunikaty obsługiwane przez procedurę okna dla kontrolki etykietki narzędzia.

Komunikat	Opis
WM_CREATE	Gwarantuje, że kontrolka etykietki narzędzia posiada style okna WS_EX_TOOLWINDOW oraz WS_POPUP. Przydziela również pamięć i inicjuje zmienne wewnętrzne.
WM_DESTROY	Zwalnia zasoby przydzielone dla kontrolki etykietki narzędzia.
WM_GETFONT	Zwraca uchwyt czcionki, który kontrolka podpowiedzi będzie używać do rysowania tekstu.
WM_MOUSEMOVE	Ukrywa okno tooltips.
WM_PAINT	Rysuje okno podpowiedzi.
WM_SETFONT	Ustawia uchwyt czcionki, którą kontrolka podpowiedzi będzie używać do rysowania tekstu.
WM_TIMER	Ukrywa okno etykietki narzędzia, jeśli narzędzie zmieniło położenie lub wskaźnik myszy został przeniesiony poza narzędzie. W przeciwnym razie zostanie wyświetlone okno podpowiedzi.
WM_WININICHANGE	Resetuje zmienne wewnętrzne oparte na metrykach systemowych.