|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.kde.koala.KCmdLineArgs
public class KCmdLineArgs
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(String[] args) { // Initialize command line args KCmdLineArgs.init(args, appName, programName, description, version); // Tell which options are supported 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 String anotherOptionArg = args.getOption("another-option"); // Arguments (e.g. files to open) for(int i = 0; i < args.count(); i++) // Counting start at 0! { // don't forget to convert to Unicode! openFile( QFile.decodeName( 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 String[][] class. An example is shown below:
static String[][] options = { { "a", I18N_NOOP("A short binary option"), 0 }, { "b \The I18N_NOOP macro is used to indicate that these strings should be marked for translation. The actual translation is done by KCmdLineArgs. You can't use i18n() here because we are setting up a static data structure and can't do translations at compile time. 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:", I18N_NOOP("A short option which takes an argument"), 0 }, { "c \ ", I18N_NOOP("As above but with a default value"), "9600" }, { "option1", I18N_NOOP("A long binary option, off by default"), 0 }, { "nooption2", I18N_NOOP("A long binary option, on by default"), 0 }, { ":", I18N_NOOP("Extra options:"), 0 }, { "option3 \ ", I18N_NOOP("A long option which takes an argument"), 0 }, { "option4 \ ", I18N_NOOP("A long option which takes an argument, defaulting to 9600"), "9600" }, { "d", 0, 0 }, { "option5", I18N_NOOP("A long option which has a short option as alias"), 0 }, { "e", 0, 0 }, { "nooption6", I18N_NOOP("Another long option with an alias"), 0 }, { "f", 0, 0 }, { "option7 \ ", I18N_NOOP("'--option7 speed' is the same as '-f speed'"), 0 }, { "!option8 \ ", I18N_NOOP("All options following this one will be treated as arguments"), 0 }, { "+file", I18N_NOOP("A required argument 'file'"), 0 }, { "+[arg1]", I18N_NOOP("An optional argument 'arg1'"), 0 }, { "!+command", I18N_NOOP("A required argument 'command', that can contain multiple words, even starting with '-'"), 0 }, { "", I18N_NOOP("Additional help text not associated with any particular option") 0 }, // End of options. }
myapp -a -c 4800 --display localhost:0.0 --nooption5 -d /tmp/fileLong 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 --nooption4is the same as:
myapp --nooption4If an option value is provided multiple times, normally only the last value is used:
myapp -c 1200 -c 2400 -c 4800is usually the same as:
myapp -c 4800However, 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/includeWhen an application does this it should mention this in the description of the option. To access these options, use getOptionList() Tips for end-users:
Constructor Summary | |
---|---|
protected |
KCmdLineArgs(java.lang.Class dummy)
|
|
KCmdLineArgs(java.lang.String[][] _options,
java.lang.String _name,
java.lang.String _id)
Constructor. |
Method Summary | |
---|---|
static void |
addCmdLineOptions(java.lang.String[][] options)
|
static void |
addCmdLineOptions(java.lang.String[][] options,
java.lang.String name)
|
static void |
addCmdLineOptions(java.lang.String[][] options,
java.lang.String name,
java.lang.String id)
|
static void |
addCmdLineOptions(java.lang.String[][] options,
java.lang.String name,
java.lang.String id,
java.lang.String afterId)
Add options to your application. |
static void |
addTempFileOption()
Add standard option --tempfile |
static java.lang.String |
appName()
Get the appname according to argv[0]. |
java.lang.String |
arg(int n)
Read out an argument. |
void |
clear()
Clear all options and arguments. |
int |
count()
Read the number of arguments that aren't options (but, for example, filenames). |
static java.lang.String |
cwd()
Get the CWD (Current Working Directory) associated with the current command line arguments. |
static void |
enable_i18n()
Enable i18n to be able to print a translated error message. |
java.lang.String |
getOption(java.lang.String option)
Read out a string option. |
java.util.ArrayList |
getOptionList(java.lang.String option)
Read out all occurrences of a string option. |
static void |
init(KAboutData about)
Initialize Class This function should be called as the very first thing in your application. |
static void |
init(java.lang.String[] _argv,
KAboutData about)
|
static void |
init(java.lang.String[] _argv,
KAboutData about,
boolean noKApp)
Initialize class. |
static void |
init(java.lang.String[] _argv,
java.lang.String _appname,
java.lang.String programName,
java.lang.String _description,
java.lang.String _version)
|
static void |
init(java.lang.String[] _argv,
java.lang.String _appname,
java.lang.String programName,
java.lang.String _description,
java.lang.String _version,
boolean noKApp)
Initialize class. |
boolean |
isSet(java.lang.String option)
Read out a booleanean option or check for the presence of string option. |
static boolean |
isTempFileSet()
|
static void |
loadAppArgs(org.kde.qt.QDataStream arg1)
Load arguments from a stream. |
static KURL |
makeURL(java.lang.String urlArg)
Used by url(). |
static KCmdLineArgs |
parsedArgs()
|
static KCmdLineArgs |
parsedArgs(java.lang.String id)
Access parsed arguments. |
static void |
reset()
Reset all option definitions, i.e. |
static void |
setCwd(java.lang.String cwd)
Made public for apps that don't use KCmdLineArgs To be done before makeURL, to set the current working directory in case makeURL needs it. |
KURL |
url(int n)
Read out an argument representing a URL. |
static void |
usage()
|
static void |
usage(java.lang.String id)
Print the usage help to stdout and exit. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
protected KCmdLineArgs(java.lang.Class dummy)
public KCmdLineArgs(java.lang.String[][] _options, java.lang.String _name, java.lang.String _id)
Method Detail |
---|
public java.lang.String getOption(java.lang.String option)
{ "option \You cannot test for the presence of an alias - you must always test for the full option.", I18N_NOOP("Description"), "default" }
option
- The name of the option without '-'.
public java.util.ArrayList getOptionList(java.lang.String option)
{ "option \You cannot test for the presence of an alias - you must always test for the full option.", I18N_NOOP("Description"), "default" }
option
- The name of the option, without '-' or '-no'.
public boolean isSet(java.lang.String option)
option
- The name of the option without '-' or '-no'.
public int count()
public java.lang.String arg(int n)
n
- The argument to read. 0 is the first argument.
count()-1 is the last argument.
const
char
* pointer to the n'th argument.public KURL url(int n)
n
- The argument to read. 0 is the first argument.
count()-1 is the last argument.
public void clear()
public static void init(java.lang.String[] _argv, java.lang.String _appname, java.lang.String programName, java.lang.String _description, java.lang.String _version, boolean noKApp)
_argv
- As passed to main
(...)._appname
- The untranslated name of your application. This should
match with argv
[0].programName
- A program name string to be used for display
purposes. This string should be marked for
translation. Example: I18N_NOOP("KEdit")_description
- A short description of what your application is about._version
- A version.noKApp
- Set this true to not add commandline options for
QApplication / KApplicationpublic static void init(java.lang.String[] _argv, java.lang.String _appname, java.lang.String programName, java.lang.String _description, java.lang.String _version)
public static void init(java.lang.String[] _argv, KAboutData about, boolean noKApp)
_argv
- As passed to main
(...).about
- A KAboutData object describing your program.noKApp
- Set this true to not add commandline options for
QApplication / KApplicationpublic static void init(java.lang.String[] _argv, KAboutData about)
public static void init(KAboutData about)
about
- the about data.
\see KAboutDatapublic static void addCmdLineOptions(java.lang.String[][] options, java.lang.String name, java.lang.String id, java.lang.String afterId)
static String[][] options = { { "option1 \", I18N_NOOP("Description 1"), "my_extra_arg" }, { "o", 0, 0 }, { "option2", I18N_NOOP("Description 2"), 0 }, { "nooption3", I18N_NOOP("Description 3"), 0 }, }
KCmdLineArgs args = KCmdLineArgs.parsedArgs(); if (args.count() == 0) KCmdLineArgs.usage(i18n("No file specified!"));
cmd = myapp [options] file options = (option) option = --option1 \Instead of "--option3" one may also use "-option3" Usage examples:| (-o | --option2 | --nooption2) | ( --option3 | --nooption3 )
options
- A list of options that your code supplies.name
- the name of the option, can be 0.id
- A name with which these options can be identified, can be 0.afterId
- The options are inserted after this set of options, can be 0.public static void addCmdLineOptions(java.lang.String[][] options, java.lang.String name, java.lang.String id)
public static void addCmdLineOptions(java.lang.String[][] options, java.lang.String name)
public static void addCmdLineOptions(java.lang.String[][] options)
public static KCmdLineArgs parsedArgs(java.lang.String id)
id
- The name of the options you are interested in, can be 0.public static KCmdLineArgs parsedArgs()
public static java.lang.String cwd()
public static java.lang.String appName()
public static void usage(java.lang.String id)
id
- if 0, print all options. If id is set, only print the
option specified by id. The id is the value set by
addCmdLineOptions().public static void usage()
public static void enable_i18n()
public static KURL makeURL(java.lang.String urlArg)
urlArg
- the argument
public static void setCwd(java.lang.String cwd)
cwd
- the new working directorypublic static void reset()
public static void loadAppArgs(org.kde.qt.QDataStream arg1)
public static void addTempFileOption()
public static boolean isTempFileSet()
|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |