MessageBox.txt

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.

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


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.