Okna

Shell NotifyIcon

  • 2008-01-26 20:33
  • 0 komentarzy
  • 885 odsłon
  • Oceń ten tekst jako pierwszy
{{Template:ArtStyle}}

// C/C++
BOOL Shell_NotifyIcon(
    DWORD dwMessage,
    PNOTIFYICONDATA lpdata
);

// Delphi
function Shell_NotifyIcon(dwMessage: DWORD; lpData: PNotifyIconData): BOOL; stdcall;


Funkcja Shell_NotifyIcon umożliwia dodanie, zmianę i usunięcie ikony z taskbara (tray, tacka systemowa).


Parametry

dwMessage
32-bitowa zmienna (DWORD) określająca jaka akcja ma być podjęta. Może przyjmować jedną z poniższych wartości:

NIM_ADDDodaje ikonę do taskbara. Pola hWnd i uID struktury NOTIFYICONDATA na którą wskazuje parametr lpData zostaną użyte do identyfikacji późniejszych wywołań funkcji NotifyIcon.
NIM_DELETEUsuwa poprzednio dodaną ikonę. Należy użyć tych samych wartości pól hWnd i uID struktury NOTIFYICONDATA, które były podane przy dodawaniu ikony.
NIM_MODIFYZmienia parametry ikony w taskbarze. Należy użyć tych samych wartości pól hWnd i uID struktury NOTIFYICONDATA, które były podane przy dodawaniu ikony.
NIM_SETFOCUSDziała w wersji 5.0 i nowszych (Windows 2000, XP i nowsze). Ustawia focus na taskbarze. Polecenie powinno być użyte po tym, gdy operacje związane z ikoną zakończą się (np. po tym, gdy użytkownik wyświetli menu kontekstowe ikony, po czym zrezygnuje z jego korzystania, zamykając je np. klawiszem Esc)
NIM_SETVERSIONWersja 5.0. Informuje taskbar, że ma się zachowywać zgodnie ze swoimi poprzednimi wersjami. Numer wersji podawany jest w polu uVersion struktury wskazywanej przez lpdata. Dzięki temu możliwe jest używanie nowych funkcjonalności wersji 5.0, lub zgodność z poprzednimi wersjami (np. domyślna wartość tego pola - 0 - włącza tryb zgodności z Windows 95). Więcej w uwagach.


lpdata
Wskaźnik na strukturę NOTIFYICONDATA. Zawartość struktury zależy od parametru dwMessage.


Wartości zwracane

Jeśli wywołanie się powiedzie, funkcja zwróci wartość true, w przeciwnym wypadku funkcja zwraca wartość false. Jeśli dwMessage ma wartość NIM_SETVERSION, funkcja zwraca true jeśli udało się ustawić wersję, lub false jeśli żądana wersja nie jest dostępna.
Dodatkowe informacje o błędzie można pobrać za pomocą funkcji GetLastError. Najczęstszym powodem błędów jest nieistniejące lub nieodpowiadające (zawieszone) okno traybaru. W takim wypadku GetLastError zwraca E_FILE_NOT_FOUND.


Uwagi

Od wersji XP SP2 systemu Windows w baloniku podpowiedzi można ustawić własną ikonę.

Od wersji 5.0 powłoki (Windows 2000 i nowsze) funkcja Shell_NotifyIcon pozwala na inne niż na starszych systemach traktowanie zdarzeń z klawiatury i myszy. Różnice dotyczą następujących elementów:
  • Jeśli użytkownik wybierze menu kontekstowe ikony za pomocą klawiatury, powiązana z ikoną aplikacja otrzyma komunikat WM_CONTEXTMENU. Poprzednie wersje biblioteki wysyłały komunikaty WM_RBUTTONDOWN i WM_RBUTTONUP.
  • Jeśli użytkownik zaznaczy ikonę za pomocą klawiatury i aktywuje ją spacją lub enterem, przypisana do ikony aplikacja otrzyma wiadomość NIN_KEYSELECT. Poprzednie wersje biblioteki wysyłały komunikaty WM_RBUTTONDOWN i WM_RBUTTONUP.
  • Jeśli użytkownik zaznaczy ikonę myszką i aktywuje ją enterem, przypisana do ikony aplikacja otrzyma wiadomość NIN_SELECT. Poprzednie wersje biblioteki wysyłały komunikaty WM_RBUTTONDOWN i WM_RBUTTONUP.
  • Jeśli użytkownik ustawi kursor myszki nad ikoną, która ma ustawiony balonikowy ToolTip, wersja 6.0 biblioteki (Windows XP i nowsze) wyśle aplikacji następujące wiadomości:
    • NIN_BALLOONSHOW - wysyłana gdy balonik jest pokazywany. Baloniki są kolejkowane.
    • NIN_BALLOONHIDE - wysyłana gdy balonik znika, np. gdy ikona jest usuwana. Wiadomość ta nie jest wysyłana, gdy balonik znika w wyniku timeoutu lub gdy użytkownik klika na nim myszką.
    • NIN_BALLOONTIMEOUT - wysyłana, gdy balonik znika w wyniku timeoutu.
    • NIN_BALLOONUSERCLICK - wysyłana, gdy balonik został zamknięty w wyniku akcji użytkownika.
  • Jeśli użytkownik najedzie kursorem myszki na ikonę, do której jest przypisane balonikowy ToolTip, powłoka Windows Vista wyśle następujące wiadomości:

    • NIN_POPUPOPEN - wysyłany, gdy użytkownik najedzie kursorem myszki na ikonę. Celem jest poinformowanie aplikacji, że może wyświetlić bardziej zaawansowane okno z dymkiem podpowiedzi niż standardowy tekstowy ToolTip.
    • NIN_POPUPCLOSE - wysyłane, gdy użytkownik wyjedzie kursorem myszki poza obszar ikonki. Celem jest poinformowanie aplikacji, że zaawansowany dymek podpowiedzi powinien zostać zamknięty.

Możesz wybrać w jaki sposób system powinien się zachowywać wywołując funkcję Shell_NotifyIcon z parametrem dwMessage ustawionym na NIM_SETVERSION i polem uVersion struktury NOTIFYICONDATA żeby wybrać zachowanie systemu - według wersji 5.0 czy wersji starszych.

Wiadomości opisane powyżej nie są standardowymi komunikatami systemu Windows. Są wysyłane poprzez wartość parametru lParam wraz ze zdarzeniem o wartości zdefiniowanej przez użytkownika podczas dodawania ikony (NIM_ADD).


Zobacz też