Dialog class derives from Window class and creates modal (or modeless) dialogs. Modal dialogs are special top-level windows which block the rest of the application until they are closed. Modal dialogs are typically used when user action is required to continue with the program or to indicate that the application is currently busy. A dialog could show a progress bar then, for example.
As with windows, the root element of a dialog always needs to be a single group object, i.e. an instance of Group class. See Group class for details. Additionally, it is not allowed to have multiple elements at the dialog's root level. You must only use a single group object as the root element. Here's an example of a simple progress dialog in XML:
<dialog id="mydlg" title="Working...">
<vgroup>
<progressbar id="prg"/>
<button id="cancel">Cancel</button>
</vgroup>
</dialog>
|
You should create dialogs only when you need them and destroy them as soon as you are finished with them. It is not advised to create all your dialogs on startup using moai.CreateApp() and keep them in memory all the time. Instead, you should use moai.CreateDialog() to create a dialog when you need it and then have it destroyed as soon as you are finished with it. The reason for this is that windows are quite a finite resource on some operating systems supported by RapaGUI. For example, on Windows there is a limit of about 10,000 windows per process. That might sound like sufficiently enough but keep in mind that on Windows every widget is a "window" for the operating system, e.g. every label, button, frame, checkbox, group, etc. in your application is a window so you should take care that you create your dialogs only as needed using moai.CreateDialog() and destroy them right afterwards.
In practice, it is advised to create a separate XML file for each of your dialogs and then use moai.CreateDialog() to convert the XML file into a dialog at runtime and have the dialog destroyed automatically by RapaGUI as soon as the user closes it.
As a subclass of Window class most Window class attributes and methods
can be used with Dialog class as well. See Window class for details. But note that modal dialogs
mustn't be opened by setting Window.Open but by running the Dialog.ShowModal method.
To close a modal dialog, simply call the Dialog.EndModal method. This will also automatically
destroy the dialog, i.e. it will implicitly call moai.FreeDialog()
on the dialog unless you explicitly request that the dialog should not be destroyed by setting an
optional argument to True.
Similarly, the dialog will also be automatically destroyed when the user clicks the close box of a dialog. If you don't want this or if you need to customize the application's behaviour when clicking the close box of a dialog, you have to install a listener on the Window.CloseRequest attribute. If there is no listener on this attribute, RapaGUI will simply call Dialog.EndModal with 0 as the parameter when the dialog's close box is clicked.
If you want to open a modeless dialog, i.e. a dialog that doesn't block your script
while it is open, you must not use Dialog.ShowModal but set Window.Open
to True for the dialog instead (and possibly set Application.Sleep to True too, if
you wish to put the application in some sort of sleep state while the dialog is open). You can then
implement the dialog's actual behaviour (e.g. a progress bar that is constantly being
updated) by repeatedly calling a management function either using SetTimeout() or Hollywood
9.0's new RunCallback() function. When you're finished with a modeless dialog, just
set Window.Open to False on it. Do not use Dialog.EndModal with modeless
dialogs! See the "Dialogs" example that comes with RapaGUI for an example of a modeless
dialog (choose "Test progress bar dialog" in the menu).