[Developers] uiDialog::Setup

[Bert Bril]

Hi all,


I've been cleaning up some uiDialog Setup stuff in the past days. 
Because it may not be completely clear what everything means (even to 
the people at dGB), here's a guide.

First of all, the (mandatory) constructor arguments are:

(1) Window title or caption. This is the name in the window title bar. 
If the window is minimized, that text will be shown in teh 'Windows 
bar'. The idea is to put a short description of where the window is for. 
For example: "Import SEG-Y". "Shift horizon". This should never be 
empty. The text can be changed by using uiMainWIn::setCaption().

(2) Dialog title. This is the text on top of the dialog. It may be 
empty, in which case the dialog will start immediately with the first 
field. If you pass null, the dialog title will be equal to the window 
title. The text can be changed with uiDialog::setTitleText();
In the development tree I have added #define mNoDlgTitle "" to help 
clarify that you do not want a dialog title.

(3) Help ID. When the user presses the '?' button, OpendTect tries to 
find a 'WindowLinkTable.txt' file, searching for a window ID. The 
default directory to find this is doc/User/base . For example, import 
SEG_Y is "103.0.6". In the WindowLinkTable.txt, it will find link 
LINK-SEGY.READ.ACCESS. Then to findthe file for this link it looks in 
'LinkFileTable.txt'. There, we see that this link is in 
chapter4.3_import.htm. Thus, OpendTect will try to open the file:
$DTECT_APPL/doc/User/base/chapter4.3_import.htm
If you create a plugin, you may want to make a separate help doc 
directory. Then, you can scope the help ID. For example, our NN plugin 
main window has "dgb:102.0.0". Then OpendTect will look for the .txt 
files in $DTECT_APPL/doc/User/dgb.
Help IDs may be absent (you may not want to support help or the window 
may be too simple for help), or you may not yet know which ID to add, or 
you may not want to . In any case, it's good to make clear what your 
intentions are, so I have added two defines mNoHelpID and mTODOHelpID. 
Help IDs can be set (e.g. if it is dependent on something) with 
uiDialog::setHelpID().


Further options for dialogs can be set through access functions. For 
such situations, we made the macro mDefSetupMemb, ideal for 'Setup' type 
classes. It defines functions that return a reference to the setup class 
instance. That makes constructions like below possible:

uiDialog::Setup su("x","y","z.z.z");
su.modal(false).nrstatusflds(3).menubar(true);

or even:

uiDialog MyDlg( p, uiDialog::Setup su("x","y","z.z.z").modal(false) );


Some options:

* The text on the Ok and Cancel buttons can be changed with oktext() and 
canceltxt(). Set to empty the button will not appear. We hardly use 
this, mostly we use uiDialog::setCtrlStyle().

* Some dialogs have a 'Save as default' check box. To get this, use 
savebutton(true). The text on the button can be set with savetext(), and 
the button can also be made as a tool button - (set callback etc. with 
the uiDialog::button() function).

* modal() sets the modality: modal windows lock the parent, non-modal do 
not. If this is set to false, expect the go() to return without a user 
OK (i.e. immediately). Thus, go() is then essentially a show().

* menubar(true) adds a menu bar, nrstatusflds(N) with N != 0 will add a 
status bar with N fields. If you want a status bar but without fields, 
set N=-1.



Bert

-- 
-- dGB Earth Sciences B.V.
-- Nijverheidstraat 11-2, 7511 JM Enschede, The Netherlands
-- mailto:Bert.Bril at dgb-group.com , http://www.dgb-group.com
-- Tel: +31 534315155 , Fax: +31 534315104