\chapter Customizing and Integrating Qt Designer

\section1 Customizing Qt Designer

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

\QD'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 \QD's dock areas.

General preferences can be set by clicking
\Menu Edit|Preferences to invoke the \Dialog Preferences
dialog. If you check the 'Restore Last Workspace on Startup' checkbox
then \QD will remember the sizes and positions of the toolbars and the
dockable windows. You can change \QD'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.

\index Plugins
\index Code Editing!Preferences
\index Preferences!Code Editing
The \Dialog 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 \QD'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.

\section2 Qt Designer's Code Editor

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

\index Keypresses (Qt Designer's code editor)
The code editor provides the following keystrokes:
\list
\i

Left Arrow -- Moves the cursor one character left
\i

Right Arrow -- Moves the cursor one character right
\i

Up Arrow -- Moves the cursor one line up
\i

Down Arrow -- Moves the cursor one line down
\i

Page Up -- Moves the cursor one page up
\i

Page Down -- Moves the cursor one page down
\i

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

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

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

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

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

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

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

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

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

Ctrl+F -- Invokes the \Dialog {Find Text} dialog
\i

Ctrl+G -- Invokes the \Dialog {Goto Line} dialog
\i

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

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

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

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

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

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

Ctrl+R -- Invokes the \Dialog {Replace Text} dialog
\i

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

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

Ctrl+Y -- Redoes the last operation
\i

Ctrl+Z -- Undoes the last operation
\i

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

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

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

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

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

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

Tab -- Completion (see below)
\endlist

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

Pressing \Key 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
\Key Return to move to the next match and press
\Key Esc to cancel the search at the position you've
reached.

Pressing \Key Tab after you've typed one or more characters
invokes completion. Completion works like this:
start typing some text then press \Key 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 \Key Return, or press
\Key Esc to continue typing. You can switch off completion
in the \Dialog Preferences dialog.

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

\section1 Creating and Using Templates

\index Creating Templates
\index Templates!Creating and Using
\QD supports two approaches to creating template forms. The simplest
approach involves little more than saving a \index .ui
\File .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.

\section2 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.
\list 1
\i

Click \Menu File|New to invoke the \Dialog {New File} dialog.
Click the Dialog template then click \OK.

\i

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

\i

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

\i

Click the \Toolbutton Save toolbar button. In the \Dialog {Save As}
dialog, navigate to \QD's templates directory, e.g.
(\File qt/tools/designer/templates.
Type in the name 'Simple_Dialog.ui' and click
\Button Save.

\i

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

\endlist

Now that we have the simple template we are ready to use it. Click
\Menu File|New to invoke the \Dialog {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.

\section2 Base-class Templates

\index Templates!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
\Class 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 \QD template. The source for the class is in
\File 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 \QD's custom widgets.
Click \Menu {Tools|Custom|Edit Custom Widgets} to
invoke the \Dialog {Edit Custom Widgets} dialog. (This dialog is explained in more
detail in \l {Simple Custom Widgets}.)
Click \Button {New Widget}. Change the Class from
'MyCustomWidget' to 'SizeAware'. Click the Headerfile ellipsis button
and select the file
\File qt/tools/designer/examples/sizeaware/sizeaware.h. Check
the Container Widget checkbox. This
class provides two properties. Click the Properties tab. Click
\Button {New Property} and change the property name to
'company'. Click the \Button {New Property} again and change
the property name to 'settingsFile'. Click \Button Close.

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

A new template, 'SizeAware' is now available from the list of templates.
Click \Menu 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.)

\section1 Integrating Qt Designer with Visual Studio

\QD can be integrated into Visual Studio using the
\index qmsdev.dsp
\File qmsdev.dsp file that is supplied with Qt.

\index Visual Studio
Start up Visual Studio and click \Menu {File|Open
Workspace}. Open
\File %QTDIR%\\tools\\designer\\integration\\qmsdev\\qmsdev.dsp.
Click \Menu {Build|Set Active Configuration} and in
the list click 'QMsDev - Win32 Release', then click \OK. Now click
\Menu {Build|Build qmsdev.dll}. You should now copy
the file
\File %QTDIR%\\tools\\designer\\integration\\qmsdev\\Release\\qmsdev.dll
into
\File {Microsoft Visual Studio\Common\MSDev98\AddIns}.
Now click \Menu Tools|Customize. Click the Add-in Macro Files
tab, then click the \Button Browse button. Change the
file type to 'Add-ins (.dll)' and navigate to
\File {Microsoft Visual Studio\Common\MSDev98\AddIns}.
Click the 
\index qmsdev.dll
\File qmsdev.dll file, click
\Button Open, then click \Button Close.

A new toolbar will appear in Visual Studio with the following toolbar
buttons:
\list
\i

New Qt Project -- A small application wizard
\i

Generate Qt Project -- Runs \Cmd qmake (or the functionally equivalent \Cmd {tmake}) with a \index .pro
\File .pro file
\i

New Qt Dialog -- Add an empty Qt Dialog to the active project
\i

Qt GUI Designer -- Run \QD
\i

Use Qt -- Add the Qt libraries to the active project
\i

Add MOC -- Add the \Cmd moc precompiler to the active file
\i

Add UIC -- Add the \Cmd uic precompiler to the active file\endlist
Double clicking a \index .ui
\File .ui file in the workspace
overview will now launch \QD.

\index Macros!Q_OBJECT
\index Q_OBJECT
If you create a \index .cpp
\File .cpp file which contains the
\c {Q_OBJECT} macro you will need an additional file which
is generated by the \Cmd moc to be included in your project. For
example, if you have 'file.cpp', then the last line would be
\c {#include "file.moc"} and the additional file would be
called 'file.moc'. To ensure that Visual Studio executes the \Cmd moc
and generates this file you must create a custom dependency.
Double click the \index .cpp
\File .cpp file (in your project
workspace) that contains the \c {Q_OBJECT} macro. Click
the \Button {Add MOC} toolbar button; this will create an
empty \index .moc
\File .moc file in your project workspace. Right
click the newly created \index .moc
\File .moc file, then click
\Menu Settings from the pop-up menu to invoke the
Project Settings dialog. Click the Custom Build tab. Click the
\Button Dependencies button to pop up the User Defined
Dependencies dialog. Type in
\c {$(InputDir)\$(InputPath)}, then press
\Key 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 \index qmsdev.dll
\File qmsdev.dll file from the add-ins directory.

\section2 Creating Makefiles without qmake

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

\index Macros!Q_OBJECT
\index Q_OBJECT
\QD produces \index .ui
\File .ui files which are used to generate
\index .h
\File .h and \index .cpp
\File .cpp files for the
compiler to compile. The \index .ui
\File .ui files are processed by
\Cmd uic. Classes which inherit from \Class QObject,
e.g. those which use slots and signals, require an additional
\index .cpp
\File .cpp file to be generated. These files are
generated by the \Cmd moc and are named
'\e {moc_}file.cpp' where the original
\index .cpp
\File .cpp file is called 'file.cpp'. If your
\index .cpp
\File .cpp file contains the \c {Q_OBJECT}
macro an additional file 'file.moc' should be generated which must be
\c {#include}d in the \index .cpp
\File .cpp, normally
at the end. This requires an extra
dependency being created.

Processing \index .ui
\File .ui files with \Cmd uic is done
\e twice:
\code
uic myform.ui -o myform.h
uic myform.ui -i myform.h -o myform.cpp
\endcode

The first execution creates the header file, the second creates the
\index .cpp
\File .cpp file. If you wish to subclass a form you can
use \Cmd uic to generate subclass skeletons:
\code
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 formbase.h formbase.ui -o form.cpp
\endcode

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 \Cmd 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.

For implementation files that contain classes which inherit from
\Class QObject we must create moc files:
\code
moc myform.h -o moc_myform.cpp
\endcode

We'll look at a simple Makefile to see the dependencies in practice.
\code
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
\endcode

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

In Unix/Linux environments the \Cmd make command may be able to
do more for us, so we should be able to use a simpler Makefile like
this:
\code
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
\endcode

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

\section1 Importing Foreign File Formats

\index Foreign File Formats
To import a file in a supported foreign file format click
\Menu File|Open, then click the File Type combobox to choose the file
type you wish to load. Click the required file and \QD will convert and
load the file.

The filters that \QD uses to read foreign file formats are 'works in
progress'. You may have different filters available in your version of
\QD 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.

\section2 Importing Qt Architect Files

\index Foreign File Formats!Qt Architect
\index Qt Architect
\link http://qtarch.sourceforge.net/ Qt Architect \endlink
is a free GUI builder for Qt written by Jeff Harris and Klaus Ebner. The
\index .dlg
\File .dlg extension is associated with Qt Architect dialog files.

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

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

There are a few drawbacks to converting Qt Architect files to \QD's
format due to differences between the two tools; these are listed below:
\list
    \i

    Layout spacing and margins

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

    \i

    Layout stretches and spacings

    Qt Architect gives access to more features of Qt's layout
    system than \QD, namely stretches and spacings. Qt
    Designer will attempt to cope with \index .dlg
\File .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.

    \i

    Mixing managed and unmanaged widgets

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

    \i

    Pixmaps

    \QD ignores pixmaps specified in \index .dlg
\File .dlg files. These
    have to be restored manually in \QD.

\endlist

\section2 Importing Glade Files

\index Foreign File Formats!Glade
\index Glade
\link http://glade.pn.org/ Glade \endlink is a free GUI builder for
GTK+ and GNOME written by Damon Chaplin. The \index .glade
\File .glade extension is
associated with Glade files.

\QD 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 Qt, the layout system and the widget
set of GTK+ are similar to those of Qt, so the filter will retain
most of the information in the \index .glade
\File .glade file.

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

    Ampersands (\&) in labels

    Qt displays an ampersand when a \Class QLabel has no buddy.
    (A buddy is a widget that accepts focus on behalf of a \Class QLabel.)
    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, Qt displays the ampersand itself instead of
    underlining the accelerator key. You should go over these \Class QLabel
    widgets and set their "\Property {buddy}" property.

    \i

    Layout placeholders

    GTK allows a layout position to be occupied by a placeholder. \QD
    converts those placeholders into \Class {QLabel}s whose text is "?"
    in red, so that you can find them and fix them manually.

    \i

    GTK+ or GNOME widget with no Qt equivalent

    Qt has equivalents for most GTK+ widgets, but Glade also
    supports GNOME, whose goal is to provide a complete desktop
    environment. Because Qt's scope is narrower, when \QD
    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 \Class QLabel 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 \Class QWizard class
    cannot.

    \i

    Message boxes and other high-level dialogs

    Glade supports editing of GnomeMessageBox, GtkFileSelection,
    GtkFontSelectionDialog and others. This is trivially achieved in
    Qt by means of a \Class QMessageBox dialog, a \Class QFileDialog, a
    \Class QFontDialog, etc., in C++ code.

    \i

    Stand-alone popup menus

    \QD only supports popup menus inside a \Class QMainWindow. If you
    need a stand-alone popup menu (presumably a context menu),
    you can easily write code that does this using \Class QPopupMenu.

    \i

    Size policy parameters

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

    \i

    GNOME standard icons

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

    \i

    Packer layout

    GTK+ provides a class called GtkPacker that provides for exotic
    layouts; Qt provides no \Class QPackerLayout and never will. \QD
    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.

    \i

    Incorrectly-justified text after conversion

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

    \endlist
