Getting Started notepad example is impossible to follow

ZedThree

Apologies if this is the wrong category, and also apologies for the following screed, but I've spent way too long bashing my head against what I thought would be a simple tutorial.

The main "Getting Started Programming" tutorial, here: https://doc.qt.io/qt-5/qtwidgets-tutorials-notepad-example.html, is currently impossible to follow as it just doesn't reflect how anything works. There's a couple of differences between the text and what actually happens in the latest version of QtCreator, but they're minor annoyances. It starts to go very wrong after creating the text edit widget.

In the "Notepad Header File" section, https://doc.qt.io/qt-5/qtwidgets-tutorials-notepad-example.html#notepad-header-file, we've got as far as creating a QMainWindow with a QTextEdit widget, and the tutorial says:

The wizard generated a header file for the Notepad class that has the necessary #includes, a constructor, a destructor, and the Ui object. The file looks as follows:

#include <QMainWindow>

namespace Ui {
class Notepad;
}


class Notepad : public QMainWindow
{
    Q_OBJECT

public:
    explicit Notepad(QWidget *parent = nullptr);
    ~Notepad();

private slots:
    void newDocument();

    void open();

// more slots snipped

private:
    Ui::Notepad *ui;
    QString currentFile;
};

For me, using QtCreator 4.10.2 with Qt 5.13.2, it actually looks like:

#ifndef NOTEPAD_H
#define NOTEPAD_H

#include <QMainWindow>

QT_BEGIN_NAMESPACE
namespace Ui { class Notepad; }
QT_END_NAMESPACE

class Notepad : public QMainWindow
{
    Q_OBJECT

public:
    Notepad(QWidget *parent = nullptr);
    ~Notepad();

private:
    Ui::Notepad *ui;
};
#endif // NOTEPAD_H

Note the complete lack of private slots section. This is very confusing! I spent way too long trying to work out where I'd gone wrong, one step into the tutorial, before I realised this is probably just the completed version.

A similar thing has happened for the description of the source file: https://doc.qt.io/qt-5/qtwidgets-tutorials-notepad-example.html#notepad-source-file
where the completed source is included instead of what it should actually be at this stage.

Again, this is incredibly confusing for a Qt beginner, as there is an instruction:

In order to have the text edit field occupy the whole screen, we add setCentralWidget to the main window.

and because the completed source is included, it's not at all clear what we are supposed to add.

The next step, where we should start doing interesting things just doesn't work at all for me, https://doc.qt.io/qt-5/qtwidgets-tutorials-notepad-example.html#adding-user-interaction

Click on "Type Here", and add the options New, Open, Save, Save as, Print and Exit. This creates 5 lines in the Action Editor below. To connect the actions to slots, right-click an action and select Go to slot > triggered(), and complete the code for that given slot.

This is, at the very least, badly phrased. A single left- or right-click doesn't allow you to do anything like that. Double-clicking on "Type Here" allows you to enter text and create a new QMenu in the QMenuBar, but it doesn't add anything to the Action Editor. I think one needs to click "New" in the Action Editor to add these.

The last sentence is misleading too, "complete the code for that given slot" makes it sound like you should already be able to complete the code, whereas it's actually the goal of the current section.

If we also want to add the actions to a toolbar, we can assign an icon to each QAction, and then drag the QAction to the toolbar. You assign an icon by entering an icon name in the Icon property of the action concerned. When the QAction has been dragged to the toolbar, clicking the icon will launch the associated slot.

After some research on how to add icons, this is way too simplified for an introductory tutorial.

The rest of the tutorial is similarly confusing. I also looked at the Qt For Python version: https://doc.qt.io/qtforpython/overviews/qtwidgets-tutorials-notepad-example.html
This appears to just be a copy of the C++ one, only without the source code.

I eventually found my way to the archives, and the version of this tutorial from 5.8 is much more helpful: https://doc.qt.io/archives/qt-5.8/gettingstartedqt.html#creating-the-notepad-project
It looks like something went wrong updating it to 5.10, which is very similar to the current form. Please could either an earlier version be restored, or the current version fixed so that it actually works?

Again, apologies for the rant, but trying to follow this tutorial was a very frustrating experience! Should I file this as a bug somewhere?

Christian Ehrlicher

Feel free to provide a patch through Qt gerrit.