diff options
| author | Friedemann Kleint <Friedemann.Kleint@digia.com> | 2014-03-11 09:35:35 +0100 |
|---|---|---|
| committer | The Qt Project <gerrit-noreply@qt-project.org> | 2014-03-15 10:44:41 +0100 |
| commit | 51e5378113ac185ce9b3f64417416243050f6335 (patch) | |
| tree | d99bbe1bf9f5c8359282b5aa6ce242a1a426e499 /src/corelib/tools | |
| parent | 00fe7bd975be844a63d688a12d10a2e9611baf4a (diff) | |
Use QCommandLineParser in example dnslookup.
Show how use QCommandLineParser with additional
parameter checking for custom options and positional
arguments.
Also explain how to display help in GUI applications.
Change-Id: I03513e09b7dd5b150259593da0af2ef2a281cab2
Reviewed-by: David Faure <david.faure@kdab.com>
Diffstat (limited to 'src/corelib/tools')
| -rw-r--r-- | src/corelib/tools/qcommandlineparser.cpp | 72 |
1 files changed, 72 insertions, 0 deletions
diff --git a/src/corelib/tools/qcommandlineparser.cpp b/src/corelib/tools/qcommandlineparser.cpp index c860b4d155..505ab5f46d 100644 --- a/src/corelib/tools/qcommandlineparser.cpp +++ b/src/corelib/tools/qcommandlineparser.cpp @@ -187,6 +187,78 @@ QStringList QCommandLineParserPrivate::aliases(const QString &optionName) const QCoreApplication::arguments() before QCommandLineParser defines the \c{profile} option and parses the command line. + \section2 How to Use QCommandLineParser in Complex Applications + + In practice, additional error checking needs to be performed on the positional + arguments and option values. For example, ranges of numbers should be checked. + + It is then advisable to introduce a function to do the command line parsing + which takes a struct or class receiving the option values returning an + enumeration representing the result. The dnslookup example of the QtNetwork + module illustrates this: + + \snippet dnslookup.h 0 + + \snippet dnslookup.cpp 0 + + In the main function, help should be printed to the standard output if the help option + was passed and the application should return the exit code 0. + + If an error was detected, the error message should be printed to the standard + error output and the application should return an exit code other than 0. + + \snippet dnslookup.cpp 1 + + A special case to consider here are GUI applications on Windows and mobile + platforms. These applications may not use the standard output or error channels + since the output is either discarded or not accessible. + + For such GUI applications, it is recommended to display help texts and error messages + using a QMessageBox. To preserve the formatting of the help text, rich text + with \c <pre> elements should be used: + + \code + + switch (parseCommandLine(parser, &query, &errorMessage)) { + case CommandLineOk: + break; + case CommandLineError: +#ifdef Q_OS_WIN + QMessageBox::warning(0, QGuiApplication::applicationDisplayName(), + "<html><head/><body><h2>" + errorMessage + "</h2><pre>" + + parser.helpText() + "</pre></body></html>"); +#else + fputs(qPrintable(errorMessage), stderr); + fputs("\n\n", stderr); + fputs(qPrintable(parser.helpText()), stderr); +#endif + return 1; + case CommandLineVersionRequested: +#ifdef Q_OS_WIN + QMessageBox::information(0, QGuiApplication::applicationDisplayName(), + QGuiApplication::applicationDisplayName() + ' ' + + QCoreApplication::applicationVersion()); +#else + printf("%s %s\n", QGuiApplication::applicationDisplayName(), + qPrintable(QCoreApplication::applicationVersion())); +#endif + return 0; + case CommandLineHelpRequested: +#ifdef Q_OS_WIN + QMessageBox::warning(0, QGuiApplication::applicationDisplayName(), + "<html><head/><body><pre>" + + parser.helpText() + "</pre></body></html>"); + return 0; +#else + parser.showHelp(); + Q_UNREACHABLE(); +#endif + } + \endcode + + However, this does not apply to the dnslookup example, because it is a + console application. + \sa QCommandLineOption, QCoreApplication */ |