QAbstractSpinBox documented poorly
-
QAbstractSpinBox is a superclass not meant to use directly, but to subclass. But the documentation doesn't explain how to subclass it properly and gives no examples. Subclassing it for long long value was fairly easy. But how do I do it for a complicated data type when I want to store the inner value and have it updated at the right time? I think I've managed it, but I can not be sure.
Example of vague documentation:
bq. void QAbstractSpinBox::interpretText()
This function interprets the text of the spin box. If the value has changed since last interpretation it will emit signals.Emit what signals?
Please make a clear documentation for this class and proper complex subclassing tutorial.
Also, the source for QAbstractSpinBox is awfully hard to understand due to use of weird macros, one letter variables and the class QAbstractSpinBoxPrivate with unexplained purpose.
ED: Sorry, I posted wrong code of my subclass in here. Shall post the working draft later.
ED2: Rewrote my subclass to not store anything and rely only on the input. So far I'm frustrated with inability to validate and parse to inner value at the same time since validate() is const. Have to parse once to validate and then again to get the value.
-
You should post your findings as a bug/ request on "JIRA":https://qt-project.org/wiki/ReportingBugsInQt, which is the bugtracker Qt uses.
-
and for "weird macros, one letter variables and the class QAbstractSpinBoxPrivate", you should read documentation about "d-pointer":http://qt-project.org/wiki/Dpointer.
-
Thank you, tilsitt. That explains a lot. I think that should be added to (offline) documentation as well.
-
[quote author="Mystery Keeper" date="1357656763"]Thank you, tilsitt. That explains a lot. I think that should be added to (offline) documentation as well.[/quote]I think that knowledge is only relevant to people who maintain/develop Qt itself, and people who're interested in studying Qt's internals. People who use Qt to write apps shouldn't need to know that Qt uses the D-pointer pattern internally. They shouldn't need to know that QAbstractSpinBoxPrivate even exists -- they should be able to do everything they could possibly need via QAbstractSpinBox itself.
The offline docs are aimed at helping people use Qt, so I think info about D-pointers shouldn't be in them. I do agree that the offline docs needs polishing though, to improve clarity on how to use those public classes.
Like sierdzio said, do file a bug report; Qt's maintainers don't visit these forums much, so the bug tracker makes it more likely for them to see your request.