Home | All Classes | Main Classes | Annotated | Grouped Classes | Functions |

[Prev: Creating Database Applications] [Home] [Next: Reference: Key Bindings]

## Customizing and Integrating TQt Designer

### Customizing TQt Designer

TQt Designer can be customized in two ways: you can add custom widgets, and you can change aspects of how TQt Designer works. Custom widgets are covered in Creating Custom Widgets. This section will focus on customizing TQt Designer itself.

TQt Designer's toolbars are all dockable so they can be dragged by their toolbar handles and arranged how you like. The Files, Object Hierarchy, Property Editor and Output Windows are also dockable so you can also drag them to the positions that you prefer. You can also make them into floating windows by dragging them outside TQt Designer's dock areas.

General preferences can be set by clicking Edit|Preferences to invoke the Preferences dialog. If you check the 'Restore Last Workspace on Startup' checkbox then TQt Designer will remember the sizes and positions of the toolbars and the dockable windows. You can change TQt Designer's main window background either by selecting a color or a pixmap. You can also switch off the grid (uncheck Show Grid) since using layouts makes the grid redundant.

The Preferences dialog may have additional tabs, depending on what plugins you have installed. We'll describe the C++ Editor tab since this is installed by default.

The C++ Editor tab is used to set your preferred fonts for syntax highlighting in TQt Designer's code editor. The base font for all elements is set in the 'Standard' element which is the last item in the list. If you want one font to be used throughout then set the 'Standard' font and all the other elements will inherit its setting.

#### TQt Designer's Code Editor

The code editor is available if an Editor plugin is installed. The C++ Editor plugin is installed by default.

The code editor provides the following keystrokes:

- Left Arrow -- Moves the cursor one character left

- Right Arrow -- Moves the cursor one character right

- Up Arrow -- Moves the cursor one line up

- Down Arrow -- Moves the cursor one line down

- Page Up -- Moves the cursor one page up

- Page Down -- Moves the cursor one page down

- Backspace -- Deletes the character to the left of the cursor

- Home -- Moves the cursor to the beginning of the line

- End -- Moves the cursor to the end of the line

- Delete -- Deletes the character to the right of the cursor

- Ctrl+A -- Moves the cursor to the beginning of the line

- Ctrl+B -- Moves the cursor one character left

- Ctrl+C -- Copies the selected text to the clipboard (also Ctrl+Insert under Windows)

- Ctrl+D -- Deletes the character to the right of the cursor

- Ctrl+E -- Moves the cursor to the end of the line

- Ctrl+F -- Invokes the Find Text dialog

- Ctrl+G -- Invokes the Goto Line dialog

- Ctrl+H -- Deletes the character to the left of the cursor

- Ctrl+I -- Indent the line or selected text that contains the cursor

- Alt+I -- Starts incremental search (see below)

- Ctrl+K -- Deletes from the cursor position to the end of the line

- Ctrl+N -- Moves the cursor one line down

- Ctrl+P -- Moves the cursor one line up

- Ctrl+R -- Invokes the Replace Text dialog

- Ctrl+V -- Pastes the clipboard text into line edit (also Shift+Insert under Windows)

- Ctrl+X -- Cuts the marked text, copy to clipboard (also Shift+Delete under Windows)

- Ctrl+Y -- Redoes the last operation

- Ctrl+Z -- Undoes the last operation

- Ctrl+Left Arrow -- Moves the cursor one word left

- Ctrl+Right Arrow -- Moves the cursor one word right

- Ctrl+Up Arrow -- Moves the cursor one word up

- Ctrl+Down Arrow -- Moves the cursor one word down

- Ctrl+Home Arrow -- Moves the cursor to the beginning of the text

- Ctrl+End Arrow -- Moves the cursor to the end of the text

- Tab -- Completion (see below)

To select (mark) text hold down the Shift key whilst pressing one of the movement keystrokes, for example, Shift+Right Arrow will select the character to the right, and Shift+Ctrl+Right Arrow will select the word to the right, etc.

Pressing Alt+I starts incremental search. The characters you type will appear in the Incremental Search line edit in the Search toolbar and the cursor will be moved to the first matching text in the editor. As you type the search will continue. Press Return to move to the next match and press Esc to cancel the search at the position you've reached.

Pressing Tab after you've typed one or more characters invokes completion. Completion works like this: start typing some text then press Tab. If the editor can find another item of text that begins with the same characters it will complete your text for you; if it finds more than one possibility it will pop up a list of choices. You can use the arrow keys to choose a piece of text then press Return, or press Esc to continue typing. You can switch off completion in the Preferences dialog.

When you enter `->` or `.` the editor will pop up a command completion list; use the arrow keys to move to the item you want and press Return, or press Esc to ignore the list.

### Creating and Using Templates

TQt Designer supports two approaches to creating template forms. The simplest approach involves little more than saving a `.ui` file into the templates directory. The second approach involves creating a container widget class to be used as a base class for forms that use the template. We will explain both techniques.

#### Simple Templates

These templates are most useful when you want to create a whole set of forms which all have some common widgets. For example, you might have a project that will require many forms, all of which need to be branded with a company name and logo.

First we'll create the simple template.

1. Click File|New to invoke the New File dialog. Click the Dialog template then click OK.

2. Click the Text Label toolbar button, then click near the top left of the form. Change the font Point Size property to 16 and change the text property to your or your company's name. Click the Line toolbar button, then click the form below the label; click Horizontal on the pop-up menu.

3. Select the label and the line. (Ctrl+Click the form, then drag the rubber band so that it touches or includes the line and the label.) Press Ctrl+L to lay them out vertically.

4. Click the Save toolbar button. In the Save As dialog, navigate to TQt Designer's templates directory, e.g. (`qt/tools/designer/templates`. Type in the name 'Simple_Dialog.ui' and click Save.

5. Right click the form in the Forms list, then click Remove form from project.

Now that we have the simple template we are ready to use it. Click File|New to invoke the New File dialog. One of the templates that will appear is 'Simple Dialog'. Click the simple dialog, then click OK. A new form will appear with the same widgets and layout as the template. Add any other widgets and functionality. When you attempt to save the form you will be prompted for a new form name.

#### Base-class Templates

These templates are useful when you want to provide some default functionality that all the forms based on the base class can inherit. In our example we'll use a class called SizeAware that remembers and restores its size as the basis of a template. We won't describe the class itself, but will focus instead on making use of it as a TQt Designer template. The source for the class is in `qt/tools/designer/examples/sizeaware`.

The template can either be based on a custom widget or on any existing container widget.

If you want to base the template on a custom widget you must first add it to TQt Designer's custom widgets. Click Tools|Custom|Edit Custom Widgets to invoke the Edit Custom Widgets dialog. (This dialog is explained in more detail in Simple Custom Widgets.) Click New Widget. Change the Class from 'MyCustomWidget' to 'SizeAware'. Click the Headerfile ellipsis button and select the file `qt/tools/designer/examples/sizeaware/sizeaware.h`. Check the Container Widget checkbox. This class provides two properties. Click the Properties tab. Click New Property and change the property name to 'company'. Click the New Property again and change the property name to 'settingsFile'. Click Close.

To create a template, based on an existing widget or on your own custom widget, click File|Create Template to invoke the Create Template dialog. Change the Template Name to 'SizeAware' and click the SizeAware base class, then click Create. The dialog will create the template and close itself immediately. Close TQt Designer and restart it.

A new template, 'SizeAware' is now available from the list of templates. Click File|New, click SizeAware and click OK. Note that the two properties, company and settingsFile, are available in the Properties window. Any forms based on this template will remember their size and resize when reloaded. (In practical applications having one settingsFile per form is not recommended, so this template would only really be useful for applications that have a single main window.)

### Integrating TQt Designer with Visual Studio

By default, TQt Designer is integrated into Visual Studio 6.0 when TQt is installed. Visual Studio.Net does not support this integration.

If installed successfully, a toolbar should be provided in Visual Studio with the following buttons:

- New TQt Project -- A small application wizard

- New TQt Dialog -- Add an empty TQt Dialog to the active project, or add an existing dialog

- TQt GUI Designer -- Run TQt Designer

- Open TQt Project -- Runs `qmake` with a `.pro` file

- Write TQt Project -- Saves the current VS project as a `.pro` file

- Use TQt -- Add the TQt libraries to the active project

- Add MOC -- Add the `moc` precompiler to the active file

Double clicking a `.ui` file in the workspace overview will now launch TQt Designer.

If you create a `.cpp` file which contains the `TQ_OBJECT` macro you will need an additional file which is generated by the `moc` to be included in your project. For example, if you have 'file.cpp', then the last line would be `#include "file.moc"` and the additional file would be called 'file.moc'. To ensure that Visual Studio executes the `moc` and generates this file you must create a custom dependency. Double click the `.cpp` file (in your project workspace) that contains the `TQ_OBJECT` macro. Click the Add MOC toolbar button; this will create an empty `.moc` file in your project workspace. Right click the newly created `.moc` file, then click Settings from the pop-up menu to invoke the Project Settings dialog. Click the Custom Build tab. Click the Dependencies button to pop up the User Defined Dependencies dialog. Type in `$(InputDir)\$(InputPath)`, then press Return. Click OK to leave the Dependencies dialog, then click OK to leave the Project Settings dialog.

If you wish to delete the add-in remove it from the toolbar then delete the `qmsdev.dll` file from the add-ins directory.

#### Creating Makefiles without qmake

The `qmake` tool provided with TQt can create Makefiles appropriate to your platform based on `.pro` project files. This section describes the dependencies involved in building a TQt application and gives a couple of simple example Makefiles. This section assumes that you have a good understanding of Makefiles.

TQt Designer produces `.ui` files which are used to generate `.h` and `.cpp` files for the compiler to compile. The `.ui` files are processed by `uic`. Classes which inherit from TQObject, e.g. those which use slots and signals, require an additional `.cpp` file to be generated. These files are generated by the `moc` and are named 'moc_file.cpp' where the original `.cpp` file is called 'file.cpp'. If your `.cpp` file contains the `TQ_OBJECT` macro an additional file 'file.moc' should be generated which must be `#include`d in the `.cpp`, normally at the end. This requires an extra dependency being created.

Processing `.ui` files with `uic` is done twice:

    uic myform.ui -o myform.h
    uic myform.ui -i myform.h -o myform.cpp

The first execution creates the header file, the second creates the `.cpp` file. If you wish to subclass a form you can use `uic` to generate subclass skeletons:

    uic formbase.ui -o formbase.h
    uic formbase.ui -i formbase.h -o formbase.cpp
    uic -subdecl Form formbase.h formbase.ui -o form.h
    uic -subimpl Form form.h formbase.ui -o form.cpp

First we generate the header and implementation file for our base class. Then we generate the header and implementation skeletons for our subclass. Note that the use of `uic` to generate skeletons is not something that would be done in a Makefile, we mention it here because it can be useful for command line users. Note also that the command line for `-subdecl` and for `-subimpl` are subtly different.

For implementation files that contain classes which inherit from TQObject we must create moc files:

    moc myform.h -o moc_myform.cpp

We'll look at a simple Makefile to see the dependencies in practice.

    myapp: moc_myform.o myform.o main.o
            g++ -lqt -o myapp moc_myform.o myform.o main.o

    main.o: main.cpp
            g++ -o main.o main.cpp

    moc_myform.o: moc_myform.cpp
            g++ -o moc_myform.o moc_myform.cpp

    moc_myform.cpp: myform.h
            moc myform.h -o moc_myform.cpp

    myform.o: myform.cpp
            g++ -o myform.o myform.cpp

    myform.cpp: myform.h myform.ui
            uic myform.ui -i myform.h -o myform.cpp

    myform.h: myform.ui
            uic myform.ui -o myform.h

Note that you may need to include the full path to the commands in your Makefile, and under Windows the filenames are `moc.exe` and `uic.exe`.

In Unix/Linux environments the `make` command may be able to do more for us, so we should be able to use a simpler Makefile like this:

    myapp: moc_myform.o myform.o main.o
            g++ -lq -o $@ $^

    %.o: %.cpp
            g++ -o $^ $@

    moc_%.cpp: %.h
            moc $^ -o $@

    myform.cpp: myform.h myform.ui
            uic myform.ui -i myform.h -o myform.cpp

    myform.h: myform.ui
            uic myform.ui -o myform.h

To see more sophisticated Makefiles simply generate them using `qmake` on any of your TQt projects or any of the examples supplied with TQt.

### Importing Foreign File Formats

To import a file in a supported foreign file format click File|Open, then click the File Type combobox to choose the file type you wish to load. Click the required file and TQt Designer will convert and load the file.

The filters that TQt Designer uses to read foreign file formats are 'works in progress'. You may have different filters available in your version of TQt Designer than those described here. The easiest way to see which filters are available is to invoke the file open dialog; all your filters are listed in the File Type combobox.

#### Importing TQt Architect Files

TQt Architect is a free GUI builder for TQt written by Jeff Harris and Klaus Ebner. The `.dlg` extension is associated with TQt Architect dialog files.

TQt Designer can read files generated by TQt Architect version 2.1 and above. When given a `.dlg` file from a previous version of TQt Architect, TQt Designer tells you how to convert it to the file format of version 2.1. (The conversion procedure varies depending on the version of the `.dlg` file.)

The import filter does a good job of importing `.dlg` files; the result is almost identical to what you get in TQt Architect. However, the C++ code that uses the dialogs will probably need some adaptation.

There are a few drawbacks to converting TQt Architect files to TQt Designer's format due to differences between the two tools; these are listed below:

- Layout spacing and margins

  If the `.dlg` file layouts use the TQt Architect defaults for layout spacing and margins, TQt Designer will override these with its standard defaults. You can change the "layoutSpacing" and "layoutMargin" properties manually afterwards if necessary.

- Layout stretches and spacings

  TQt Architect gives access to more features of TQt's layout system than TQt Designer, namely stretches and spacings. TQt Designer will attempt to cope with `.dlg` files that use these features, but sometimes the resizing will not be what you want. The solution typically involves setting the "sizePolicy" properties of some widgets and inserting or deleting spacers.

- Mixing managed and unmanaged widgets

  TQt Architect allows a widget to have some child widgets managed by a layout and other child widgets with fixed positions. When presented with a `.dlg` file that uses this facility, TQt Designer will silently put the fixed position widgets into the layout.

- Pixmaps

  TQt Designer ignores pixmaps specified in `.dlg` files. These have to be restored manually in TQt Designer.

#### Importing Glade Files

Glade is a free GUI builder for GTK+ and GNOME written by Damon Chaplin. The `.glade` extension is associated with Glade files.

TQt Designer has been tested with Glade files up to version 0.6.0 and might work with later versions as well.

Although Glade does not target TQt, the layout system and the widget set of GTK+ are similar to those of TQt, so the filter will retain most of the information in the `.glade` file.

There are some considerations regarding the conversion of Glade files, as listed below:

- Ampersands (&) in labels

  TQt displays an ampersand when a TQLabel has no buddy. (A buddy is a widget that accepts focus on behalf of a TQLabel.) Glade allows GtkLabel widgets with an (underlined) accelerator key but with no buddy. This is an error since users expect underlined characters to be accelerators. In this situation, TQt displays the ampersand itself instead of underlining the accelerator key. You should go over these TQLabel widgets and set their "buddy" property.

- Layout placeholders

  GTK allows a layout position to be occupied by a placeholder. TQt Designer converts those placeholders into TQLabels whose text is "?" in red, so that you can find them and fix them manually.

- GTK+ or GNOME widget with no TQt equivalent

  TQt has equivalents for most GTK+ widgets, but Glade also supports GNOME, whose goal is to provide a complete desktop environment. Because TQt's scope is narrower, when TQt Designer encounters a widget it cannot convert, it replaces it with a label that indicates the problem. For example, a GnomePaperSelector will be replaced by a TQLabel whose text is "GnomePaperSelector?" in red. If you are porting to KDE, you might want to use the corresponding KDE widget.

  Other GTK+/GNOME widgets are only supported in certain contexts. For example, the GnomeDruid can be embedded in another widget, whereas the corresponding TQWizard class cannot.

- Message boxes and other high-level dialogs

  Glade supports editing of GnomeMessageBox, GtkFileSelection, GtkFontSelectionDialog and others. This is trivially achieved in TQt by means of a TQMessageBox dialog, a TQFileDialog, a TQFontDialog, etc., in C++ code.

- Stand-alone popup menus

  TQt Designer only supports popup menus inside a TQMainWindow. If you need a stand-alone popup menu (presumably a context menu), you can easily write code that does this using TQPopupMenu.

- Size policy parameters

  Glade provides size policies in the "Place" tab of the property editor. TQt Designer does not attempt to make use of the padding, expand, shrink and fill information, as the TQt defaults are usually good enough. In a few cases, you might have to set the "sizePolicy" property manually to obtain the effect you want.

- GNOME standard icons

  GNOME provides a large set of standard icons. TQt Designer will ignore references to these. If you are porting to KDE, you might want to manually set the standard KDE icons.

- Packer layout

  GTK+ provides a class called GtkPacker that provides for exotic layouts; TQt does not provide a TQPackerLayout and none is planned. TQt Designer will treat packer layouts as if they were vertical layouts and you will probably have to change them to whatever combination of layouts that produces the right effect.

- Incorrectly-justified text after conversion

  The "hAlign" property is sometimes set wrongly, in which case you have to change it manually. It is caused by a quirk in Glade.

[Prev: Creating Database Applications] [Home] [Next: Reference: Key Bindings]