Oddities in "Getting Started Programming with Qt"



  • I've just finished a "German version":http://developer.qt.nokia.com/wiki/Einstieg_in_die_Programmierung_mit_Qt of the "Getting Started Programming with Qt":http://doc.qt.nokia.com/4.7/gettingstartedqt.html guide and came over some oddities during translation:

    Download of code samples
    For the readers of the guide it surely would be handy if they could download the complete examples in a zip file.

    Missing references
    In the end of the "Hello Notepad":http://doc.qt.nokia.com/4.7/gettingstartedqt.html#hello-notepad section directories part1 resp. part1/debug and part1/release are mentioned. These directories have not been introduced before. Additionally, on windows the path would be part1\debug - with a backslash :-)

    Signal/slot connection
    In section "Subclassing QWidget":http://doc.qt.nokia.com/4.7/gettingstartedqt.html#subclassing-qwidget we read:

    bq. The quit() slot can now be connected to signals with a matching signature (any signal that takes no parameters)

    That's not the whole truth, we can connect any signal with parameters to slots with parameters that are a (probably empty!) prefix of the signals signature. So we can connect any signal to a slot with an empty parameter list!

    Implementation of slots open() and close()
    The code sections should display the complete functions, including function signature, not only the body. E.g. like this:

    @
    void Notepad::open()
    {
    // function body
    }
    @

    Line numbering in code sections
    Some of the code blocks do have line numbers, some do not. That's inconsistent.

    QFileDialog:: getOpenFileName()
    The function not only does return when the user has selected a file name, but also when he hit the abort button :-)

    Different level of verbosity in the explanations
    In the beginning the verbosity level is quite high, including the explanation of #include statements. Further on this verbosity is not the same. I can understand that it's quite cumbersome to hold that until the very end, but it introduces a strange style of writing. It reads as if different people had written the particular sections.

    Wrong code in slots save() and open()
    In slot open we operate on a raw QFile, using its readAll; in slot save we use QTextStream for writing. That may not cause problems in 7 bit ASCII world (read: english :-) ) but may cause failures to read the previously written files with the very same program if the file encoding does not match the guess of QTextStream. I'd suggest to use QTextStream for saving the contents too and to explicitly set a text encoding.



  • Thank you Volker, excellent feedback.

    I'll make sure the Doc team gets it.



  • I found another one:

    Subclassing QWidget not complete
    The header file contains a quit() slot which is actually not implemented. Also, the modified main.cpp is missing, so the example cannot be compiled.

    The missing code:

    from notepad.cpp:

    @
    void Notepad::quit()
    {
    if( QMessageBox::question(
    this,
    tr("Quit?"),
    tr("Do you really want to quit the Notepad?"),
    QMessageBox::Yes | QMessageBox::No,
    QMessageBox::No
    ) == QMessageBox::Yes
    )
    {
    qApp->quit();
    }
    }
    @

    main.cpp:

    @
    #include <QtGui>
    #include "notepad.h"

    int main(int argv, char **args)
    {
    QApplication app(argv, args);

    Notepad window;
    window.show();
    
    return app.exec();
    

    }
    @



  • There's a ticket "QTWEBSITE-163":http://bugreports.qt.nokia.com/browse/QTWEBSITE-163 for this now.



  • Bugs in Qt documentation should be filed against QTWEBSITE or against Qt itself? I'd say the latter, because the documentation is also shipped offline (in assistant / html).

    [Edited to add]: or, of course, Trolls can add a QTDOCS category for bugs in the "official" Qt documentation...



  • I would file against QTWEBSITE and choose doc.qt.nokia.com as the "project" for the issue. Marius did not veto against that for another one ("QTWEBSITE-161":http://bugreports.qt.nokia.com/browse/QTWEBSITE-161) - so it seems ok :-)



  • [quote author="Volker" date="1294157071"]I would file against QTWEBSITE and choose doc.qt.nokia.com as the "project" for the issue.[/quote]

    This is the correct way. When you create the bug report -> just start typing "doc" in the field called "Component/s" and it pops up:

    !http://developer.qt.nokia.com/uploads/image_upload/mariusg_2011-01-04_000192.png(bugreport)!



  • Congrats! Make an article and teach us German first. lol



  • [quote author="mohsen" date="1294168643"]Congrats! Make an article and teach us German first. lol[/quote]

    I'm not sure I understand, care to elaborate?



  • [quote author="mohsen" date="1294168643"]Congrats! Make an article and teach us German first. lol[/quote]

    Do I have missed something?



  • No Volker! just kidding. You did your best. Thank you very much :)



  • In the section "Using a QMainWindow" there are a few typo's in the 2nd code snippet:

    @
    Notepad::Notepad()
    {
    saveAction = new QAction(tr("&Open"), this);
    saveAction = new QAction(tr("&Save"), this);
    exitAction = new QAction(tr("E&xit"), this);
    ...
    connect(exitAction, SIGNAL(triggered()), qApp, SLOT(quit()));
    ...
    @

    Which should be:

    @
    Notepad::Notepad()
    {
    openAction = new QAction(tr("&Open"), this);
    saveAction = new QAction(tr("&Save"), this);
    exitAction = new QAction(tr("&Exit"), this);
    ...
    ...
    connect(exitAction, SIGNAL(triggered()), this, SLOT(quit()));
    ...
    @

    connect(exitAction, SIGNAL(triggered()), qApp, SLOT(quit())); also works, but then QT's standard quit()-function is used, not the one with the confirmation window (QMessageBox) that Volker posted earlier.



  • As a new user, my first attempt at trying Qt was "Getting Started Programming with Qt". It seemed like a reasonable choice given the title. :-)

    I've had much trouble given the subtle errors (and errors by omission) in the document, and now I have a rather involuntary bad taste for Qt.

    The very first document your website recommends reading should be much higher quality. :)

    At the very least, test all the steps on a fresh install of Qt on popular newbie platforms. (Windows, Mac, and Ubuntu come to mind)

    Thank you



  • @nonot1: I have passed your points on to our documentation team. I'm sure they will look into the issues. I assume you have used the latest version of the docs?



  • @Alexandra : Thank you for sending this to the doc team.

    Also, the tutorial tells you to use the "make" command, but this is missing from the Qt SDK 1.1 RC installed environment. Dunno if that's correct or not. Seems wrong, though. Tested on Windows 7, using the "Qt 4.7.3 for Desktop (MinGW)" command prompt window. This should be fixed, or if it's not a bug, spoken about in the tutorial.

    (By searching the /bin folder, I found "mingw32-make.exe"... annoying to type, but that seemed to work.)

    The final as-built applications also only work when instantiated via the development command line window. I assume it's a DLL linking issue, but no mention is made in the tutorial on how to fix this. So, how am I supposed to share my new text-edit application with friends? ;-) This should be spoken about in the tutorial.

    Thank you



  • Hi nonot1,

    the make command you need, depends on the tool-chain you use. On windows, this is typically mingw (mingw32-make.exe) or MSVS (nmake).

    For linux using gcc it's make.

    Regarding the start of the app, the dlls need to be found. On windows, thats is done in the following way:

    Look in the executable dir

    look in the current dir

    look inside windows system dir

    search the %PATH% environment variable for it

    On Linux, it's different (but I'm not sure, how), also for Mac.

    What works for windows, copy the dlls to the executable :-)
    This is also stated in the docs for "distributing":http://doc.qt.nokia.com/4.7/deployment.html



  • Hi Gerolf,

    Thank you for clearing up those points. (And providing background justification)

    As I said, I did eventually figure our how to build and run the application, but the main issue is that the introduction tutorial does not even mention these issues. (Aside from other errors covered earlier in this thread.)

    Not to get the thread off-topic, but there should also be a simple introductory level how-to for using the QtSDK, and it's supplied MinGW tool-chain, to generate size-minimized "single .exe" Qt applications.



  • The size minimize singele .exe can be achieved by using static libs. But this approach is discouraged due to causing problems with plugins and the like. Additionally, if you use WebKit you must use dynamic libs, it's not supported with static linking.



  • @Alexandra

    Quick question.....

    Some of the issues I had were due to rough edges in the 1.1 RC SDK install.

    Where is the correct place to ask about these?



  • [quote author="nonot1" date="1304358997"]
    @Alexandra

    Quick question.....

    Some of the issues I had were due to rough edges in the 1.1 RC SDK install.

    Where is the correct place to ask about these?
    [/quote]

    Just for future reference: you can send a personal message to a person by using the link on her/his profile page



  • I think it is usually good form to keep the discussion on the (public) forum, even if you address one person in particular. That way, also others have the opportunity to answer as well as learn from that answer.

    Like in this case, I might answer - even though my name is not Alexandra - : the right place would be in the Installation and Deployment forum :-)



  • As novice to Qt I followed the source code on the "getting started page":http://doc.qt.nokia.com/4.7/gettingstartedqt.html.
    There were several issues I encountered. Alas, if I only had found this thread during one of my earlier searches on google! This would have saved quite a few hours. Thank you to Volker, Bertus and nonot1 and all others for their helpful contributions!

    There was a lot to be learned by taking this approach, but the learning curve was too steep. Maybe my expectations were set too high after having completed all basic tutorials of Ogre3D without any issues. And the Qt getting started tutorial is well written in that it gives a good overview of Qt and easily is found early on. Perhaps for some the direct move into the "nice tutorials":http://doc.qt.nokia.com/4.7/tutorials.html is a better starting point.

    To recap on some other peoples experiences:
    (1) "http://developer.qt.nokia.com/forums/viewthread/2253":http://developer.qt.nokia.com/forums/viewthread/2253
    (2) "http://www.qtcentre.org/threads/34610-Getting-Started-Programming-with-Qt-tutorial-part2-giving-assertion-fail":http://www.qtcentre.org/threads/34610-Getting-Started-Programming-with-Qt-tutorial-part2-giving-assertion-fail
    (3) "http://stackoverflow.com/questions/7314878/not-able-to-find-quit-slot-and-use-q-object-macro":http://stackoverflow.com/questions/7314878/not-able-to-find-quit-slot-and-use-q-object-macro

    (1) and (2) are complementary in their descriptions. Personally, I preferred the smallest possible change to fix the code by pulling up the line
    @QWidget window;@
    to a point before the definition of the edit and button widgets. This suffices, because during destruction of the objects on the stack the edit and button widgets are destroyed before their parent. If the parent is destroyed first, users of the Visual Studio will see a
    @debug assertion failed ... _BLOCK_TYPE_IS_VALID(pHead->nBlockUse)@
    because the parent auto-destroys its children and the destruction of a non-existant object from the stack fails.

    As Volker and Bertus have pointed out, the implemention of quit() is missing. One solution is to implement it. The other is to use the default slot of qApp. My impression was that quit should never have been declared at all, thus preferring the latter solution.
    Using "this" (as in the original sample) fails because quit() is neither a slot of QWidget nor of QMainWindow. And there is no need to implement quit() in the first place if "qApp" is used instead of "this":
    @connect(quitButton, SIGNAL(clicked()), qApp, SLOT(quit()));@
    If one wishes to define quit(), a short version can be used too:
    @void Notepad::quit() {
    QCoreApplication::instance()->quit(); // or use qApp->quit();
    }@

    If the unpatched code is used, then users of Visual Studio 2010 will see the
    linker choke:
    @moc_Notepad.obj : error LNK2019: unresolved external symbol "public: void __thiscall Notepad::quit(void)" (?quit(at)Notepad
    (at)(at)QAEXXZ) referenced in function "public: virtual int __thiscall Notepad::qt_metacall(enum QMetaObject::Call,int,void *
    *)" (?qt_metacall(at)Notepad(at)(at)UAEHW4Call(at)QMetaObject(at)(at)HPAPAX(at)Z)@

    Other recommendations on the web have suggested one of the following to fix this and similar messages. Here they are not needed, but I found them to be good general advice:
    Check the source code and config settings in the .pro file. Check if the moc files were created, compiled and linked. Check that the project is in a clean state before building.

    The include directive
    @#include <QtGui>@
    is non-functional in Visual Studio 2010 under the default settings.
    @error: can not open source file "QtGui"@
    Only a Qt project that is provided by the Visual Studio QT plugin has the
    additional include path of
    @$(QTDIR)\include\QtGui@
    Without the plugin or when using a default empty VC++ project, this path has not been set. It is not needed, when one uses a single additional include path
    @$(QTDIR)\include @
    Which works well enough when specifying
    @#include <QtGui\QtGui>@
    Or include the headers individually. One file is not located in the QtGui folder
    @#include <QtCore\QTextStream>@
    Actually, I liked that fact that the tutorial does not require the Visual Studio addin at all. It would be helpful if this would be mentioned. Perhaps by linking out to the prerequisites needed to build the sample code?

    One thing specific to Visual Studio 2010 SP1 is that a warning from IntelliSense about inability to generate PCH will show up. To avoid this warning I used an empty main.h header. The warning is documented and occurs, because it cant find a declaration that is outside of an #if-block.

    After taking care of the above noted issues, the final sample application builds flawlessly in Visual Studio with default settings. Nonetheless the application will crash before showing the window, if the previously posted bugfix in this thread for
    @saveAction = new QAction(tr("&Open"), this); // should be openAction = ...
    saveAction = new QAction(tr("&Save"), this);@
    is not introduced, because openAction is not initialized before it is used.

    Hope this is able to help some people who have recently started with Qt.



  • wow. How is it 2013 and these issues are still unresolved?

    Just got started coding in cxx and qt and found this site. Add another issue to this tutorial: all the "learn more" links all go to the same anchor. That is the first anchor about windows.

    Seriously, can someone fix this?


  • Moderators

    Hi cxx::qmanic,

    Thanks for bringing up the "Learn more" issue. I've filed a bug report at https://bugreports.qt-project.org/browse/QTBUG-32110

    The documentation linked from the original post is the archived version of Qt 4.7 docs, which are no longer being developed. The currently-maintained versions of Qt are Qt 5.0 (released in 2012) and Qt 4.8 (released in 2011).

    If you're new, I highly recommend starting with Qt 5. You can find the updated documentation at http://doc-snapshot.qt-project.org/qt5-release/qtdoc/gettingstartedqt.html -- the original issues are gone.

    If you find any more issues, please report them to https://bugreports.qt-project.org -- reports in this forum unlikely to be seen by Qt's engineers and will get buried under all the other posts.



  • "The documentation linked from the original post is the archived version of Qt 4.7 docs, which are no longer being developed. The currently-maintained versions of Qt are Qt 5.0 (released in 2012) and Qt 4.8 (released in 2011)."

    Not really sure what you're saying here. The documentation I'm speaking of is located here: http://qt-project.org/doc/qt-4.8/gettingstartedqt.html and if 4.8 is still maintained then it would be nice to update the documentation accordingly so Devs can have reliable documentation to learn from.

    "If you’re new, I highly recommend starting with Qt 5. You can find the updated documentation at http://doc-snapshot.qt-project.org/qt5-release/qtdoc/gettingstartedqt.html — the original issues are gone."

    Which is fine if a developer wanted to start with 5.0, but if they were to start with 4.8 - which we are currently using at work for example - then those issues would still persist. So again, I iterate my first point: just update the docs for 4.8 to what it should be. It'll only frustrate developers.

    Also I noticed in your bug report that you created a ticker for 5.0 - which still has the same anchor issue. Do both 5.0 and 4.8 "learn more" sections link to the same place? Is this what you were saying in your response thus Updating one will update the other? If so great, if not again my first point about correcting the docs for 4.8.

    Thanks for taking the time to reply and even creating a bug report. Much appreciated.


  • Moderators

    [quote author="cxx::qmanic" date="1372610754"][quote author="JKSH" date="1372564126"]The documentation linked from the original post is the archived version of Qt 4.7 docs, which are no longer being developed. The currently-maintained versions of Qt are Qt 5.0 (released in 2012) and Qt 4.8 (released in 2011).[/quote]
    Not really sure what you're saying here. The documentation I'm speaking of is located here: http://qt-project.org/doc/qt-4.8/gettingstartedqt.html and if 4.8 is still maintained then it would be nice to update the documentation accordingly so Devs can have reliable documentation to learn from.[/quote]I was saying that the issues only exist in Qt 4.7; everything that Volker, Bertus and densewater mentioned is fixed in the Qt 4.8 page that you linked. The only issue left that I can see is the anchoring, which now has a formal bugtracker ticket.

    nonot1's struggle with make is toolchain-specific -- Qt supports many different tools; showing all the variants of make will just clutter the tutorial. As for missing DLLs, that's a topic on deployment which has "entire pages":http://qt-project.org/doc/qt-4.8/deployment.html#platform-specific-notes dedicated to it -- it's not quite "Getting Started" material (and it's not Qt-specific either).

    Have I missed anything?

    The issues still exist in the archived Qt 4.7 docs, because that's what it is -- an archived copy, which won't (and shouldn't) be changed.

    [quote author="cxx::qmanic" date="1372610754"]Also I noticed in your bug report that you created a ticker for 5.0 - which still has the same anchor issue. Do both 5.0 and 4.8 "learn more" sections link to the same place? Is this what you were saying in your response thus Updating one will update the other? If so great, if not again my first point about correcting the docs for 4.8.[/quote]They don't link to the same place, as they have independent code bases. To keep the 2 versions in sync, the procedure is to push changes to Qt 5.x first, then cherry-pick important fixes over to Qt 4.8.[/quote]

    [quote author="cxx::qmanic" date="1372610754"]Thanks for taking the time to reply and even creating a bug report. Much appreciated.[/quote]You're welcome :) That's what a community is for!


Log in to reply
 

Looks like your connection to Qt Forum was lost, please wait while we try to reconnect.