BASIC USAGE

Calling the native message box functions of your browser is straightforward : call the function and you will be sure that the next instruction after the call will only be executed when the call has completed, ie when the user has closed the message box :

Doing the same using jQuery UI will require you to use callback, in order to take into account the "pure multitasking, asynchronous essential nature" of Javascript. So, using the $.alert() function, you will have to rewrite the above code the way below (note that I use my own indentation style for that, you are free to refuse it !) :

REFERENCE

You can specify arguments in the order you like, because they are recognized using their types. The only rule to follow is that the message string must appear before the title string (if specified).

The alert(), error(), confirm(), inputbox() and msgbox() functions all accept a callback, which have the following signature :

callback ( status, dialog )

Where status depends on the user action : it is usually a boolean set to true if the user clicked the Ok button and false if the user clicked the Cancel button or the Close icon ; dialog is a reference to the opened dialog object.

All msgbox functions accept an options object, which are simply options passed to the jQuery dialog() function.

Once closed, the displayed message boxes are removed from the DOM.

$.alert ( msg, title, callback, options )

Displays an alert message (simple message box). The parameters are the following :

message : Message to be displayed.

title : Optional message box title. The default is "Message".

callback : A function to be called when the user clicks the "Ok" button or the Close icon (optional).

options : Additional dialog options (optional).

The status parameter of the callback function is always set to true.

The options parameter can now contain a buttons member, which allows you to specify additional buttons to your alert box ; each element will be added to the left of the Ok button and can contain the following members :

html : The button text to be displayed

click : A callback function which will be passed the current event as a parameter. The alert box will be closed if the callback returns a value different from false.

$.error ( msg, title, callback, options )

Displays an error message (simple message box). The parameters are the following :

message : Message to be displayed.

title : Optional message box title. The default is "Error".

callback : A function to be called when the user clicks the "Ok" button or the Close icon (optional).

options : Additional dialog options (optional).

The difference with $.alert() resides only in the class names used for styling.
The status parameter of the callback function is always set to true.

As for $.alert, additional buttons may be specified with the options parameter.

$.inputbox ( msg, title, callback, options, field_definition )

Asks the user for text input. The parameters are the following :

message : Message to be displayed.

title : Optional message box title. The default is "Input".

callback : A function to be called when the user clicks the "Ok" button or the Close icon (optional).

options : Additional dialog options (optional).

field_definition : Html input field definition. The default is :

&lt;input type="text" size="50"/&gt;

Note that you do not need to define an id or name attribute. This parameter is optional.

The status parameter of the callback function is set to the input string if the user clicked Ok, or false if the user clicked on the Cancel button or Close icon.

$.wait ()

This function is used to display a modal dialog with no buttons and no possibility to be closed. You can use it to display a message while doing some long processing.

It can be displayed using one of the following forms :

$.wait ( message )

$.wait ( options )

message is the message to be displayed. options is an object than can contain any $.dialog() options, plus the following specific members :

message : Message to be displayed

icon : Optional reference to an icon file.

To close the wait dialog box, simply call $.wait() with no parameters.

$.msgbox ( msg, title, callback, flags, options )

The $.msgbox() functions mimics the Windows API MessageBox function. It accepts an additional flags parameter, which is a combination of the following bit constants :

ui-popup-dialog-buttonset : the area of the dialog box containing the buttons

ui-popup-dialog-button-text : text of a dialog button

Each of these classes have also a counterpart depending on the function you are calling. For example, the $.alert() function will add a 'ui-alert-dialog-button' class for items that have class 'ui-popup-dialog-button'. $.error() will add ui-error-dialog-button-class, and so on for all the '\-popup\-' classes defined.