In this post we’ll look at the 3 main technical options Qt Designer employs to serve this function:

• Aggregation as a pointer member
• Aggregation
• Multiple Inheritance

We’ll also see examples of each method in practice. By the end of this post we should have a good grasp on the various ways we can use Qt Designer to create and integrate designer forms into a larger application.

When considering which method to use it’s important to understand why multiple methods exist in the first place.

The first part of our answer is to understand that when we design an application, our user interface will at some point need to interact with our underlying program logic and/or data structures. Thus, while we can create a new form for our application using the visual editor, it’s up to us to make a programmatic connection so these elements actually do something meaning ful in the context if the larger application.

In short then, how do we get say, a dialog box to write values to a main window? That is, how does one window (designer form) talk to another?

The three methods mentioned above are an abstract answer to this question.

So let’s open Qt Creator and create a basic, empty Qt GUI Application. For our purposes we’ll leave the default names the same, which means we should have a few basic files in our project:

main.cpp

mainwindow.cpp

mainwindow.h

mainwindow.ui

formsdemo.pro

At least in Qt Creator 2.0, the first window that should be open when we leave the create project wizard is the integrated Qt Designer tool. We can close that for now, as our focus is the code files Qt Creator has created for us.

Specifically, mainwindow.cpp and its definition file, mainwindow.h.

The contents of these files will differ based on a setting you may not have seen before:

Qt Preferences > Designer > Embedding of the UI Class

Notice the three options:

• Aggregation as a pointer member
• Aggregation
• Multiple Inheritance

The default on a fresh install should the first: Aggregation as a pointer member. If it’s not, then set it as such and recreate the project (delete the one you just created and start over).

The reason why is with this setting Qt Creator designates the mainwindow.cpp and mainwindow.h files to utilize a private pointer to our Ui::MainWindow object, which is in turn defined in mainwindow.h, which itself part of the Ui:: namespace, of which Ui_MainWindow is a subclass of MainWindow, our main window widget.

It’s a mouthful, and may not the easiest to understand strait away. The end result is that in mainwindow.cpp, so long as we include:

…our Ui objects defined in ui_mainwindow.h should all be accessible (exposed) via our private ui-> pointer in mainwindow.cpp.

Sure enough, our MainWindow constructor contains a call to setupUi() using this pointer:

Again, this is somewhat of a mouthful and is not always the easiest to understand. This technique gets at the heart of some of C++’s more advanced Object Oriented features, many of which could be completely foreign to you. Complexities aside, the end result is with this logic any time we need to access a Ui element in our MainWindow class, we simply use the ui-> pointer.

This is an incredibly important point, as it sets us up for understanding how to add and integrate our own designer forms. In other words, when faced with the task of linking a Ui_ definition file (ui_mainwindow.h) to the mainwindow.h and .cpp files, this is what the designers of Qt have decided to do…it’s a pretty good idea to follow this lead!

Creating A New Designer Form

To see why, right click on your projects name in the Protect Panel (the listing with all the project files, left and side), and from the context menu, click Add New…

Depending on your platform and version, you need to locate the Qt Designer From Class template.

Choose Dialog without Buttons and click continue.

Now set the Class name MyDialog.

This will update the other fields in the wizard such that your header and source files will be mydialog.cpp and mydialog.h respectively.

Again, the first window that will open is the Qt Designer editor. Go ahead and add a single lineEdit item to the dialog and save and close the Qt Designer editor.

Let’s assume this dialog box needs to communicate with the MainWindow form. How do we do that?

We have two main options: Signals and Slots, and Direct Exposure.

Signals and Slots

This is perhaps the most ‘pure’ method, as is means we do not have to force direct connections between widgets. We simply set up a signal from MyDialog and create a slot in MainWindow to process any signals it receives. The only down-side to this method is it creates more coding work, and can be harder to maintain. The upshot is as we’re using signals and slots, we have a greater ability to compose multiple objects together and only listen to the elements we choose. In short, the dialog and caller remain disconnected for the most part.

Direct Exposure

Direct Exposure means we manipulate the mydialog.h file to gain direct access to its ui members from the calling class, in this case MainWindow. The manipulation is a bit of a force though, as our change is making the ui-> member pointer public instead of the default private.

I addition to the privilege change, we must also include both mydialog.h and ui_mydialog.h in the mainwindow.cpp file.

The upshot to this manipulation and inclusion is our MyDialog ui members are now visible to MainWindow, and can be accessed in a manner similar to:

Again, it’s important to note that in order to get to this point we needed to make a private member public, as well as include two header files in our mainwindow.cpp file. This could be considered a bit of heavy-handed coding, and may not always be what you want. That said, it’s a totally legitimate solution, and is certainly less code-heavy and maintenance prone than the Signals and Slots approach.

What About The Others?

Up until this point we’ve only looked at the first of Qt Creators three options for creating code, Aggregation as a pointer member. The other two are just as important, and in some ways, perhaps a bit more convenient.

Aggregation

First we have aggregation. This is very similar in usage terms to the first, in that we aggregate the ui object into our definition file. However, as it’s not a pointer the syntax is a bit cleaner, and in terms of includes, is a bit easier to keep track of as the ui_.h file (the one created by moc), is included in the .h file of the form implementation, meaning we do not need to include it in the mainwindow.cpp class. However, we still need to make the Ui:: member public instead of private, which means we need to edit the moc generated code. This is fine, but is something you should be aware of when faced with creating many widgets.

The end result however, is that we can now access the ui members from MainWindow:

Notice that as our Ui member was created on the stack as opposed to the heap like the first method, we access the ui elements using the member operator (.)

Multiple Inheritance

This is an interesting approach, as from a pedagogical standpoint many of the Qt learning tools use this method in their examples. In other words, knowing about this method helps us learn Qt.

As the name suggests, in this method we subclass both the Base Class of our Widget as well as the namespaced class, which designates the Ui_ class as a subclass.

This dependency chain thus provides our base class with direct access to our forms Ui elements. As can be seen, this makes for the cleanest, most easy-to-understand code:

However, it should be said this benefit comes with a price. Classes defined in this way or almost certainly less flexible for more complex projects, as now we’ve created a tight bond between ui definition and implementation.

Overall though it’s not a surprise why Qt chooses this method in many example code blocks, it’s the easiest to understand and totally sufficient, at least for smaller projects.

Conclusion

This post is rather heavy on theory, so to aid in its consumption I’ve created a test project which shows off each method. The project is purposely light on comments, as the goal here is to just open it up and stalk through the code, letting your own explorations decipher it.

Please keep in mind that their are no doubt other techniques and strategies/design patterns for adding and integrating Qt Designer forms.

Code Download

Contains a simple project showing the methods discussed in this post.

uimembers

The goal during this step is to make exclusive use of the Qt frameworks built-in functions and methods for handling these tasks, as the end result must be a cross-platform compatible app.

We’re already getting a valid directory entry from part 2, so the first step in this part is to figure out how we iterate and query files from our base folder.

As setup for this task, in the first app (the command line one) we defined a few globals:

We’ll keep that basic structure, but of course implement them as member private variables. It should be noted that in the new version the ‘base’ directory value comes from our Worker constructor with:

In the worker constructor we then:

Same thing as the original version really, though one thing I had to check on is if using / will be a problem for Windows. *Turns out the answer is no.*

With the setup tasks done notice that in the GUI we have two buttons: The first allows us to select the base folder, the second kicks off the Process Images task. Notice how we do this: in cleaner.enc__cppqt our clicked() SIGNAL of the processButton button is assigned to the processAction slot, which in turn, after creating our Worker instance object, calls cleanImages(). And so we’re getting an images directory via the GUI–so far so good!

This brings us to the next big question question: how do we open and iterate over directories?

Iterator Over Directories

As you may recall the first task of our program is to remove all files with a _bw_ in the name from the /images sub-folder. It looks like we have: QDirIterator and QDir to help us perform this duty, with the possibly of others as well. The former seems to be for general access, the latter for iterating–we want to iterate.

Basic QDirIterator Implementation

Pretty strait forward really. Iterator over the directory, making sure to skip the path items.

This takes care of the iteration, now we need to find and remove files that have the _bw_.

In the old code we used:

I should step back to mention the first step was to get the file name. In the first attempt we relied on a struct returned by dirent to store file info for checking, now we have a nice simple fileName() method to call. I’m not going to lie, the Qt way feels much cleaner than the command line version. dirent was tricky to work with at first without having a debugger, this is no longer an issue in Qt. With that out of the way, what of finding the text “_bw_”?

I suspected, and was proven right, that QString would have some type of find function. Sure enough:

Beautiful! I can’t help but show my gratitude over such an elegant and natural thing. Without any documentation look up I was able to basically guess and implement my search function in one line. Yes std::string had the same thing with .find(), but this was a nice treat regardless.

Right, so now how do we delete files?

In the first version we had to use a separate variable (location) and a member function .c_str() to pass to the delete(char*) call. This is fine, but a touch verbose. It would be nice to encapsulate this a bit more.

Delete File Implementation

It turns out that we can use the same remove() call, though it wants a char*, we’ve got a QString. As was the goal anyway, we want to use native solutions for cross-platform consistency. I did some digging and found QFile. QFile has a member function for removing files: .remove(). Even better though, QDirIterator has a member function filePath() to return the full path to the file (not just file name). Of course I may have missed similar functionality in the first go (such as using QDir), but now we save ourselves the hassle of rebuilding the file path from scratch. The final code is:

Sure it’s about the same length as the original command line code, if not a bit longer, but it feels more intuitive–almost like OO PHP coding. I do not however, like the idea of creating a new QFile for each item to remove, but I’m learning–I’m sure we’ll find a better way in the next few posts.

Final Method Implementation

For the sake of completeness, here’s the final cleanImages() function:

Up next, rewriting the cleanXMLStoryFiles() function.

At the end of this post we’ll have a shell ready for the actual porting process to being. In other words, a GUI that loads, reacts to button presses, and updates status text.

So here’s the code:

main.enc__cppqt

cleaner.enc__cppqt

cleaner.h

worker.enc__cppqt

worker.h

The biggest thing to note about this code is that we’re not using the Qt Designer program to create the UI. It’s all hand coded, done for the sake of learning the core UI model. If you’re learning Qt I suggest you try this as well. Yes the Qt Designer tool is fantastic and yes I’ll use it for most tasks moving forward, but for this project we’ll keep it low-level.

Core Implementation

On the implementation level it’s important to note that we’re using a totally object oriented approach to the UI and logic. Speaking of UI and Logic, note how we’ve split the app in two logical components: cleaner.enc__cppqt which holds the presentation logic, worker.enc__cppqt for the ‘model’.

On a releated note, as the XML logic will almost certainly get parallelized we’ll take special note of how we add and handle additional classes and data structures. From what I can see Qt may want all parallel code in separate classes, so we’ll see. We may end up editing the core functionality of worker.enc__cppqt, or possibly add a workerXML.ccp to the mix.

Also note how our call to: QFileDialog::getExistingDirectory() via: void Cleaner::loadAction() in cleaner.enc__cppqt is how we get the file path to process. In short, we’ve already replaced the command line apps argument with a GUI based equivalent!

To that end notice that as of right now we still have implementation bugs. So for example we create pointer to an instance of Worker on the heap in processAction() but do not call delete() on it. Of course this is wrong, and we’ll fix that in time–for now though the main idea is this code creates the UI which reacts to member functions of the worker class.

Next Steps

That’s it for the core UI code, in part 2 we’ll start porting our base application.

Go To Part 3 –>
Link

The application in question is a simple tool for cleaning up the export of a Print Publishing CMS system for eventual use in a Web-based CMS. By simple I mean we open a folder and loop through it, diving into sub-folders as needed to:

1. Remove all images tagged with a _bw_
2. Open XML ‘story’ files and remove extra line breaks from headline elements, and clean up content HTML.

The application started as an Apple Xcode project, and has now moved into NetBeans 6.8 on Linux. In the end I hope to learn a good deal about the Qt framework, as well as proper C++ application development.

How and why are we doing this?

Command line apps are only so useful, so the next natural step was to port it to a GUI. I had not done this before, so it would be an education experience. Perhpas you find yourself in a similar situation, stuck with a command line tool when a nice GUI would be preferred. Of course doing so can be intimidating at first, as in most cases the libraries needed to accomplish this task can be quite daunting.

To that end I we’ll use Qt (read: cute) because it’s open source for non-commercial apps, is incredibly powerful, cross-platform, easy to learn, and well documented.

The Code

So what have we got to work with? I did a fair bit of experimentation during the first pass, what we see here is the sanitized version with most comments and junk taken out. That said, it should work on *NIX based distributions, Windows is iffy, and not tested.

The Current Program

The program is broken into several logical sections: The first part of the program takes the user supplied command line argument of a folder and creates a simple variable: basePath. This path is then used to build the other locations of our sub-folder structure. Here we also define a few text constants used in the XML file cleanup step.

With a valid path, we loop though the images folder and delete any files with a _bw_ in the name. The _bw_ is for Black and White, and is a known quantity in this work-flow.

I should add at this point the folder structure we are traversing looks like:

xmlout

–images/

—-/image_files.jog

–null/

–stories/

—-/story.xml

—-/story.xml

The next step is slightly longer, here we need to clean up XML files. The process really isn’t important for the porting process, as we’ll probably end up with very similar code in the end anyway. The long and short of it though is at several places in the XML output are unclosed <p> tags, extra line breaks and formatting, and other general messiness that cause an XML import of these files to fail when going to the ‘target’ system.

The one thing I do want to pay attention to is the file read process. It’s in this area that we’ll probably find the most diversion from the command line app. In particular, I want to see how Qt makes file reading easier, and also, I want to explore parallelization at this step. I can envision reading in a batch of files, say, 50 at a time, and then spawning new threads to handle the clean up tasks.

Of course we then write the cleaned up files back to the system, something that again, could probably be done in concert with a parallel processing model.

More generally though, with a port I want to explore a more object oriented way of performing these steps, as well as adding more error and sanity checks.

Coming In Part 2

Stay tuned for part 2 where we’ll take a look at the ported code I’ve created thus far. We’ll talk about general Qt development, and what goals I have the project in general.

Code Download

A note of caution: This code has not been tested, and may not work on Windows. Of course this is one area a proper Qt port will help with!

main.cpp
Go To Part 2 –>
Link