DDialog

From Dabo Wiki
Jump to: navigation, search

Dialogs are like forms, but are modal and are used to request a very specific piece of information from the user, and/or display specific messages to the user. So in typical use a Dialog is effectively a simple modal form. You create an instance of it, show it, interact with it, then close it, possibly make use of some data from it, and then destroy it.

Using dDialog is a little bit like a cake ! ! !

You can go to the shop and buy yourself a cake. There are a number of different types already sitting on the shelf. A chocolate cake, a banana cake, a sponge cake and a fruit cake. And don't they look yummy, just sitting there waiting for you, mmm....

Alternatively you can go into the kitchen and make use of the cake mixer and all those packets of ingredients in the pantry to make whatever sort of cake that you would like.

The same is true of Dialogs. There are a number of functions available that handle the dialog creation, display and release for you; you can customize their titles, icons, messages, etc., as needed, but Dabo handles everything else.

See here for fuller details on the various built-in functions: dabo.ui Functions


Creating Your Own Custom Dialogs

So the alternative to using one of these ready-made dialog functions is to "bake your own" (in the pre-politic days it was called "roll your own"). When you create your own dialogs, you can customize them to suit your needs. Check the API to discover the multitude of options that you can make use of. But don't forget that this also requires you to take responsibility for them.

For instance: When you are finished with your dialog, make certain that you destroy it!

wxPython Background (for those who are interested): dDialog is built from wxPython Dialogs.

When using a wxPython Dialog, do you need to destroy it after "EndModal"? "The answer is of course YES. Dialogs are different because the C++ part of the window objects in wxPython hold a reference to the Python object, so you need to call Destroy() to deallocate the C++ object and break the cycle. Most window objects are owned by their parents and are destroyed automatically when the parent is, (or in the case of frames they destroy themselves when closed) but for dialogs the are meant to be used after they are closed (for accessing data values, etc.) so you have to explicitly destroy them."

- Quote from Robin Dunn (wxPython Software Craftsman).


release()

If you are creating your own dDialog instance, you have to call its release() method when you are finished with it. When you create your own custom version, the dialog is only released when the release() method is called or its parent is destroyed. So get into the habit now, of always calling release() as soon as you are finished with the dialog.

The normal flow for using a dialog is:

dlg = dDialog()
dlg.show()
# the user interacts with the dialog
# When they close the dialog, call its hide() method
# Now get the info from the dialog
val = dlg.getSomeValue()
val2 = dlg.getSomeOtherValue()
# Got all the info; now release it
dlg.release()

If you have a dialog that you need to show multiple times, you can create it once, and simply call hide() to, well, hide it and allow the user to continue working on the main form. When you need to display it again, simply call its show() method. You can do this as many times as you need. When you are done, you can then call the dialog's release() method to properly destroy it.

These notes put together by Fraser Burns and corrected by those who know better.