Important: Please read the Qt Code of Conduct -

How to use MainWindow centralWidget & Layout

  • I prefer to do my development in source. I've read many articles and watched many tutorials, but I still don't completely understand MainWindow's built-in centralWidget & layout, and how to use them.

    What I end up doing is creating my own QWidget mainWidget and mainLayout.

    Is this the correct way, or should I utilize the built-in objects? How do I properly use them?

    Below is an example of how I typically setup my apps:


    #ifndef MAINWINDOW_H
    #define MAINWINDOW_H
    #include <QMainWindow>
    #include <QPushButton>
    #include <QVBoxLayout>
    #include <QWidget>
    #include <QDebug>
    class MainWindow : public QMainWindow
        explicit MainWindow(QWidget *parent = nullptr);
        void setup();
        QPushButton *button;
        QVBoxLayout *mainLayout;
        QWidget *mainWidget;
    #endif // MAINWINDOW_H


    #include "mainwindow.h"
    #include "ui_mainwindow.h"
    MainWindow::MainWindow(QWidget *parent) :
    void MainWindow::setup(){
        button = new QPushButton();
        button->setText("Press Me");
        mainLayout = new QVBoxLayout();
        mainWidget = new QWidget();


    #include "mainwindow.h"
    #include <QApplication>
    int main(int argc, char *argv[])
        QApplication a(argc, argv);
        MainWindow w;
        return a.exec();

  • mainWidget->show();

    Wrong, this is the central wiget of the MainWindow:


    and show the mainWindow instead in main:

    MainWindow w;;

    And all should be good :)

  • Lifetime Qt Champion

    Just as a note.
    The default CentralWidget() for a default GUI app (with UI file) is simply just a plain QWidget.
    So there is no special trick or special feature with it.
    Using setCentralWidget(mainWidget); simply sets it and
    there is nothing more to consider.

  • @mpergand & @mrjj ,

    So it isn't wrong to create and use my own widget as the main widget? It just seems to me that since Qt has a built in centralWidget that I should utilize it instead of recreating the wheel with another widget.

  • By default the centralWidget contains nothing ( centralWidget() return null ), hence if you create your UI by code, you must set the centralWidget with your own widget.

    If you build your UI with the Designer, the central widget is created automaticaly when the Ui is build ( ui->setupUi(this) )

    Extract from some code of mine:


    QWidget(0x7faf58dac750, name="centralWidget")

  • @mpergand

    Ah, I understand.

    centralWidget is blank, and Qt sort of expects you to use the Designer, which will automatically modify when you start dragging and dropping elements onto it.

    So in source I simply use setCentralWidget(centralWidget), and add elements and layouts to design the UI. That makes sense.

    So then, if I set and populate centralWidget with all of the elements the UI will need, do I even need to create another "main widget"? Or are you saying that I do need to create another main/central widget, because centralWidget doesn't even have a widget to add other elements to?

  • @Burke212
    Given that you are not using the designer, create your own QWidget *mainWidget and at some point call setCentralWidget(mainWidget). You can add your widgets onto your mainWidget before or after setting it as your central widget, I don't think it matters.

    So just one "main widget", which you create, and then you set the main window to have that as its central widget.

Log in to reply