Introduction and prerequisites

In this post, we will cover the basics of creating a custom Qt widget in Visual Studio, which will display a configurable text and image, and use it in a mini-cookbook application.
Qt offers a lot of standard widgets (button, combo box, label, text edit etc.). But you may often need either to extend their behavior or to write your own, custom-tailored widget. It can be used for a variety of different purposes and can behave differently. In general, a custom widget enables you to extend capabilities of a standard collection of Qt widgets. Also, it helps to avoid breaking DRY principle, when it comes to having similar GUI elements but, for example, with different content, which can be parametrized. We will see an example of such a GUI element later in this post.

Prerequisites: intermidiate C++, intermidiate Qt widgets level.

Installing the Qt Visual Studio Tools plugin

First, get the Qt Visual Studio Tools plugin either from Qt Downloads or from Visual Studio Marketplace or from Visual Studio menu:

Tools -> Extensions And Updates… -> Online -> start typing “Qt” in the search field -> download Qt Visual Studio Tools.

After installing the plugin, restart Visual Studio.

What is a Qt widget

Widgets are the primary elements for creating user interfaces in Qt. Widgets can display data and status information, receive user input, and provide a container for other widgets[Qt widgets documentaion]. Each type of widget is provided by a subclass of QWidget, which is itself a subclass of QObject. if you unfamiliar with Qt widgets, you can read more on official Qt docs.


What we are building

Three recipes using custom Qt widget | Images by Anna Krykora via <a href="" target="blank"> Instagram</a>
Three recipes using custom Qt widget | Images by Anna Krykora via Instagram


We are going to build a Qt window, with three recipes displayed on it.

The bottom line is to have one customizable widget instead of three boilerplate duplicates of the same GUI element. We will populate these widgets directly in code, but a config file or reading data from a database or any other external source is appreciated.


Break it down

First, we create a Qt GUI Application Project in Visual Studio. In Qt GUI Application Wizard we can leave everything with default values.

Create Qt GUI Application Project in Visual Studio
Create Qt GUI Application Project in Visual Studio


As a result, we will get the following project structure:

VS project structure
Created VS Project Structure

In the created project, we already have a main window named “CustomWidgetExample” (which is also a subclass of a Qt widget), where we will place our own widgets.

In the .qrc file, we will store images for our App.

Just like the main window widget, our custom widget will consist of 3 parts: a header, a corresponding .cpp file, and a .ui file. The last one we will edit using Qt Tools plugin GUI editor (Qt Designer), which is very similar to what you get in the Qt Creator IDE. To open it just double-click on the .ui file.

In main.cpp file, you will find the code, which starts and runs a Qt application, as well as creates and shows the main window.


Creating a custom widget is pretty easy. We just derive from a basic QWidget class and already have a base infrastructure and widget’s behavior. We can also derive from any other QWidget subclass, for example, from a QButton, so that we will have all the standard button behavior and properties out of the box. We use GUI to create a skeleton of our custom widget. Right-click on the project -> Add -> Add Qt Class.

Using GUI to create a custom widget
Using GUI to create a custom widget


Select Qt GUI Class and follow the wizard. You may leave all settings at the defaults.

Adding Qt GUI Class
Adding Qt GUI Class


As a result, we will get 3 new files generated: RecipeWidget.h, RecipeWidget.cpp and RecipeWidget.ui. Let’s start with editing .ui file.

In our recipe custom widget, we will add several QLabel elements for recipe title, image and description, and a button. The resulting elements structure will look like this:

Now we will add a method to populate our recipe widget.

Next, we will add three of our custom widgets onto the main window. First, we add three QWidget GUI elements and then promote each of them to our custom RecipeWidget.

Right-click on one of the widgets -> Promote to …

In the appeared dialog window, in Promoted class name filed type our widget name, click Add. If your custom widget derived from other Qt base class (say, QButton), do not forget to select it in a Base class name combobox.

Then select added promoted class and click Promote.

For other two widgets, we will choose Promote to from the context menu to promote them to RecipeWidget:

Then, we will populate them with data in main window constructor:

That’s it. We have created a custom widget, designed it in Qt Designer, put it in other widget and populated it with data.
We can continue developing our custom widget, for example, adding a click handler for a button, or implementing slots and signals.


The End

Complete project source code lives on GitHub.
I hope you have enjoyed this tutorial. Please, leave your comments, questions, and suggestions below. Good luck creating your own custom widgets and thanks for reading!

How to create a custom Qt widget in Visual Studio 17
Tagged on:             

12,226 thoughts on “How to create a custom Qt widget in Visual Studio 17