Development/Tutorials/Using Qt Designer: Difference between revisions

    From KDE TechBase
    m (Fix syntax highlighting.)
    (Replaced content with link to Community WIki.)
     
    (4 intermediate revisions by 3 users not shown)
    Line 1: Line 1:
    {{Template:I18n/Language Navigation Bar|Development/Tutorials/Using Qt Designer}}
    {{Note|This is now located at https://community.kde.org/Get_Involved/development/Tutorials/Using_Qt_Designer}}
     
    == Qt Designer User Interfaces in KDE ==
     
    In this tutorial, we will explore how to programatically insert user interfaces
    (UIs) created with Qt Designer, into your KDE project. 
     
    == Designing the UI ==
     
    Qt Designer is a graphical program which allows you to easily build user interfaces, using a ''drag n drop'' interface. Here is a short example how it can go, for more information read the [http://qt.nokia.com/doc/designer-manual.html user documentation].
     
    ;Step 0:
    Call Qt Designer
    <pre>
    designer
    </pre>
    ;Note:
    You can also use Qt Designer from within the [http://labs.trolltech.com/page/Projects/Tools/QtCreator QtCreator] [http://en.wikipedia.org/wiki/Integrated_development_environment IDE] [[Getting_Started/Set_up_KDE_4_for_development#QtCreator|(here is how)]].
    ;Step 1:
    Add the widgets you want by drag-and-drop
     
    [[File:Designer-step1.png|200px]]
    ;Step 2:
    Select the mainwindow. This is the one un-intuitive step. To lay out the objects in the mainwindow, you do not select the objects in the mainwindow, but the mainwindow itself.
     
    [[File:Designer-step2.png|200px]]
    ;Step 3:
    Select Form -> Lay Out in a <u>G</u>rid
     
    [[File:Designer-step3.png|200px]]
    ;Result:
    You get a decent look, and if you resize the window, the widgets resize as well.
     
    [[File:Designer-result.png|200px]]
     
    === Adding a toolbar ===
    To add a toolbar, right-click on the UI and choose "Add Toolbar". Then you can set icons and text in your mainwindow's constructor with code like this:
    ui->toolBar->addAction(QIcon("/usr/share/icons/oxygen/22x22/apps/ktip.png"),"hello world");
     
    == Adding the UI File to Your KDE Project ==
     
    For our purposes, the most important part of using Designer is the
    <tt>*.ui</tt> file that it creates.  This is simply an XML file that
    encodes the user interface in a machine-readable (and human-readable!) way.
     
    Let's imagine that you've created a UI named "MyDialog" with Designer, and
    saved it as the file <tt>mydialog.ui</tt>.  To add this UI to your KDE
    project, simply add a command like the following to your CMakeLists.txt file:
     
    <pre>
    kde4_add_ui_files(myapp_SRCS mydialog.ui)
    </pre>
     
    Replace "<tt>myapp_SRCS</tt>" with the name of the main block in
    your CMakeLists.txt file, defining all of the source code files.  It is usually the
    name of your application, with "<tt>_SRCS</tt>" appended.
     
    When you do this, the build system will run the Qt program <tt>uic</tt>
    on <tt>mydialog.ui</tt>, to auto-generate a C++ header file that
    defines the UI.  The generated file will be named <tt>ui_mydialog.h</tt>.
     
    == Using the UI in Your Code ==
     
    The <tt>ui_mydialog.h</tt> file defines a class named
    "<tt>Ui_MyDialog</tt>", that contains all of the widgets you created in
    Designer as public members of the class.  It also contains the public function
    "<tt>setupUi(QWidget *parent)</tt>", which instantiates all of the widgets,
    sets up their properties, and inserts them into layout managers, all according
    to what you specified in Designer.
     
    Note that <tt>setupUi()</tt> takes a <tt>QWidget*</tt>
    argument.  This argument represents the parent container widget, into which
    all of the widgets in your UI will be inserted.  In other words,
    '''<tt>Ui_MyDialog</tt> is not itself derived from QWidget''', and
    '''it does not contain a toplevel widget itself'''.  You have to supply the toplevel widget
    when you call <tt>setupUi()</tt>.  This is an important point.
     
    One more important semantic detail:  the <tt>Ui_MyDialog</tt> class
    also creates a <tt>Ui</tt> namespace, which simply creates an alias
    for the class.  So you can use <tt>Ui::MyDialog</tt> to refer to the
    same class.
     
    Now, on to actually using the generated UI in your code. The Qt documentation
    shows three ways of [http://qt.nokia.com/doc/latest/designer-using-a-ui-file.html how to use ui-files];
    here only the ''direct approach'' is discussed. The goal is to create a KDialog
    which embeds the UI from the ui-file. First, we have to subclass MyDialog from
    KDialog and add a member variable of type Ui::MyDialog. The header file of
    "<tt>mydialog.h</tt>" looks like the following:
     
    <syntaxhighlight lang="cpp-qt">
    #ifndef MYDIALOG_H
    #define MYDIALOG_H
     
    #include <KDialog>
     
    // include the automatically generated header file for the ui-file
    #include "ui_mydialog.h"
     
    class MyDialog : public KDialog
    {
        Q_OBJECT
        public:
            MyDialog( QWidget *parent=0 );
            ~MyDialog();
     
        private slots:
            void slotButtonClicked();
     
        private:
            // accessor to the ui. we can access all gui elements
            // specified in Designer. If mydialog.ui contains a
            // button "myButton", we will be able to access it
            // with ui.myButton in the cpp file.
            Ui::MyDialog ui;
    };
     
    #endif
    </syntaxhighlight>
     
    Now we are going to look at the implementation of MyDialog, which is in the file
    "<tt>mydialog.cpp</tt>".
     
    <syntaxhighlight lang="cpp-qt">
    #include <KLocale>
    #include <KMessageBox>
     
    // include the header file of the dialog
    #include "mydialog.h"
     
    MyDialog::MyDialog( QWidget *parent )
    : KDialog( parent )
    {
        QWidget *widget = new QWidget( this );
     
        // create the user interface, the parent widget is "widget"
        ui.setupUi(widget); // this is the important part
     
        // set the widget with all its gui elements as the dialog's
        // main widget
        setMainWidget( widget );
     
        // other KDialog options
        setCaption( i18n("This is my Dialog window!") );
        setButtons( KDialog::Close );
     
        // Example Signal/Slot connection using widgets in your UI.
        // Note that you have to prepend "ui." when referring
        // to your UI elements.
        connect( ui.myButton, SIGNAL( clicked() ),
                this, SLOT( slotButtonClicked() ) );
    }
     
    MyDialog::~MyDialog()
    {
    }
     
    void MyDialog::slotButtonClicked()
    {
        KMessageBox::information( this,
                                  i18n("You pressed the button!" ),
                                  i18n( "Hooray!" ) );
    }
     
    #include "mydialog.moc"
    </syntaxhighlight>
     
    So, basically, we create a new Ui::MyDialog and then call
    <tt>ui.setupUi(widget)</tt> in the constructor of <tt>MyDialog</tt>. This
    places the UI elements into the given widget. Then we set the parent-widget
    as the KDialog's main widget. We can then interact with all of the UI elements
    by prepending "<tt>ui.</tt>" to their names, just like it is often done
    with the prefix "<tt>m_</tt>".
     
    == Final Thoughts ==
     
    The cascade of files and classes in this tutorial may seem daunting at
    first, but the naming scheme layed out here has one nice intuitive
    feature: the source code files that you will be editing directly (either as
    text or with Designer) are all named with the same scheme:
    * '''mydialog.ui''': the user interface, created with Designer
    * '''ui_mydialog.h''': auto-generated by uic, Qt's user interface compiler
    * '''mydialog.h/cpp''': the dialog implementation
    The steps in short are
    # create <tt>mydialog.ui</tt>
    # create <tt>mydialog.h/cpp</tt>
    # add variable Ui::MyDialog ui; in <tt>mydialog.h</tt>
    # call <tt>ui.setupUi(widget);</tt>
    # access the ui elements with <tt>ui.</tt>
     
    == Qt Documentation ==
     
    The Qt documentation contains a good article about
    [http://qt.nokia.com/doc/latest/designer-using-a-ui-file.html Using a Designer .ui File in Your Application].
    [[Category:C++]]
    [[Category:KDE4]]

    Latest revision as of 12:48, 16 May 2019