MessageBox

int MessageBox(
    HWND hWnd,	
    LPCTSTR lpText,	
    LPCTSTR lpCaption,	
    UINT uType 
   );

function MessageBox(hWnd: HWND; lpText, lpCaption: PChar;  uType: UINT): Integer; stdcall; 

Funkcji MessageBox używamy, aby pokazać okno dialogowe zawierające wiadomość (treść komunikatu), tytuł oraz dowolną kombinację ikon i przycisków.

Parametry:

hWnd Identyfikuje właściciela okna komunikatu. W przypadku, gdy parametr jest równy 0 (NULL) okno nie posiada właściciela. Jeśli parametr posiada wartość Handle, to właścicielem komunikatu jest okno aplikacji (formularz). Na przykład, jeśli właścicielem okna dialogowego jest nasza aplikacja (formularz), to podczas wyświetlania komunikatu okno programu jest nieaktywne. Sterowanie do aplikacji zostanie zwrócone dopiero po potwierdzeniu komunikatu. lpText Parametr określający tekst wyświetlanego komunikatu. W przypadku długiej treści komunikatu, jest ona automatycznie zawijana (do następnej linii) w oknie dialogowym. lpCaption Parametr opcjonalny, określający tytuł okienka dialogowego. W przypadku, gdy parametr ma wartość 0 (NULL), tytuł okienka przyjmuje domyślny tekst Błąd. uType Parametr uType zawiera flagi, które określają wygląd i zachowanie się okna dialogowego. Parametr ten może być kombinacją flag z dowolnych grup flag. W przypadku, gdy parametr posiada wartość 0, zostanie wyświetlone okno dialogowe z przyciskiem OK.

Poniżej flagi określają rodzaje przycisków wyświetlanych w oknie dialogowym.<justify>

MB_ABORTRETRYIGNORE
Okno dialogowe zawiera trzy przyciski: Przerwij, Ponów próbę i Ignoruj.
MB_CANCELTRYCONTINUE Windows 2000 i nowsze
Okno dialogowe zawiera przyciski: Anuluj, Ponów próbę i Kontynuuj
MB_HELP
Dodaje do okna dialogowego przycisk Pomoc. Jeśli użytkownik kliknie ten przycisk lub naciśnie F1, okno będące właścicielem okienka z wiadomością otrzyma komunikat WM HELP
MB_OK
Okno dialogowe zawiera przycisk z napisem OK.
MB_OKCANCEL
Okno dialogowe zawiera dwa przyciski: OK i Anuluj.
MB_RETRYCANCEL
Okno dialogowe zawiera następujące przyciski: Ponów próbę i Anuluj.
MB_YESNO
Okno dialogowe zawiera dwa przyciski: Tak i Nie.
MB_YESNOCANCEL
Okno dialogowe zawiera przyciski z napisami: Tak, Nie i Anuluj.

Pozniżej znajdują się natomiast flagi określające rodzaj ikony wyświetlanej w okienku dialogowym.

MB_ICONEXCLAMATION, MB_ICONWARNING
Wyświetla okno dialogowe z ikoną czarnego wykrzyknika na żółtym tle.
MB_ICONINFORMATION, MB_ICONASTERISK
Wyświetla okno dialogowe z niebieskim znakiem informacyjnym na białym tle.
MB_ICONQUESTION
Wyświetla okno dialogowe z niebieskim znakiem zapytania na białym tle.
MB_ICONSTOP, MB_ICONERROR, MB_ICONHAND
Wyświetla okno dialogowe z białym znakiem ?x? na czerwonym tle.

Poniższe flagi umożliwiają wskazanie, który przycisk ma być aktywny podczas wyświetlania okna dialogowego.

MB_DEFBUTTON1
Pierwszy przycisk jest domyślny (aktywny).
MB_DEFBUTTON2
Drugi przycisk jest domyślny (aktywny).
MB_DEFBUTTON3
Trzeci przycisk jest domyślny (aktywny).
MB_DEFBUTTON4
Czwarty przycisk jest domyślny (aktywny).

Istnieją również flagi, które określają modalność okna dialogowego.
MB_APPLMODAL
Użytkownik musi potwierdzić komunikat, aby zwrócić sterowanie do okna określonego w parametrze hWnd. Okna innych aplikacji są dostępne. Zależnie od hierarchii okien, użytkownik ma dostęp do okien należące do danej aplikacji. Wszystkie okna, które są podporządkowane (ang. child windows ? okno potomne) oknie, będącym rodzicem (ang. parent) okna dialogowego, są nieaktywne.
MB_SYSTEMMODAL
Tak samo jak flaga MB_APPLMODAL, blokuje dostęp do okna będącego rodzicem komunikatu, jednakże okno dialogowe pozostaje na wierzchu (ang. stay on top) nawet, gdy użytkownik ?pracuje? z innymi programami.
MB_TASKMODAL
W przypadku, gdy parametr hWnd ma wartość 0 (NULL), wyświetlenie okna dialogowego powoduje blokadę wszystkich okien aplikacji. Jeśli jednak wartością tego parametru jest uchwyt do dowolnego okna, okno to zostanie zablokowane podczas wyświetlania komunikatu (pozostałe okna programu są dostępne).

Dodatkowo, możemy wyróżnić następujące flagi:
MB_DEFAULT_DESKTOP_ONLY
Komunikat musi pojawić się na domyślnym pulpicie (na tym, na którym zalogował się użytkownik).
MB_SETFOREGROUND
Okno komunikatu jest oknem pierwszoplanowym. Nie pozwala użytkownikowi rozpocząć żadnej innej akcji.
MB_SERVICE_NOTIFICATION
Wyświetla okno dialogowe na aktywnym pulpicie, nawet jeśli żaden użytkownik systemu Windows się nie zalogował. Jeśli flaga ta jest ustawiona, parametr hWnd musi być pusty (0).
MB_RIGHT
Tekst w oknie dialogowym jest wyrównany do prawej strony.
MB_RTLREADING
Pokazuje okno dialogowe, w którym tekst nagłówka jest wyrównany do prawej strony, oraz w którym przycisk zamykania znajduje się po lewej stronie okna.
MB_TOPMOST
Okno dialogowe komunikatu będzie posiadać styl WS_EX_TOPMOST.

Wartość zwracana:

Jeśli okno komunikatu posiada przycisk ?Anuluj?, funkcja zwraca wartość `IDCANCEL` zarówno po wybraniu tego przycisku jak i po naciśnięciu klawisza ESC. Jeśli okno nie zawiera przycisku ?Anuluj?, klawisz ESC jest ignorowany.

Jeśli funkcja się nie powiedzie, zwraca wartość 0. Dodatkowe informacje o błędzie można pobrać za pomocą funkcji GetLastError.

Jeśli funkcja się powiedzie, zwraca jedną z następujących wartości:

Stała (Wartość liczbowa)
IDOK (1)
Wybrano przycisk: OK
IDCANCEL (2)
Wybrano przycisk: Anuluj
IDABORT (3)
Wybrano przycisk: Przerwij
IDRETRY (4)
Wybrano przycisk: Ponów próbę
IDIGNORE (5)
Wybrano przycisk: Ignoruj
IDYES (6)
Wybrano przycisk: Tak
IDNO (7)
Wybrano przycisk: Nie
IDTRYAGAIN (10)
Wybrano przycisk: Ponów
IDCONTINUE (11)
Wybrano przycisk: Kontynuuj
<justify>

Uwagi:
Windows 95/98/Me: Wersja Unicode funkcji (MessageBoxW) jest wspierana przez Warstwę Unicode (Microsoft Layer for Unicode) - MSLU. Aby użyć funkcji w wersji Unicode, należy dokonać pewnych zmian w aplikacji wedle wskazówek nakreślonych w Microsoft Layer for Unicode on Windows 95/98/Me Systems (eng)

Jak wcześniej wspomniałem, parametr uType może być kombinacją flag opisanych powyżej. Do połączenia flag służy operator ?or? (można również używać operatora ?+?). Poniższy przykład wyświetli okno dialogowe z przyciskami OK i Anuluj, oraz z ikoną czarnego wykrzyknika na żółtym tle. Drugi przycisk będzie domyślny.

MessageBox(Handle, 'Za mało pamięci RAM', 'My application', MB_OKCANCEL or MB_DEFBUTTON2 or MB_ICONWARNING);

Istnieje również funkcja Application.MessageBox (funkcja klasy TApplication), która różni się od funkcji MessageBox tym, że nie wymaga uchwytu okna, ponieważ właścicielem okna jest nasza aplikacja. Funkcja ta ma następującą postać:

function MessageBox(const Text, Caption: PChar; Flags: Longint = MB_OK): Integer;

Pozostałe parametry są identyczne jak w funkcji MessageBox.

Przykład:

uses
  ShellApi;

procedure TForm1.FormShow(Sender: TObject; var Action: TCloseAction);
begin
  if MessageBox(Handle,'Czy chcesz zarejestrować program?', 'Rejestracja', MB_YESNO + MB_ICONQUESTION) = IdYes then
    begin
      ShellExecute(Handle, 'open', 'http://www.rejestracja.pl/', nil, nil, SW_SHOWNORMAL);
      Close;
    end;
  end;
end;

Podczas wyświetlania okna aplikacji (zdarzenie OnShow) zostanie wyświetlone okno dialogowe z pytaniem: Czy chcesz zarejestrować program?. W przypadku, gdy użytkownik wybierze przycisk Tak (czyli zostanie zwrócona wartość IdYes) wyświetli się strona internetowa umożliwiająca rejestrację programy, a aplikacja zostanie zamknięta. Ponieważ w powyższym przykładzie została użyta funkcja ShellExecute, należy dodać do listy uses moduł ShellApi.

• Zobacz też: **
• MessageBeep
• MessageBoxEx
• MessageBoxIndirect