Compound list   Compound Members  

DialogBase Class Reference

This base class provides basic functionality needed by nearly all dialogs. More...

List of all members.

Public Members

Public Slots

Signals

Static Public Members

Protected Members

Static Protected Members


Detailed Description

This base class provides basic functionality needed by nearly all dialogs.

It offers three standard buttons, OK , Apply and Cancel, a complete geometry management that relies on the minimum size you set for the contents, and the possibility to set background tiles for parts of the window. See the KDE addressbook for some examples how this dialogs look.

The standard buttons
The buttons are configurable in some aspects and are already connected to the appropriate slots:
  1. OK: accept() (from QDialog)
  2. Apply: applyPressed() (not defined by Qt, but declared virtual for overloading), sends signal "apply" to be connected to your code.
  3. Cancel: reject() (from QDialog)

The main widget
The inner frame of a freshly created object is empty. To use it, you need to set a Qt widget as the main widget of the dialog using setMainWidget(). If you do not want to bother with geometry management yourselfes, just set a minimum size for the widget. The dialog will automatically take care of it and ajust its own minimum size. The size of the dialog is not fixed.
Often the dialog should be adjusted in its size on startup. The class does not do this by default, as sometimes it is not wanted. After setting the main widget the dialog has a minimum size set, so you may use:
YourDialog.resize(YourDialog.minimumSize());
With this, your dialog starts up in its minimum size, but is still resizeable by the user.

The layout
The class inserts a base frame and an inner frame that are resized automatically if you call the resizeEvent function of this class in your resizeEvent if you derived it. Also the buttons are placed this way. The inner frame is set inside the base frame above of the buttons. Both the base and the inner frame get background tiles as a static image provided by the class. This way you can achieve that all your dialogs look the same way all over your application. All dialog derived from this class used in one program get the background that is set centrally.
The class has been initially created using QtArchitect.


Member Function Documentation

DialogBase::DialogBase(QWidget* parent=0, const char* name=0, bool modal=true)

The Qt standard constructor.

virtual DialogBase::~DialogBase() [virtual]

The destructor.

void DialogBase::showBaseFrameTile(bool state)

The background mode - either showing the selected tile or the standard background color - can be switched independently for the outer and the inner frame.

This method sets this property for the inner frame. If state is true, the background tile is displayed. If not, the standard background color is used.

void DialogBase::showMainFrameTile(bool state)

Select the background mode for the outer frame.

See also:
setBackgroundTile()

void DialogBase::enableButtonOK(bool state)

Enable the OK button if state is true (default).

void DialogBase::enableButtonApply(bool state)

Enable the Apply button if state is true (default).

void DialogBase::enableButtonCancel(bool state)

Enable the Cancel button if state is true (default).

void DialogBase::showButtonOK(bool state)

Show the OK button if state is true (default).

void DialogBase::showButtonApply(bool state)

Show the Apply button if state is true (default).

void DialogBase::showButtonCancel(bool state)

Show the Cancel button if state is true (default).

QRect DialogBase::getContentsRect()

This method returns the contents rectangle of the inner frame.

Place your widgets inside this rectangle, and use it to set up their geometry. Be carefull: 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 element, use getBorderWidth.

void DialogBase::getBorderWidths(int& ulx, int& uly, int& lrx, int& lry) const

This method returns the border widths in all directions that the dialog needs for itselfes.

Respect this, or get bad looking results. The references are upper left x, upper left y, lower left x and lower left y. The results are differences in pixels from the dialogs corners.

QSize DialogBase::calculateSize(int w, int h)

With this method it is more easier to calculate a size hint for a dialog derived from DialogBase if you now 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.

void DialogBase::setMainWidget(QWidget*)

This method is meant to make the management of simple layouts easier.

You may assign (and remove) a main widget to the dialog. This main widget will be placed exactly fitting into the frame rectangle of the inner frame. This is usefull if the widget you insert is managed by a Qt layout manager, for example (or by your own resizeEvent handler). Make sure to set the minimum size of the dialog using one of the methods above (Note: if the main widget provided by you has a minimum size the dialogs minimum size is automatically adapted to this size, no need to bother).
If you set a main widget and there is already one, this previous main widget will NOT be deleted. This way you may switch between different widgets for example by hiding the old one and setting the new one as main. The dialog does not manipulate the visibility state of your widget, only its geometry.
If you replace a previous main widget, the old one is still visible. Hide it, or place it somewhere else.

QWidget* DialogBase::getMainWidget()

Returns the main widget or zero if there is none.

void DialogBase::updateBackground() [slot]

Called when the background changed.

void DialogBase::initializeGeometry() [slot]

Initialize dialog geometry.

void DialogBase::setDesc(const char*) [slot]

Set the dialogs description.

void DialogBase::apply() [signal]

The apply button was pressed.

void DialogBase::backgroundChanged() [signal]

The background tile has changed.

bool DialogBase::haveBackgroundTile() [static]

This returns whether the background tile is set or not.

const QPixmap* DialogBase::getBackgroundTile() [static]

This returns a const pointer to the background tile if there is one.

void DialogBase::setBackgroundTile(const QPixmap*) [static]

This method sets the background tile.

If it is Null (0), the background image is deleted.

void DialogBase::emitBackgroundChanged() [protected]

Emits the signal backgroundChanged().

void DialogBase::resizeEvent(QResizeEvent*) [protected]

The resize event.

void DialogBase::applyPressed() [protected]

Called when apply button is pressed.


Member Data Documentation

QWidget* DialogBase::main [protected]

The main widget.

bool DialogBase::mainTile [protected]

Show the outer frame background tile if true.

bool DialogBase::baseTile [protected]

Show the base frame background tile if true.

QPixmap* DialogBase::tile [static, protected]

The background tile.

const int DialogBase::Grid [static, protected]

The default grid spacing.

DialogBase* DialogBase::dummy [static, protected]

For internal use only.


The documentation for this class was generated from the following file:

The KDE Addressbook Developers Reference 
Mirko Sucker, 1999