number of ratings	0
average rating	0.00

19 Dialogs

Dialogs are frequently used to display special information, information that is not presented during the normal course of an application. Dialogs may be displayed in a modal way where they block input to the background windows while displayed, or in a non-blocking modeless fashion. Carousel allows you build dialogs from pages just as you would build any other pages.

Creating a dialog

A new dialog can be created from the File menu by choosing File | New | Xui | Xui Dialog . Alternatively you can right click on the pages folder in the file view and choose New XUI Page... from the popup menu.

When the dialog is displayed enter the name of the new dialog and choose XDialog from the Base class list.

Structure

In Carousel a dialog is special case of a page, the XDialog class is derived from XPage and inherits all its facilities just as any other page would. However, whereas a typical page is displayed in the body of the application or within a frameset a dialog is displayed in a popup window.

The XDialog class is not itself the dialog object from the point of view of the underlying Java system, instead the XDialog is a container nested inside a dialog class or window.

The XDialog class can be subclassed and in this way you can customize the look and feel of the dialog plus modify the dialog's behavior, perhaps setting icons and changing headers. Normally such customization is not undertaken in applications but in some highly branded application you may not want the default operating system color scheme clashing with you applications look.

Display

A dialog may be displayed by calling the showDialog method instead of the showPage method.

Code Sample 19-1 - Displaying a dialog

try { XDialog popupDialog = ( XDialog )pageMgr.loadPage( "myPopupDialog" ); Point pt = (( MouseEvent )getCurrentEvent() ).getPoint(); Point topLeft = myObject.getLocationOnScreen(); pt.translate( topLeft.x, topLeft.y ); popupDialog.setLocation( pt ); popupDialog.setModal( true ); popupDialog.pack(); popupDialog.showDialog( this ); } catch ( Exception e ) { e.printStackTrace(); }

A dialog will normally be displayed in the centre of the screen, but the location can be changed with a call to setLocation . The above example displays the dialog just below and to the right of the component ' myObject ' when the mouse is clicked on the component. (The translate method is used to adjust the current location since the current mouse position is relative to the component).

Once a modal dialog has been displayed the calling method is blocked till the dialog is dismissed. A dialog can be dismissed or closed by calling the closeDlg or cancelDlg methods.

For a modeless dialog it is sometimes useful to know when the dialog is dismissed even if the calling code is not blocked. The showDialog method therefore comes in a version that takes a reference to a callback method. The callback method is simply specified as the name of a response/handler method in the calling class. When the dialog is dismissed the callback method is invoked.

Packing

The decorations on a dialog (the border and header) can vary from platform to platform and it is therefore awkward to calculate the exact size of the dialog prior to display. Carousel provides the pack method to resize the dialog so that all the components are visible. In addition the dialog page may specify a padding attribute to provide some extra space about the edges of the dialog and so that the components are not butted up against the edge of the dialog.

Code Sample 19-2 - Padding a dialog

The above example shows the declaration of a dialog in XML as mentioned above in "Structure" on page 179 . It is important to note that a dialog must be of class XDialog or a class derived from the XDialog class (in either the net.xoetrope.swing.XDialog or net.xoetrope.awt.XDialog variant). The XDialog class is a special form of page designed for use in Dialogs. Once the super class is defined, the content of the dialog can be setup like any other page.

Modality

A dialog can be display in a modal way where all input to background windows is blocked till the dialog is dismissed. To make a dialog modal simply call the setModal method for the dialog class.

Code Sample 19-3 - Making a dialog modal

popupDialog.setModal( true );

Conversely a non-modal or modeless dialog can be created by setting this flag to false . A modeless dialog will allow user input to background window while the dialog is visible. Sometime modeless dialogs are used for parallel or alternate input mechanisms or for displaying summary or optional information in a separate window.

Other issues

Dialogs introduce a few additional issues due to the way they can interact with the rest of the system. The following sections cover some of these issues.

Setting the dialog location

The dialog is normally displayed at a position which centers it in relation to the the application. If you wish to explicitly set the location you can use a different version of the showDialog method:

Code Sample 19-4 - Specifying the dialog location explicitly

XDialog popupDialog = ( XDialog )pageMgr.loadPage( "MyPopup" ); popupDialog.setModal( true ); popupDialog.pack(); popupDialog.showDialog( this, "My Dialog", new Point( 100, 100 ) );

Centering the dialog on screen

In another variation of dialog positioning you can use a helper method to position a modeless dialog on the center of the screen. A helper class is provided to do this:

Code Sample 19-5 - Centering a modeless dialog

XDialog popupDialog = ( XDialog )pageMgr.loadPage( "MyPopup" ); popupDialog.setModal( false ); popupDialog.pack(); popupDialog.showDialog( this, "My Dialog", null ); XuiUtilities.centerOnScreen( popupDialog );

Helpers

The dialog can also be displayed with the helper XSwingHelper , or the AWT version XAwtHelper .

Code Sample 19-6 - Using XSwingHelper to show a modal dialog.

XSwingHelper.showDialog( this, "MyPopup", "My Title", true, new Point( 100, 100 ));

Focus

Displaying a dialog will cause the focus to shift to the new dialog window once it is displayed. Therefore it is important to exercise caution when using focus event and handlers that trigger dialogs. In some cases this can prove problematic and a special method is available for suppressing the focus events temporarily, however it should be used with caution and should be well tested as it can be difficult to get the timing of such changes right.

Code Sample 19-7 - Turning off focus event handling

getEventHandler().suppressFocusEvents( true );

Page activation

A dialog acts as any other page and will received the normal pageCreated , pageActivated and pageDeactivated messages. However the page from which the dialog display was triggered is not affected by the dialog display (other than by the focus events described above).

The bound components of the triggering page are however updated when a dialog is dismissed.

Data bindings

If a dialog page has bindings to the same part of the model as the current page in the application then special measures need to be taken to ensure that the data is displayed and saved in a consistent way. Take for example the following page which shows a dialog:

Code Sample 19-8 - The calling page declaration

And the popup dialog which reproduces some of the input is as follows:

Code Sample 19-9 - The dialog page declaration

Both the customer and the dialog page have declared bindings for their respective firstnameText text components to the same path in the data model. This means that the firstnameText component in the main application needs to display the results of the dialog if OK was clicked. So the Customer class openDialog function should look like the following.

Code Sample 19-10 - The openDialog function

public void openDialog() { saveBoundComponentValues(); XDialog dlg = (XDialog)pageMgr.loadPage( "CustDlg" ); dlg.pack(); dlg.showDialog( this ); }

The first line of this function makes a call to the saveBoundComponentValues function of the XPage in order to persist all of the screen information to the data model. This ensures that when the the dialog is displayed it will be consistent with the customer page.

A similar situtation arises when the dialog is dismissed. Normally the dialog just disappears and you do not need to worry about the dialog's data. However if you are binding data as described above you will need to save the data when the dialog is dismissed and update the page that had displayed the dialog. The CustDlg class which subclasses the XDialog class follows.

Code Sample 19-11 - The CustDlg class

public class CustDlg extends XDialog { private boolean okClicked = false; public void pageActivated() { okClicked = false; } public void okClick() { okClicked = true; closeDlg(); }

public void cancelClick() { closeDlg(); } public void saveBoundComponentValues() { if ( okClicked ) super.saveBoundComponentValues(); } }

When the OK button is clicked it is necessary to persist the bindings to the model. This is done by overloading the saveBoundComponentValue function and only calling the super function if the okClicked flag is true.

Fortunately the dialog class provides the setSaveOnClose(true) method to do exactly the above and saves you some code. The method causes the dialog to save its data and update the calling page if the OK button is used to dismiss the dialog. The saveOnClose flag is set to true by default so you do not need to modify the openDialog method.

The dialog still needs to know when the cancel button is clicked (assuming you have a cancel button on your dialog) and the method cancelDlg can be used to dismiss the dialog without saving the data. The modified page is as follows:

Code Sample 19-12 - The dialog page with the calls to closeDlg and cancelDlg

Now, since there is no need to set a special flag for the cancel event we can get rid of the rest of the custom code and just call the closeDlg method in response to the OK button click.

The dialog has one more button, the close button in the top right of the toolbar. This button is treated as the Cancel button and automatically dismisses the dialog without saving any data.

comments

If you were logged in you could rate this article or add a comment.