Next Previous Table of Contents

### 11. The Dialog Editor

The KDevelop integrated dialog editor allows the easy construction of widgets and dialogs your application uses all by graphical means. You see the direct appearance of your dialog as it will be presented to the user. Using the dialog editor is usually the first step you would take after creating a new project with the KAppWizard to create your main view, the user interaction dialogs and, after finishing the graphical work, the code generation. This way, your project will contain all the usually considered "difficult" parts that normally would take a long time to implement. Then, the "rest" of your work is implementing the functionality in the generated code. This chapter deals with how to use the dialog editor to create your project widgets as well as what to do in case you see your widgets need corrections or additions during the further development process.

You can switch to the dialog editor either by selecting "Dialog Editor" from the "View"-menu or by the according toolbar icon. To switch back to the Project Editor, select "KDevelop" from the dialog editor's "View"-menu or by the icon in the toolbar.

What else does the dialog editor's interface offer you ? Mainly, that its appearance is almost the same as the project editor in term of the main view separation as well as the menu- and toolbars. This allows you to make yourself accustomed with the dialog editor very quickly and, as he completely interacts with the project management, stay in the dialog editor if you want to control your build-process. Actions that require to switch back to KDevelop will do that automatically for you, like accessing the documentation browser. Just select the menu commands, and KDevelop reacts to your will.

The following chapters give you an overview of the dialog editor interface, how to create a new dialog initially and how set up the properties of the child widgets that your dialog contains.

### 11.1 The Dialog Editor View

#### The Mainview

The dialog editor's view is logically separated by:

- The Widgets Tabulator, containing the "Widgets", "Dialogs" and "Items" tabs. These are described in Adding Widgets.
- The Widget-Editor, representing the editing view for creating your dialog. See The Widget Editor
- The Properties window, containing a list of properties and their values, dependent on the currently selected widget in the widget editor. See Setting Properties for information how to specialize the widget's behavior and look.

#### Menubar, Toolbar and Statusbar differences to KDevelop

In Dialogeditor mode, KDevelop changes the menubar, toolbar and statusbar slightly to provide the functionality you need for creating widgets. These are:

#### Menubar

"File"-menu: replaces "New" with "New Dialog". "Open" allows to open a dialog definition file.

"View"-menu: replaces "Tree-View" with "Widgets-View", en/disabling the Widgets-View tabulators; adds "Properties-View" to en/disable the Properties-View and "Grid Size" to let you specify the grid size in pixels for horizontal and vertical values.

"Build"-menu: replaces "Compile File" with "Generate Sources". This lets you actually generate the sources for your dialog.

#### Toolbar

The toolbar contains a new icon for "New Dialog" as well as a replacement for "Compile File" by "Generate Sources".

#### Statusbar

The statusbar is providing you information about the currently selected widget, especially displaying the values for X and Y size in the coordinate system. For Statusbar help, you are provided the same functionality than in Project-editing mode.

While changing widget size, the statusbar shows the current values for width and height of the selected widget.

### 11.2 Creating a New Dialog

After creating your project skeleton, you are provided a ready-to-run application, according to your preferences. As KDevelop provides the project types KDE and Qt application, the dialog editor recognizes this and offers widget construction by the widgets that are provided by the used libraries. To save time, you already should have a design in mind that will do the intended actions. For information about widget design, see The KDevelop Programming Handbook.

To create a new dialog, select "New" from the "File"-menu or select "New" from the context menu in the "Dialogs" tab. The "New Dialog" menu appears where you have to give KDevelop the dialog-specific information about the baseclass and the source file names and destination.

#### Dialog Class

The dialog class you can select, is the class that is inherited by your new widget, which is technically represented by a class itself. Therefore, you have the following options:

1. QWidget: the base class for all user interaction widgets provided by Qt. Used for main views and top-level widgets.
2. QFrame: inherits `QWidget` and is used by numerous widgets as a base class. This is useful for widgets that already want to have a `QFrame` functionality in addition to `QWidget` methods.
3. Custom: inherits a custom class that has to be set in the "Custom Properties". This could be an already designed class provided by your project or the libraries.
4. QDialog: the base class for dialogs that you would inherit for user interaction like setting properties or changing values.
5. QTabDialog: inherits QDialog and provides a dialog with predefined buttons and a set of tabs, which you will provide by the widgets that you create.

Custom Properties

For the inheritance of a custom class as selected in the dialog class field, you have to specify the classname, which goes to "Custom Class". The dialog editor uses this for the code-generation; therefore, you also have to insert the "Custom Header", where the header filename of the custom class has to be set.

#### Files

In the "Files" section, you have to enter the widget's specific information. This is the classname (which would be e.g. KColorSelectDlg for a dialog that allows selecting the color of a pen), the header, C++ and Data filenames. When inserting the Classname, the filenames are given by the dialog editor, but you can as well change the filenames.

Now, what about the files ? When you are ready with constructing the widget visually, you will have to generate the files that contain the implementation for your widget. As this will be a class, the dialog will exist by the header file containing the classdeclaration, a C++ file containing the method implementation for your widget's methods and slots. The Data file is the file that will contain a function that is called by the constructor of your widget, the initDialog() method. The file itself shouldn't be changed as it will contain the generated code from the dialog editor to create the widget on the screen. If you ever have to change values, you should do this by the constructor or be sure that you won't change the dialog during the development process, as the Data file will be overwritten each time the code is generated for your widget. The header and C++ file contain sections, where the dialog editor writes; these are marked by comments. After file generation, you can change any values and settings outside these sections; otherwise your changes will get lost by the next code-creation.

#### Location

For generating the widget's sources, the dialog editor needs to know the location where these will go. The default value for the output directory is the current project subdirectory containing the sources already present.

After pressing "OK", your default values are generated and an empty Widget constructor is opened. Then you are ready to go for creating your own widget. Mind that the dialog editor currently only supports static widgets without geometry management. If you're about to use geometry management for your widgets, you should make yourself accustomed with the classes that Qt provides for this, create a new class with the classgenerator and write your widget by hand. For more information, see The KDevelop Programming Handbook.

### 11.3 Adding Widgets

After specifying the dialogs or widgets class and filenames, you are ready to start creating the widget and filling it with contents. Adding low-level widgets to your dialog is a very easy task. Just select the widget you want to add from the "Widgets" tabulator on the left by a single click over the according widget icon. The widget will then be laid on the left upper corner of the currently opened main widget. An added widget then gets the default size of 100x30 pixels on the editor view. To move a widget, click over it to activate the drawing frame, which is displayed in dark grey with hot spots on the corners and on the center of the top, bottom, left and right sides of the widget. A cross-cursor indicates that the widget can be moved. To move it, press the left mouse button and keep it pressed. then move the widget with your mouse to the place you want to have it displayed later.

To resize a widget, move your mouse cursor over one of the hot spots of the already activated item. The mouse cursor then changes to a double-arrow indicating the directions, in which resizing can be done. Press the left mouse button and hold it pressed. The widget item will change it's size when the mouse is moved to the direction indicated by the cursor.

Further, the widget editor contains a lot of context menus to help you coordinate your work. Those are available over all items in the widgets tabulator and give you a quick help message window that shows the class name of the selected widget with a short description. Over a selected widget, the context menu shows the class name of the selected item and offers:

- Raise
- Lower
- Raise to top
- Lower to bottom
- Cut
- Delete
- Copy
- Paste
- Help

After setting the size and position, you can edit the preferences for the selected item on the Preferences window.

#### The Widgets Tabulator

The widgets tab represents the available widgets you can place on the dialog. If you want information about a certain widget, press the right mouse button over a widget icon and select "Quick-Help" from the popup-menu. Mind that the dialog editor automatically determines, if your project type is Qt-only or KDE. This prevents you from using KDE-widgets in a Qt application.

After you selected a widget item, it is placed with default sizes and values on the editing window and marked selected by a frame and darkened corners. To resize a widget, move your mouse over one of the dark spots and your cursor will change to display which resizing directions are possible. Then press the mousebutton and move the mouse while holding it. When you're finished with resizing the widget, release the mouse. While resizing, the statusbar displays the current position of the item by X and Y values and the current size by W(Width) and H(Height) values.

#### The Dialogs Tabulator

The dialogs tabulator is intended to let you open your project's dialogs by a mouseclick. As the dialog's structure is saved in a *.kdevdlg file within the directory that contains the generated files, only those dialog definition files are shown. Also mind that you don't delete these definition files.

On selecting a dialog, it will be shown as by the state it was saved in the last editing step in the Widget-Editor view.

#### The Items Tabulator

The Items tabulator lets you have an overview over the currently present widget items of the dialog hierarchically. This means, that, as your background represents the parent of all widgets within the dialog, it is shown on top of the tree. The children of the main dialog are then listed in the next tree-level.

On selecting an item, it gets marked in the editor view, as well as the properties are shown in the properties window. Using the items view is sometimes important if your widgets behavior depends on the parent-child relationship.

### 11.4 The Widget Editor

The Widget Editor is the main view that is placed in the middle and where you are constructing your widget. After adding items, those can be selected and resized, as well as moved to the place you need them. Over all items, popup menus provide a quick access to functions like cut, copy and insert.

### 11.5 Setting Properties

The properties window on the right is the place where you set the default behavior for the widget and its items. It displays the pre-set values for each selected item right away; changing values will result in direct changes on the Widget Editor view, e.g. naming labels or buttons.

To separate certain property values by their effect, the properties window contains four folders; selecting a folder will pop up all values for the properties group. All possible values are described below. Mind that the properties are dependent on the widget, e.g. a label and button will have a property for their on-screen name, while lineedits will have properties for methods like setText().

For a complete list of the available values per item, you should see the class-reference of the widget which explains the used methods and all possible values. Note that most values are implemented in `QWidget` and are used for all widgets that inherit QWidget. Also mind that the final code does not contain any method calls that are unchanged by the user and therefore use the default values as given in the widget's constructors.

A complete list of the supported properties that can be set in the properties window for each widget item.

### 11.6 Generating Files

After creating a widget, you have to generate the sourcecode to make it available in your project. This can be done either with the "Generate Sources" from the "Build"-menu or by the according icon in the dialog editor toolbar. Your Makefiles will be updated automatically to include the new widget in the compiling process; therefore, after calling "Generate Sources", you can build your project again within the dialog editor. The output window pops up below the Widget-Editor window as in Project Editor mode.

Now that your project contains a new widget, your work as a programmer is to implement functionality to the used slots and eventually add other methods you may need.

> See The KDevelop Programming Handbook, The Dialogeditor for more information about widget properties and sourcecode generation.

Next Previous Table of Contents