|
|
This base class provides basic functionality needed by nearly all dialogs. It offers the standard action buttons you'd expect to find in a dialog as well as the ability to define at most three configurable buttons. You can define a main widget which contains your specific dialog layout or use a predefined layout. Currently, TreeList/Paged, Tabbed, Plain and Swallow mode layouts (faces) are available.
The class takes care of the geometry management. You only need to define a minimum size for the widget you want to use as the main widget.
You can set a background tile (pixmap) for parts of the dialog. The tile you select is shared by all instances of this class in your application so that they all get the same look and feel.
There is a tutorial available on http://developer.kde.org/ (NOT YET) that contains copy/paste examples as well a screenshots on how to use this class.
UrlDlg::UrlDlg( QWidget *parent, const QString& caption, const QString& urltext) : KDialogBase( parent, "urldialog", true, caption, Ok|Cancel, Ok, true ) { QWidget *page = new QWidget( this ); setMainWidget(page); QVBoxLayout *topLayout = new QVBoxLayout( page, 0, spacingHint() ); QLabel *label = new QLabel( caption, page, "caption" ); topLayout->addWidget( label ); lineedit = new QLineEdit( urltext, page, "lineedit" ); lineedit->setMinimumWidth(fontMetrics().maxWidth()*20); topLayout->addWidget( lineedit ); topLayout->addStretch(10); }
If you use makeVBoxMainWidget , then the dialog above can be made simpler but you loose the ability to add a stretchable area.
UrlDlg::UrlDlg( QWidget *parent, const QString& caption, const QString& urltext) : KDialogBase( parent, "urldialog", true, caption, Ok|Cancel, Ok, true ) { QVBox *page = makeVBoxMainWidget(); QLabel *label = new QLabel( caption, page, "caption" ); lineedit = new QLineEdit( urltext, page, "lineedit" ); lineedit->setMinimumWidth(fontMetrics().maxWidth()*20); }
KDialogBase ( QWidget *parent=0, const char *name=0, bool modal=true, const QString &caption=QString::null, int buttonMask=Ok|Apply|Cancel, ButtonCode defaultButton=Ok, bool separator=false, const QString &user1=QString::null, const QString &user2=QString::null, const QString &user3=QString::null) |
Constructor for the standard mode where you must specify the main widget with setMainWidget() .
Parameters:
parent | Parent of the dialog. |
name | Dialog name (for internal use only) |
modal | Controls dialog modality. If false , the rest of the
program interface (example: other dialogs) is accessible while
the dialog is open.
|
caption | The dialog caption. Do not specify the application name here. The class will take care of that. |
buttonMask | Specifies which buttons will be visible. |
defaultButton | Specifies which button we be marked as the default. |
separator | If true , a separator line is drawn between the
action buttons and the main widget.
|
user1 | User button1 text. |
user2 | User button2 text. |
user3 | User button3 text. |
KDialogBase ( int dialogFace, const QString &caption, int buttonMask, ButtonCode defaultButton, QWidget *parent=0, const char *name=0, bool modal=true, bool separator=false, const QString &user1=QString::null, const QString &user2=QString::null, const QString &user3=QString::null) |
Constructor for the predefined layout mode where you specify the kind of layout (face).
Parameters:
dialogFace | You can use TreeList, Tabbed, Plain or Swallow. |
caption | The dialog caption. Do not specify the application name here. The class will take care of that. |
buttonMask | Specifies what buttons will be visible. |
defaultButton | Specifies what button we be marked as the default. |
parent | Parent of the dialog. |
name | Dialog name (for internal use only). |
modal | Controls dialog modality. If false , the rest of the
program interface (example: other dialogs) is accessible while
the dialog is open.
|
separator | If true , a separator line is drawn between the
action buttons and the main widget.
|
user1 | User button1 text. |
user2 | User button2 text. |
user3 | User button3 text. |
KDialogBase ( const QString &caption, int buttonMask=Yes|No|Cancel, ButtonCode defaultButton=Yes, ButtonCode escapeButton=Cancel, QWidget *parent=0, const char *name=0, bool modal=true, bool separator=false, QString yes = QString::null, QString no = QString::null, QString cancel = QString::null ) |
Constructor for a message box mode where the buttonMask
can only
contain Yes, No, or Cancel.
If you need other names you can rename the buttons with setButtonText(). The dialog box is not resizeable by default but this can be changed by setInitialSize(). If you select 'modal' to be true, the dialog will return Yes, No, or Cancel when closed otherwise you can use the signals yesClicked(), noClicked(), or cancelClicked() to determine the state.
Parameters:
caption | The dialog caption. Do not specify the application name here. The class will take care of that. |
buttonMask | Specifies what buttons will be visible. |
defaultButton | Specifies what button we be marked as the default. |
escapeButton | Specifies what button that will be activated by
when the dialog receives a Key_Escape keypress.
|
parent | Parent of the dialog. |
name | Dialog name (for internal use only). |
modal | Controls dialog modality. If false , the rest of the
program interface (example: other dialogs) is accessible
while the dialog is open.
|
separator | If true , a separator line is drawn between the
action buttons and the main widget.
|
user1 | User button1 text. |
user2 | User button2 text. |
user3 | User button3 text. |
~KDialogBase ( void ) |
Destructor.
void adjustSize ( void ) |
Adjust the size of the dialog to fit the contents just before QDialog::exec() or QDialog::show() is called.
This method will not be called if the dialog has been explicitly resized before showing it.
void enableButtonSeparator ( bool state ) |
Hide or display the a separator line drawn between the action buttons an the main widget.
void enableButton ( ButtonCode id, bool state ) |
Enable or disable (gray out) a general action button.
Parameters:
id | Button identifier. |
state | true enables the button(s).
|
void enableButtonOK ( bool state ) |
Enable or disable (gray out) the OK button.
Parameters:
state | true enables the button.
|
void enableButtonApply ( bool state ) |
Enable or disable (gray out) the Apply button.
Parameters:
state | true enables the button. |
void enableButtonCancel ( bool state ) |
Enable or disable (gray out) the Cancel button.
Parameters:
state | true enables the button. |
void showButton ( ButtonCode id, bool state ) |
Hide or display a general action button.
Only buttons that have been created in the constructor can be displayed. This method will not create a new button.
Parameters:
id | Button identifier. |
state | true display the button(s). |
void showButtonOK ( bool state ) |
Hide or display the OK button.
The OK button must have been created in the constructor to be displayed.
Parameters:
state | If true , display the button(s).
|
void showButtonApply ( bool state ) |
Hide or display the Apply button.
The Apply button must have been created in the constructor to be displayed.
Parameters:
state | true display the button(s). |
void showButtonCancel ( bool state ) |
Hide or display the Cancel button. The Cancel button must have been created in the constructor to be displayed.
Parameters:
state | true display the button(s).
|
bool showPage ( int index ) |
Set the page with index to be displayed.
This method will only work when the dialog is using the predefined shape of TreeList or Tabbed.
Parameters:
index | Index of the page to be shown. |
Returns: true
if the page is shown, false
otherwise.
int activePageIndex ( void ) |
Retrieve the index of the active page.
This method will only work when the dialog is using the predefined shape of TreeList or Tabbed.
Returns: The page index or -1 if there is no active page.
void setMainWidget ( QWidget *widget ) |
Set the main user definable widget.
If the dialog is using the predefined Swallow mode, the widget will
be reparented to the internal swallow control widget. If the dialog
is being used in the standard mode then the widget
must have the
dialog as parent.
Parameters:
widget | The widget to be displayed as main widget. If it is 0, then the dialog will show an empty space of 100x100 pixels instead. |
QWidget * getMainWidget ( void ) |
Retrieve the main widget if any.
Returns: The current main widget. Can be 0 if no widget has been defined.
void disableResize ( void ) |
Convenience method.
Freezes the dialog size using the minimum size of the dialog. This method should only be called right before show() or exec().
void setInitialSize ( const QSize &s, bool noResize=false ) |
Convenience method. Set the initial dialog size.
This method should only be called right before show() or exec(). The initial size will be ignored if smaller than the dialog's minimum size.
Parameters:
s | Startup size. |
noResize | If true the dialog can not be resized.
|
void incInitialSize ( const QSize &s, bool noResize=false ) |
Convenience method. Addd a size to the default minimum size of a dialog.
This method should only be called right before show() or exec().
Parameters:
s | Size added to minimum size. |
noResize | If true the dialog can not be resized.
|
void setButtonOKText ( const QString &text=QString::null, const QString &tooltip=QString::null, const QString &quickhelp=QString::null ) |
Sets the text of the OK button.
If the default parameters are used (that is, if no parameters are given) the standard texts are set: The button shows "OK", the tooltip contains "Accept settings." (internationalized) and the quickhelp text explains the standard behavior of the OK button in dialogs.
Parameters:
text | Button text. |
tooltip | Tooltip text. |
quickhelp | Quick help text. |
void setButtonApplyText ( const QString &text=QString::null, const QString &tooltip=QString::null, const QString &quickhelp=QString::null ) |
Sets the text of the Apply button.
If the default parameters are used (that is, if no parameters are given) the standard texts are set: The button shows "Apply", the tooltip contains "Apply settings." (internationalized) and the quickhelp text explains the standard behavior of the apply button in dialogs.
Parameters:
text | Button text. |
tooltip | Tooltip text. |
quickhelp | Quick help text. |
void setButtonCancelText ( const QString &text=QString::null, const QString &tooltip=QString::null, const QString &quickhelp=QString::null ) |
Set the text of the Cancel button.
If the default parameters are used (that is, if no parameters are given) the standard texts are set: The button shows "Cancel", the tooltip contains "Cancel settings." (internationalized) and the quickhelp text explains the standard behaviour of the cancel button in dialogs.
Parameters:
text | Button text. |
tooltip | Tooltip text. |
quickhelp | Quick help text. |
void setButtonText ( ButtonCode id, const QString &text ) |
Set the text of any button.
Parameters:
id | The button identifier. |
text | Button text. |
void setButtonTip ( ButtonCode id, const QString &text ) |
Set the tooltip text of any button.
Parameters:
id | The button identifier. |
text | Button text. |
void setButtonWhatsThis ( ButtonCode id, const QString &text ) |
Sets the "What's this?" text of any button.
Parameters:
id | The button identifier. |
text | Button text. |
void setTreeListAutoResize ( bool state ) |
This function has only effect in TreeList mode.
Defines how the tree list widget is resized when the dialog is resized horizontally. By default the tree list keeps its width when the dialog becomes wider.
Parameters:
state | The resize mode. If false (default) the tree list keeps its current width when the dialog becomes wider. |
bool haveBackgroundTile ( void ) |
Check whether the background tile is set or not.
Returns: @true if there is defined a background tile.
const QPixmap * getBackgroundTile ( void ) |
Retrieve a pointer to the background tile if there is one.
Returns: The tile pointer or 0 if no tile is defined.
void setBackgroundTile ( const QPixmap *pix ) |
Set the background tile.
If it is Null (0), the background image is deleted.
Parameters:
pix | The background tile. |
void showTile ( bool state ) |
Enable hiding of the background tile (if any).
Parameters:
state | true will make the tile visible.
|
void getBorderWidths ( int& ulx, int& uly, int& lrx, int& lry ) |
Do not use this method. It is included for compatibility reasons.
This method returns the border widths in all directions the dialog
needs for itself. Respect this, or get bad looking results.
The references are upper left x (ulx
), upper left y (uly
),
lower right x (lrx
), and lower left y (lly
).
The results are differences in pixels from the
dialogs corners.
QRect getContentsRect ( void ) |
Do not use this method. It is included for compatibility reasons.
This method returns the contents rectangle of the work area. Place your widgets inside this rectangle, and use it to set up their geometry. Be careful: The rectangle is only valid after resizing the dialog, as it is a result of the resizing process. If you need the "overhead" the dialog needs for its elements, use getBorderWidths().
QSize calculateSize ( int w, int h ) |
Calculate the size hint for the dialog.
With this method it is easy to calculate a size hint for a dialog derived from KDialogBase if you know the width and height of the elements you add to the widget. The rectangle returned is calculated so that all elements exactly fit into it. Thus, you may set it as a minimum size for the resulting dialog.
You should not need to use this method and never if you use one of the predefined shapes.
Parameters:
w | The width of you special widget. |
h | The height of you special widget. |
Returns: The minimum width and height of the dialog using w
and h
as the size of the main widget.
QString helpLinkText ( void ) |
Retrieve the help link text.
If no text has been defined, "Get help..." (internationalized) is returned.
Returns: The help link text.
void enableLinkedHelp ( bool state ) |
Display or hide the help link area on the top of the dialog.
Parameters:
state | true will display the area.
|
void setHelpLinkText ( const QString &text ) |
Set the text that is shown as the linked text.
If text is empty, the text "Get help..." (internationalized) is used instead.
Parameters:
text | The link text. |
void setHelp ( const QString &path, const QString &topic ) |
Set the help path and topic.
Parameters:
path | Path to help text. |
topic | Topic in help text. |
void helpClickedSlot ( const QString & ) |
Connected to help link label.
void updateBackground ( void ) |
This method is called automatically whenever the background has changed. You do not need to use this method.
void helpClicked ( void ) |
The Help button was pressed. This signal is only emitted if slotHelp() is not replaced.
void defaultClicked ( void ) |
The Default button was pressed. This signal is only emitted if slotDefault() is not replaced.
void user3Clicked ( void ) |
The User3 button was pressed. This signal is only emitted if slotUser3() is not replaced.
void user2Clicked ( void ) |
The User2 button was pressed. This signal is only emitted if slotUser2() is not replaced.
void user1Clicked ( void ) |
The User1 button was pressed. This signal is only emitted if slotUser1() is not replaced.
void applyClicked ( void ) |
The Apply button was pressed. This signal is only emitted if slotApply() is not replaced.
void tryClicked ( void ) |
The Try button was pressed. This signal is only emitted if slotTry() is not replaced.
void okClicked ( void ) |
The OK button was pressed. This signal is only emitted if slotOk() is not replaced.
void yesClicked ( void ) |
The Yes button was pressed. This signal is only emitted if slotYes() is not replaced.
void noClicked ( void ) |
The No button was pressed. This signal is only emitted if slotNo() is not replaced.
void cancelClicked () |
The Cancel button was pressed. This signal is only emitted if slotCancel() is not replaced.
void closeClicked () |
The Close button was pressed. This signal is only emitted if slotClose() is not replaced.
void apply ( void ) |
Do not use this signal. Is is kept for compatibility reasons. Use applyClicked() instead.
void backgroundChanged ( void ) |
The background tile has changed.
void hidden ( void ) |
The dialog is about to be hidden.
If you have stored a pointer to the dialog do @bf not try to delete the pointer in the slot that is connected to this signal. Instead you must start a timer and delete the pointer when this timer expires.
QFrame * plainPage ( void ) |
Returns the empty page when the predefined layout is used in Plain mode. This widget must used as the toplevel widget of your dialog code.
Returns: The widget or 0 if the predefined layout mode is not Plain or if you don't use any predefined layout
QFrame * addPage ( const QString &item, const QString &header=QString::null ) |
Adds a page to the dialog when the class is used in TreeList or Tabbed mode. The returned widget must be used as the toplevel widget for this particular page. Note: The returned frame widget has no layout manager associated with it. In order to use it you must create a layout yourself as the example below illustrates:
QFrame *page = addPage( i18n("Layout") ); QVBoxLayout *topLayout = new QVBoxLayout( page, 0, 6 ); QLabel *label = new QLabel( i18n("Layout type"), page ); topLayout->addWidget( label ); ..
Parameters:
item | Name used in the list (TreeList mode) or Tab name (Tabbed mode). |
header | Header text use in TreeList mode. Ignored in Tabbed mode. If empty, the item text is used instead. |
Returns: The page widget which must be used as the toplevel widget for the page.
QVBox * addVBoxPage ( const QString &itemName, const QString &header=QString::null ) |
Adds a page to the dialog when the class is used in TreeList or Tabbed mode. The returned widget must be used as the toplevel widget for this particular page. The widget contains a QVBoxLayout layout so the child widgets are lined up vertically. You can use it as follows:
QVBox *page = addVBoxPage( i18n("Layout") ); QLabel *label = new QLabel( i18n("Layout type"), page ); ..
Parameters:
item | Name used in the list (TreeList mode) or Tab name (Tabbed mode). |
header | Header text use in TreeList mode. Ignored in Tabbed mode. If empty, the item text is used instead. |
Returns: The page widget which must be used as the toplevel widget for the page.
QHBox * addHBoxPage ( const QString &itemName, const QString &header=QString::null ) |
Adds a page to the dialog when the class is used in TreeList or Tabbed mode. The returned widget must be used as the toplevel widget for this particular page. The widget contains a QHBoxLayout layout so the child widgets are lined up horizontally.
Parameters:
item | Name used in the list (TreeList mode) or Tab name (Tabbed mode). |
header | Header text use in TreeList mode. Ignored in Tabbed mode. If empty, the item text is used instead. |
Returns: The page widget which must be used as the toplevel widget for the page.
QGrid * addGridPage ( int n, QGrid::Direction dir, const QString &itemName, const QString &header=QString::null ) |
Adds a page to the dialog when the class is used in TreeList or Tabbed mode. The returned widget must be used as the toplevel widget for this particular page. The widget contains a QGridLayout layout so the child widgets are positioned in a grid.
Parameters:
n | Specifies the number of columns if 'dir' is QGrid::Horizontal or the number of rows if 'dir' is QGrid::Vertical. |
dir | Can be QGrid::Horizontal or QGrid::Vertical. |
item | Name used in the list (TreeList mode) or Tab name (Tabbed mode). |
header | Header text use in TreeList mode. Ignored in Tabbed mode. If empty, the item text is used instead. |
Returns: The page widget which must be used as the toplevel widget for the page.
QFrame * makeMainWidget ( void ) |
Makes a main widget. The function will make a QFrame widget and use setMainWidget to register it. You can NOT use this function more than once, NOT if you have already defined a main widget with setMainWidget and NOT if you have used the constructor where you define the face (Plain, Swallow, Tabbed, TreeList).
Returns: The main widget or 0 if any of the rules described above were broken.
QVBox * makeVBoxMainWidget ( void ) |
Makes a main widget. The function will make a QVBox widget and use setMainWidget to register it. You can NOT use this function more than once, NOT if you have already defined a main widget with setMainWidget and NOT if you have used the constructor where you define the face (Plain, Swallow, Tabbed, TreeList).
Returns: The main widget or 0 if any of the rules described above were broken.
QHBox * makeHBoxMainWidget ( void ) |
Makes a main widget. The function will make a QHBox widget and use setMainWidget to register it. You can NOT use this function more than once, NOT if you have already defined a main widget with setMainWidget and NOT if you have used the constructor where you define the face (Plain, Swallow, Tabbed, TreeList).
Returns: The main widget or 0 if any of the rules described above were broken.
QGrid * makeGridMainWidget ( int n, QGrid::Direction dir ) |
Makes a main widget. The function will make a QGrid widget and use setMainWidget to register it. You can NOT use this function more than once, NOT if you have already defined a main widget with setMainWidget and NOT if you have used the constructor where you define the face (Plain, Swallow, Tabbed, TreeList).
Parameters:
n | Specifies the number of columns if 'dir' is QGrid::Horizontal or the number of rows if 'dir' is QGrid::Vertical. |
dir | Can be QGrid::Horizontal or QGrid::Vertical. |
Returns: The main widget or 0 if any of the rules described above were broken.
void keyPressEvent ( QKeyEvent *e ) |
Maps some keys to the actions buttons. F1 is mapped to the Help button if present and Escape to the Cancel or Close if present. The button action event is animated.
void hideEvent ( QHideEvent * ) |
Emits the hidden signal. You can connect to that signal to detect when a dialog has been closed.
void closeEvent ( QCloseEvent *e ) |
Detects when a dialog is being closed from the window manager controls. If the Cancel or Close button is present then the button is activated. Otherwise standard QDialog behavior will take place.
void slotHelp ( void ) |
Activated when the Help button has been clicked. If a help text has been defined, the help system will be activated.
void slotDefault ( void ) |
Activated when the Default button has been clicked.
void slotUser3 ( void ) |
Activated when the User3 button has been clicked.
void slotUser2 ( void ) |
Activated when the User2 button has been clicked.
void slotUser1 ( void ) |
Activated when the User1 button has been clicked.
void slotOk ( void ) |
Activated when the Ok button has been clicked. The QDialog::accept() is activated.
void slotApply ( void ) |
Activated when the Apply button has been clicked.
void slotTry ( void ) |
Activated when the Try button has been clicked.
void slotYes ( void ) |
Activated when the Yes button has been clicked. The QDialog::done( Yes ) is activated.
void slotNo ( void ) |
Activated when the Yes button has been clicked. The QDialog::done( No ) is activated.
void slotCancel ( void ) |
Activated when the Cancel button has been clicked. The QDialog::reject() is activated in regular mode and QDialog::done( Cancel ) when in message box mode.
void slotClose ( void ) |
Activated when the Close button has been clicked. The QDialog::reject() is activated.
void applyPressed ( void ) |
Do not use this slot. Is is kept for compatibility reasons. Activated when the Apply button has been clicked
void updateGeometry ( void ) |
Updates the margins and spacings.