Next Previous Table of Contents

6. The Dialogeditor: Where your Dialogs are Build

6.1 What the Dialogeditor provides

The built-In dialogeditor of KDevelop is designed to help you construct widgets and dialogs that fit your application's purpose and reduces the time rapidly to extend the GUI of your application. The only limitation for now is that the dialogeditor does not support geometry management that is provided by Qt; therefore the dialogs are static in their size and this may lead to certain circumstances where e.g. the label width is not long enough to support the full length of a translation.

On the other hand, the current state of the editor in conjunction with KDevelop's project management offers the fastest way to create full-featured applications for the K Desktop Environment.

6.2 Qt and KDE Widgets

Currently provided widgets are:

QT-Widgets:

• QWidget - a widget that can be specified by yourself and can contain other widgets as well. This allows creating a widget hierarchy within your dialog.
• QLabel - a label that represents text information on the widget. Use QLabel e.g. in front of lineedits to signal what the purpose of the line-edit is or which variable e.g. a combo box allows to set.
• QPushButton - a button that allows to e.g. call another dialog like QFileDialog for selecting a filename.
• QCheckBox - a check box for e.g. enabling/disabling options. QCheckBox is widely used for configuration dialogs.
• QLCDNumber - displays numbers in LCD style. Often used for clocks.
• QRadioButton - like QCheckBox often used to let the user set any options. QRadioButton specializes the options setting when more of them depend on each other, e.g. you have three radio-buttons, but you want the user to choose one of three offered options. See QButtonGroup for additional information.
• QComboBox - a combo box lets the user set a value by selecting it from a drop-down menu or by inserting the value, if the box is write enabled.
• QListBox - provides a single-column list of items that can be scrolled.
• QListView - creates a multi-column list view that can be used to display e.g. file trees etc. in tree and table view.
• QMultiLineEdit - offers a multi-line editor.
• QProgressBar - displays the progress of an action that takes a longer time to be finished.
• QSpinBox - allows choosing numeric values by up- and down buttons or insertion if write enabled.
• QSlider - sets a value in a program-defined range by a slider.
• QScrollBar - indicates the range of a value and sets the current value by a slider as well as up- and down buttons; often used for widgets whose contents is larger than the actually visible view area. By using the scrollbar, the visible area can be changed to another part of the widgets' contents.
• QGroupBox - provides a group box frame with title to indicate that child widgets within the box belong together.

KDE-Widgets:

• KColorButton - a pushbutton displaying a selected color. On a button press, the KDE Color dialog is shown where the user can select another color. Often used for drawing applications or in any case where color values can be set.
• KCombo - similar to QComboBox. Lets the user choose a value by a drop-down list box.
• KDatePicker - a complete widget to get a date value by the user.
• KDateTable - a calendar table to select a date of a month. Used by KDatePicker to build the date picker dialog.
• KKeyButton - a button to select a key value. If the button is selected, it gets activated. Pressing a keyboard button will change the key value for the button which can be used to configure key-bindings.
• KLed - and LED (Light Emitting Diode) widget to display a certain state.
• KLedLamp - and LED lamp that also supports click actions
• KProgress - similar to QProgressBar, KProgress supports certain other values.
• KRestrictedLine - a QLineEdit that only accepts certain user input. This can be used to restrict access to certain data by password dialogs.
• KSeparator - a separator widget to be used in all cases where KDE applications require a separator to provide a unique look. Often used in dialogs to separate logical parts where QGroupBox doesn't fit.
• KTreeList - a collapsible list view to display trees similar to QListView.

6.3 Properties of Qt supported Widgets

The following chapter gives a complete overview over the currently supported widgets of the Qt toolkit. To achieve a better understanding of the properties, these are separated to their inheritance. As all of them inherit QWidget, this class is described first. All QWidget properties are available for all other widgets as well, so these are not listed for them again. For widget groups that inherit an abstract subclass of QWidget as their base-class, the base-classes' properties are listed first (though this class does not provide a widget in the dialogeditor itself). Then the widget properties for the available widget of the group contains the properties that are specific to it. For a better understanding the inheritance tree of the available widgets is listed below:

• QWidget
  • QButton (abstract)
    • QCheckBox
    • QPushButton
    • QRadioButton
  • QComboBox
  • QFrame (abstract for now)
    • QGroupBox
    • QLCDNumber
    • QLabel
    • QProgressBar
    • QScrollView (abstract for now)
      • QListView
    • QSpinBox
    • QTableView (abstract)
      • QListBox
      • QMultiLineEdit
  • QLineEdit
  • QScrollBar
  • QSlider

QWidget Properties

QWidget is the base class for almost all widgets in Qt and KDE. Therefore widgets that inherit QWidget will allow to use the same settings in most cases.

• Appearance:
  • BgColor: Background color of the widget
  • BgMode: Background mode of the widget
  • BgPalColor: Color pallette for the background
  • BgPixmap: filename for a background pixmap
  • Cursor: Cursor over the widget
  • Font: Font for the widget
  • MaskBitmap: filename for a masking bitmap.
• C++ Code:
  • AcceptsDrops: if set to true, the widget item will accept drops by drag'n drop mechanisms (Qt drag'n drop protocol, not KDE 1.x !)
  • Connections: connects the item's signals to slots
  • FocusProxy: the item that gives its focus to this widget.
  • HasFocus: sets if the item has the focus by default. Mind that only one item per dialog can have this value as true
  • ResizeToParent: resizes the widget to its parent's size (not visible in editing mode)
  • VarName: Variable name of the item. Change this to names that describe the item's purpose.
• General:
  • IsEnabled: sets if the widget will accept user events
  • IsHidden: sets the item to be visible(false) or hidden(true)
  • Name: sets the name of the widget. Mind that the name is different from the VarName in C++ Code.
• Geometry:
  • Height: height of the item
  • IsFixedSize:
  • MaxHeight: maximum value for Height
  • MaxWidth: maximum value for Width
  • MinHeight: minimum value for Height
  • MinWidth: minimum value for Width
  • SizeIncX: pixel steps for resize actions to X direction
  • SizeIncY: pixel steps for resize actions to Y direction
  • Width: width of the item
  • X: position horizontal, counted from the left corner
  • Y: position vertical, counted up to down

QButton inherited widgets

QButton is an abstract widget class that provides properties common to buttons.

Inherits QWidget

Inherited by QCheckBox, QPushButton and QRadioButton inherit QButton.

• Appearance:
  • setPixmap: sets the pixmap filename to use
• General:
  • setText: the text on labels, buttons and boxes, also pre-set text for lineedits.
  • setAutoRepeat: if enabled, the clicked() signal is emitted at regular intervals while the button is down. No effect on toggle buttons.
  • setAutoResize: Enables auto-resizing if TRUE. When auto-resize is enabled, the button will resizes itself whenever the contents changes.

QCheckBox Properties

Inherits QWidget and QButton

• General:
  • isChecked: (setChecked) defines is the checkbox is set checked on construction

QPushButton Properties

Inherits QWidget and QButton

• General:
  • isAutoDefault: (setAutoDefault) the auto-default button becomes the default push button if it receives the keyboard input focus.
  • isDefault: (setDefault) there can be only one default button and it is only allowed to use in a dialog (see QDialog). The default button emits clicked() if the user presses the Enter key.
  • isMenuButton: (setIsMenuButton) tells the button to draw a menu indication triangle if enabled. The menu has to be inserted separately.
  • isToggleButton::(setToggleButton) makes a push button a toggle button, so the button has a similar state as check boxes.
  • isToggledOn: (setOn) (public slot) switches a toggle button on.

QRadioButton Properties

Inherits QWidget and QButton

• General:
  • isChecked: (setChecked) defines is the radio button is set checked on construction

QComboBox Properties

Inherits QWidget

( no additional properties for now)

QFrame inherited widgets

Inherits QWidget

For now only used as an abstract class.

• Appearance:
  • Margin (setMargin): sets the margin, which is the distance from the innermost pixel of the frame and the outermost pixel of the contents.

QGroupBox Properties

Inherits QWidget and QFrame

• General:
  • Title: (setTitle) sets the group box title that is displayed in the box frame.

QLCDNumber Properties

Inherits QWidget and QFrame

• General:
  • NumDigits:(setNumDigits) sets the number of digits displayed in QLCDNumber
  • Value: (display) (public slot) sets the initial value for QLCDNumber

QLabel Properties

Inherits QWidget and QFrame

• Appearance:
  • Margin (setMargin): sets the margin, which is for QLabel the distance from the frame to the first letter of the label text, depending on the alignment of the label.
• C++ Code:
  • Buddy: (setBuddy) sets the buddy widget of the label.
• General:
  • Text: (setText) sets the label text.
  • isAutoResize: (setAutoResize) if TRUE, the label will resize itself if the contents changes. The top left corner is not moved.

QProgressBar Properties

Inherits QWidget and QFrame

• General:
  • TotalSteps: (setTotalSteps) (public slot) sets the total steps of the progress bar. During the iteration of your action to display the progress, you have to call setProgress(int) to advance the progress step displayed to (int).

QScrollView

Inherits QWidget and QFrame

Inherited by QListBox (abstract for now)

Provides a scrollable widget that manages the display of a child widget by a vertical and horizontal scrollbar.

QListView

Inherits QWidget, QFrame and QListView

Provides a list view to display hierarchical data either in a table or a tree. Manages itself by scrollbars through QScrollView.

• Appearance:
  • ListViewFont: (setFont()) Sets the font of the ListView items
  • ListViewPalette: (setPalette()) Sets the palette of the list view items
  • TreeStepSize: (setTreeStepSize(int)) Offset of pixels of a child item to its parent item
  • hScrollBarMode: Scrollbar mode provided by QScrollView for the horizontal scrollbar
  • isAllColumnsShowFocus: (setAllColumnsShowFocus(bool)) displays focus on all columns of an item.
  • isMultiSelection: enables multi-selection of list items
  • isRootDecorated: enables the + and - decoration to open and close trees
  • vScrollBarMode:Scrollbar mode provided by QScrollView for the vertical scrollbar
• General:
  • Entries: lets you insert a list of entries that are pre-set as QListViewItems.
  • isAutoUpdate:

QSpinBox Properties

Inherits QWidget and QFrame

• General:
  • MaxValue: the maximum value the user can choose
  • MinValue: the minimum value the user can choose
  • Prefix:
  • Suffix:
  • Value: the pre-set value when the widget is shown
  • isWrapping:

QTableView inherited widgets

Inherits QWidget, QFrame and QTableView

Inherited by QListBox and QMultiLineEdit

QListBox Properties

Inherits QWidget, QFrame and QTableView

• General:
  • isAutoBottomScrollBar: (setAutoBottomScrollBar)
  • isAutoScroll: (setAutoScroll)
  • isAutoScrollBar: (setAutoScrollBar)
  • isAutoUpdate: (setAutoUpdate)
  • isBottomScrollBar: (setBottomScrollBar)
  • isDragSelect: (setDragSelect)
  • isSmoothScrolling: (setSmoothScrolling)
• Geometry:
  • setFixedVisibleLines: sets a fixed height for the widget so that the given number of text lines are displayed using the current font.

QMultiLineEdit Properties

Inherits QWidget, QFrame and QTableView

• General:
  • Text: (setText) (public slot) sets the text of the widget.
  • isAutoUpdate: (setAutoUpdate) used to avoid flicker during large changes; the view is not updated if disabled.
  • isOverWriteMode: (setOverwriteMode) (public slot) sets overwrite enabled or disabled.
  • isReadOnly: (setReadOnly) (public slot) sets the widget text to read only; disables text input.
  • isTextSelected: (selectAll)(public slot) marks the whole text selected
• Geometry:
  • setFixedVisibleLines: sets a fixed height for the widget so that the given number of text lines are displayed using the current font.

QLineEdit Properties

Inherits QWidget

• General:
  • CursorPosition: (setCursorPosition) sets the default cursor position.
  • MaxLength: (setMaxLength) sets the maximum string length
  • Text: (setText) (public slot) sets the contents displayed on construction
  • hasFrame: (setFrame) draws the line edit within a two-pixel frame if enabled.
  • isTextSelected: (selectAll) (public slot) sets the text to be selected.

QScrollBar Properties

Inherits QWidget and QRangeControl.

• General:
  • MaxValue: sets the maximum slider value; used in constructor (optional)
  • MinValue: sets the minimum slider value; used in constructor (optional)
  • Orientation: (setOrientation) sets the orientation of the scrollbar to horizontal or vertical.
  • Value: sets the initial value of the scrollbar in the constructor (optional)
  • isTracking: (setTracking) if enabled, the scrollbar emits valueChanged() whenever the bar is dragged; otherwise only on mouse release.

QSlider Properties

Inherits QWidget and QRangeControl.

• General:
  • MaxValue: sets the maximum slider value; used in constructor (optional)
  • MinValue: sets the minimum slider value; used in constructor (optional)
  • Orientation: (setOrientation) sets the orientation of the slider to horizontal or vertical.
  • Value: (setValue) (public slot) uses QRangeControl::setValue() to set the value.
  • isTracking:(setTracking) if enabled, the slider emits valueChanged() whenever the slider is dragged; otherwise only on mouse release.

6.4 Properties of KDE supported Widgets

• QWidget
  • QButton (abstract)
    • QPushButton
      • KColorButton
      • KKeyButton
  • QComboBox
    • KCombo
  • QFrame (abstract for now)
    • KDatePicker
    • KLedLamp
    • KProgress
    • KSeparator
    • QTableView (abstract)
      • KDateTable
      • KTreeList
  • QLineEdit
    • KRestrictedLine
• KLed

KColorButton

Inherits QPushButton

• General
  • DisplayedColor (setColor()) the displayed color on the button

KKeyButton

KCombo

Inherits: QComboBox

• General
  • Entries the string list of entries displayed in the combo box
  • Text the text displayed in the combo box currently
  • isAutoResize resizes the combo box to the current item

KDatePicker

• Appearance
  • FontSize the font size for the date picker

KLedLamp

KProgress

KSeparator

• General
  • Orientation sets the orientation of the separator to horizontal or vertical; default is horizontal

KDateTable

KTreeList

• Appearance
  • TreeListBgColor
  • TreeListPalette
  • isBottomScrollbar
  • isScrollBar
  • isShowItemText
  • isSmoothScrolling
  • isTreeDrawing
• General
  • Entries
  • isAutoUpdate

KRestrictedLine

KLed

Inherits QWidget

• Appearance
  • LedColor: (setColor()) sets the displayed LED color

6.5 Constructing a new Dialog

Constructing a new dialog is very easy if you already have experience with graphical construction applications. KDevelop offers to create a widget visually and displays the look as it will be shown to the user directly. Further, you can have a preview of your widget by selecting "Preview" from the "View" menu.

To begin constructing a dialog or any other widget, switch to the Dialogeditor and select "New" from the "File" menu. Select "Qt/KDE Dialgo (*.kdevdlg) from the New File dialog and enter the dialog filename. Construct your dialog and when you´re finished, select "Generate all Sources" from the "Build"-menu.

Then enter all needed information to the appearing dialog. Those are:

1. The Dialog inheritance. This is necessary because any widget is at least derived from QWidget. Besides the widget types provided by Qt, you can inherit e.g. form an abstract base class you constructed yourself within your project. In this case, select "custom" and enter the header file path to the line edit below.
2. The Dialog name. This sets the class name of the generated dialog. Select a classname that is descriptive for what the dialog does; in cases of inheritance from QDialog, you may enter a name that ends with Dlg to remember yourself it's a dialog. Naming convention should match that of KDE and Qt: Use uppercase letters for your classname. For e.g. a grid-size selection dialog, you would enter GridSizeDlg.
3. The generated filenames. Those are preset when entering the dialog name, but can be changed afterwards. If you want to use other filenames, the naming convention should also match that of KDE and Qt: the filenames are all lowercase and contain the classname to remember what class is kept where. The data file that has to be set will later contain the generated code that will build up your dialog. You should not edit this file manually afterwards; use the implementation file for any additions towards dialog construction code and method implementations.

The dialog will then show itself as a widget with a grid. As the dialogeditor uses the grid to snap any child widgets to the geometry, you can change the grid size with the "Grid Size" entry in the "View" menu, if the preset values don't match your needs.

Then select the "Widgets" tabulator on the left pane and press the button for the widget item you want to add to the main widget. It directly appears on the main widget's left upper corner and gets selected by a resizable frame. Then move or resize the widget with the mouse. The cursor will change to indicate which action can be done at the current position.

After having finished the construction, select "Generate Files" from the "Build" menu or hit the according toolbar button. The files will then be generated at the preset location and included into your project sources. A rebuild or make will compile all generated files within your project and you can add the according constructor call to the application to invoke the dialog or widget. For KDE projects, all widget properties that will be visible later, e.g. label texts, are set with the i18n() macro of kapp.h to support internationalization. Therefore you should do a "Make Messages and merge" when finished with construction and implementation.

When creating a dialog or widget, you should watch the following guidelines:

• Always try to be consistent! This is probably the most important rule when constructing GUI elements. Mind that the user will only accept an application that is easy to understand no matter how complex it's purpose may be.
• Add help wherever you can by tool-tips, What's this..? help or Quick-help. This allows getting direct information about the purpose of the GUI elements.
• watch the keyboard focus ! The generator does not take care of that- this has to be watched when constructing any widget; otherwise you have to reorder your initialization code by hand which is a very unthankful job. The keyboard focus on any widget means the oder on which items get the keyboard input focus when the user presses the tab and shift+tab button. It would be very annoying if the focus changes everywhere but not to the next widget visible below or to the right of the current widget. Therefore start constructing your widget top down from left to right to ensure the consistency of the focus.

6.6 Setting Widget Properties

Widget properties can be set easily with the properties window entries. When a widget gets selected, the properties window automatically updates to the properties of the current widget. As all widgets are derived from QWidget, you can set the QWidget properties plus an amount of properties that are specific to the selected widget. Properties can be:

• Integer values, such as the geometry of a widget or the font size
• Boolean values to enable/disable certain parameters of the widget. Set with combos containing true and false
• enumerable values of a widget, e.g. the palette. Set with combos containing all possible values
• Color values for e.g. the displayed color. Set with the KDE Color Dialog
• Font values for e.g. labels. Be careful to set Font values other than the default because this may prevent KDE from updating the font. Set with the KDE Font Dialog
• File names for e.g. background pixmaps. Do not use gif images here as these may get unsupported by further Qt versions > 1.42

6.7 Integrating the Dialog

Whenever you created a widget, you probably want to add it to the project to execute the action it is designed for. As a widget can be constructed for several purposes, we will watch for two cases: a QWidget inherited widget and a QDialog one.

QWidget inherited

Let's say you created a widget that will be part of the main view. If it fills the whole view area, you have to add an instance pointer to the header declaration of your KTMainWindow instance replacing the currently set view widget. Then change the code in the initView method to set this widget the main view. Additionally, you could remove the View class of the generated project, but mind that the document instance and the App instance depends on the view class. In this case, it is technically a much better way to create a mini-KDE application and construct your KTMainWindow instance yourself.

More often the widget is intended to be a part of the view area, which means it is combined with other widgets. This can be done by using one of the following classes that provide a divider to separate two widgets:

1. QSplitter
2. KPanner
3. KNewPanner

If the main view shall contain more than two widgets, you have to use another instance of the divider as one of the two managed widgets by the first one. Then add the according widgets to each panner and set the first panner the view area.

QDialog inherited

If your widget inherits QDialog, it is probably intended to change one or more values; often this is used to set the application preferences. To invoke the dialog, you have to add a slot to the App class by adding the method declaration and the implementation body. Then add the constructor call to the method as well as a call to show() or exec() the dialog. Finally, you should take care for processing the results of the dialog; this can either be done by the dialog who changes values of the parent widget itself or by retrieving the values from the dialog (which would make your dialog a lot more reusable in other projects). Mind that you should call delete if you called the dialog instance with new to avoid memory leaks.

Finally, you have to connect a menuentry (with according statusbar help) to the new slot invoking the dialog; optionally a keyboard accelerator and a toolbar icon. For this, add a resource ID to the file resource.h with a define. Then add an according menuentry to one of the popup menus already present in the menubar or create a new popup to add your menuentry. The menuentry consists of:

• an optional icon pixmap. Call this with the Icon("iconname.xpm") macro of KApplication to use the provided KIconLoader instance.
• the menuentry name. Add this with the i18n("&entryname") macro of KApplication to allow internationalization. The ampersand should be in front of the letter that will be displayed underlined to access the entry directly by keyboard acceleration.
• the member instance to call. Normally this would be the this pointer.
• the member slot to call. Use SLOT(yourmethod() to call the slot on the signal activated().
• the accelerator key. This should be set to zero as this is done by an entry in initKeyAccel() where you have to introduce an accelerator key together with the slot to call. Then call changeMenuAccel() to change the menu item's accelerator . This will make it configurable by a key-chooser dialog later. For standard actions, use the enumerable values given by KAccel.
• the menu ID as set in resource.h

Next Previous Table of Contents