Okna

Shell NotifyIcon

ŁF
<style type="text/css">tr { background-color: #eee; } td { padding: 6px; } </style> 
// 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 [[WinAPI/UI/Okna/NOTIFYICONDATA|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 [[WinAPI/UI/Okna/NOTIFYICONDATA|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 [[WinAPI/UI/Okna/NOTIFYICONDATA|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 [[winapi/GetLastError|GetLastError]]. Najczęstszym powodem błędów jest nieistniejące lub nieodpowiadające (zawieszone) okno traybaru. W takim wypadku [[winapi/GetLastError|GetLastError]] zwraca E_FILE_NOT_FOUND.

Uwagi

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

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ż

Okna

0 komentarzy