class KCmdLineArgs


Module kdecore
Namespace
Class KCmdLineArgs
Inherits
A class for command-line argument handling.

KCmdLineArgs provides simple access to the command-line arguments for an application. It takes into account Qt-specific options, KDE-specific options and application specific options.

This class is used in %main() via the static method init().

A typical %KDE application using %KCmdLineArgs should look like this:

int main(int argc, char *argv[])
{
// Initialize command line args
KCmdLineArgs.init(argc, argv, appName, programName, version, description);

// Define the command line options using KCmdLineOptions KCmdLineOptions options; ....

// Register the supported options KCmdLineArgs.addCmdLineOptions( options );

// Add options from other components KUniqueApplication.addCmdLineOptions();

....

// Create application object without passing 'argc' and 'argv' again. KUniqueApplication app;

....

// Handle our own options/arguments // A KApplication will usually do this in main but this is not // necessary. // A KUniqueApplication might want to handle it in newInstance().

KCmdLineArgs *args = KCmdLineArgs.parsedArgs();

// A binary option (on / off) if (args->isSet("some-option")) ....

// An option which takes an additional argument QString anotherOptionArg = args->getOption("another-option");

// Arguments (e.g. files to open) for(int i = 0; i < args->count(); i++) // Counting start at 0! { openFile( args->arg(i)); // Or more convenient: // openUrl( args->url(i));

}

args->clear(); // Free up some memory. .... }

The options that an application supports are configured using the KCmdLineOptions class. An example is shown below:

KCmdLineOptions options;
options.add("a", ki18n("A short binary option"));
options.add("b \", ki18n("A short option which takes an argument"));
options.add("c \", ki18n("As above but with a default value"), "9600");
options.add("option1", ki18n("A long binary option, off by default"));
options.add("nooption2", ki18n("A long binary option, on by default"));
options.add(":", ki18n("Extra options:"));
options.add("option3 \", ki18n("A long option which takes an argument"));
options.add("option4 \", ki18n("A long option which takes an argument, defaulting to 9600"), "9600");
options.add("d");
options.add("option5", ki18n("A long option which has a short option as alias"));
options.add("e");
options.add("nooption6", ki18n("Another long option with an alias"));
options.add("f");
options.add("option7 \", ki18n("'--option7 speed' is the same as '-f speed'"));
options.add("!option8 \", ki18n("All options following this one will be treated as arguments"));
options.add("+file", ki18n("A required argument 'file'"));
options.add("+[arg1]", ki18n("An optional argument 'arg1'"));
options.add("!+command", ki18n("A required argument 'command', that can contain multiple words, even starting with '-'"));
options.add("", ki18n("Additional help text not associated with any particular option"));

The ki18n calls are used for translation instead of the more usual i18n calls, because the translation needs to be delayed until after the message catalogs have been initialized.

Note that a program should define the options before any arguments.

When a long option has a short option as an alias, a program should only test for the long option.

With the above options a command line could look like:

myapp -a -c 4800 --display localhost:0.0 --nooption5 -d /tmp/file

Long binary options can be in the form 'option' and 'nooption'. A command line may contain the same binary option multiple times, the last option determines the outcome:

myapp --nooption4 --option4 --nooption4
is the same as:
myapp --nooption4

If an option value is provided multiple times, normally only the last value is used:

myapp -c 1200 -c 2400 -c 4800
is usually the same as:
myapp -c 4800

However, an application can choose to use all values specified as well. As an example of this, consider that you may wish to specify a number of directories to use:

myapp -I /usr/include -I /opt/kde/include -I /usr/X11/include
When an application does this it should mention this in the description of the option. To access these options, use getOptionList()

Tips for end-users:

  • Single char options like "-a -b -c" may be combined into "-abc"
  • The option "--foo bar" may also be written "--foo=bar"
  • The option "-P lp1" may also be written "-P=lp1" or "-Plp1"
  • The option "--foo bar" may also be written "-foo bar"
  • Author Waldo Bastian Version: 0.0.4



    enums

    enum details

    methods