An OptionContext defines which options are accepted by the commandline option parser. More...
#include <glibmm/optioncontext.h>
Public Types | |
typedef sigc::slot < Glib::ustring, const Glib::ustring& > | SlotTranslate |
This function is used to translate user-visible strings, for --help output. | |
Public Member Functions | |
OptionContext (const Glib::ustring& parameter_string=Glib::ustring()) | |
Creates a new option context. | |
OptionContext (GOptionContext* castitem, bool take_ownership=false) | |
virtual | ~OptionContext () |
void | set_help_enabled (bool help_enabled=true) |
Enables or disables automatic generation of <option>--help</option> output. | |
bool | get_help_enabled () const |
Returns whether automatic <option>--help</option> generation is turned on for context. | |
void | set_ignore_unknown_options (bool ignore_unknown=true) |
Sets whether to ignore unknown options or not. | |
bool | get_ignore_unknown_options () const |
Returns whether unknown options are ignored or not. | |
bool | parse (int& argc, char**& argv) |
Parses the command line arguments, recognizing options which have been added to context. | |
void | add_group (OptionGroup& group) |
Adds an OptionGroup to the context, so that parsing with context will recognize the options in the group. | |
void | set_main_group (OptionGroup& group) |
Sets an OptionGroup as the main group of the context. | |
Glib::ustring | get_help (bool main_help, const OptionGroup& group) const |
Returns a formatted, translated help text for the given context. | |
Glib::ustring | get_help (bool main_help=true) const |
GOptionContext* | gobj () |
const GOptionContext* | gobj () const |
void | set_summary (const Glib::ustring& summary) |
Adds a string to be displayed in --help output before the list of options. | |
Glib::ustring | get_summary () const |
Returns: the summary See set_summary() for more information. | |
void | set_description (const Glib::ustring& description) |
Adds a string to be displayed in --help output after the list of options. | |
Glib::ustring | get_description () const |
Returns: the description See set_description() for more information. | |
void | set_translation_domain (const Glib::ustring& domain) |
A convenience function to use gettext() for translating user-visible strings. | |
void | set_translate_func (const SlotTranslate& slot) |
Sets the function which is used to translate user-visible strings, for --help output. | |
Protected Attributes | |
GOptionContext* | gobject_ |
bool | has_ownership_ |
An OptionContext defines which options are accepted by the commandline option parser.
typedef sigc::slot<Glib::ustring, const Glib::ustring&> Glib::OptionContext::SlotTranslate |
This function is used to translate user-visible strings, for --help output.
The function takes an untranslated string and returns a translated string
Glib::OptionContext::OptionContext | ( | const Glib::ustring& | parameter_string = Glib::ustring() |
) | [explicit] |
Creates a new option context.
parameter_string | A string which is displayed in the first line of --help output, after programname [OPTION...] |
Glib::OptionContext::OptionContext | ( | GOptionContext * | castitem, | |
bool | take_ownership = false | |||
) | [explicit] |
virtual Glib::OptionContext::~OptionContext | ( | ) | [virtual] |
void Glib::OptionContext::add_group | ( | OptionGroup& | group | ) |
Adds an OptionGroup to the context, so that parsing with context will recognize the options in the group.
Note that the group will not be copied, so it should exist for as long as the context exists.
group | The group to add. |
Glib::ustring Glib::OptionContext::get_description | ( | ) | const |
Returns: the description See set_description() for more information.
Glib::ustring Glib::OptionContext::get_help | ( | bool | main_help = true |
) | const |
Glib::ustring Glib::OptionContext::get_help | ( | bool | main_help, | |
const OptionGroup& | group | |||
) | const |
Returns a formatted, translated help text for the given context.
To obtain the text produced by <option>--help</option>, call <literal>g_option_context_get_help (context, true
, 0
)</literal>. To obtain the text produced by <option>--help-all</option>, call <literal>g_option_context_get_help (context, false
, 0
)</literal>. To obtain the help text for an option group, call <literal>g_option_context_get_help (context, false
, group)</literal>.
main_help | If true , only include the main group. | |
group | The OptionGroup to create help for, or 0 . |
bool Glib::OptionContext::get_help_enabled | ( | ) | const |
Returns whether automatic <option>--help</option> generation is turned on for context.
See g_option_context_set_help_enabled().
true
if automatic help generation is turned on. bool Glib::OptionContext::get_ignore_unknown_options | ( | ) | const |
Returns whether unknown options are ignored or not.
See g_option_context_set_ignore_unknown_options().
true
if unknown options are ignored. Glib::ustring Glib::OptionContext::get_summary | ( | ) | const |
const GOptionContext* Glib::OptionContext::gobj | ( | ) | const [inline] |
GOptionContext* Glib::OptionContext::gobj | ( | ) | [inline] |
bool Glib::OptionContext::parse | ( | int & | argc, | |
char **& | argv | |||
) |
Parses the command line arguments, recognizing options which have been added to context.
A side-effect of calling this function is that g_set_prgname() will be called.
If the parsing is successful, any parsed arguments are removed from the array and argc and argv are updated accordingly. A '--' option is stripped from argv unless there are unparsed options before and after it, or some of the options after it start with '-'. In case of an error, argc and argv are left unmodified.
If automatic <option>--help</option> support is enabled (see g_option_context_set_help_enabled()), and the argv array contains one of the recognized help options, this function will produce help output to stdout and call <literal>exit (0)</literal>.
Note that function depends on the <link linkend="setlocale">current locale</link> for automatic character set conversion of string and filename arguments.
argc | A pointer to the number of command line arguments. | |
argv | A pointer to the array of command line arguments. |
true
if the parsing was successful, false
if an error occurred. void Glib::OptionContext::set_description | ( | const Glib::ustring& | description | ) |
Adds a string to be displayed in --help output after the list of options.
This text often includes a bug reporting address.
Note that the summary is translated (see set_translate_func()).
void Glib::OptionContext::set_help_enabled | ( | bool | help_enabled = true |
) |
Enables or disables automatic generation of <option>--help</option> output.
By default, g_option_context_parse() recognizes <option>--help</option>, <option>-h</option>, <option>-?</option>, <option>--help-all</option> and <option>--help-</option><replaceable>groupname</replaceable> and creates suitable output to stdout.
help_enabled | true to enable <option>--help</option>, false to disable it. |
void Glib::OptionContext::set_ignore_unknown_options | ( | bool | ignore_unknown = true |
) |
Sets whether to ignore unknown options or not.
If an argument is ignored, it is left in the argv array after parsing. By default, g_option_context_parse() treats unknown options as error.
This setting does not affect non-option arguments (i.e. arguments which don't start with a dash). But note that GOption cannot reliably determine whether a non-option belongs to a preceding unknown option.
ignore_unknown | true to ignore unknown options, false to produce an error when unknown options are met. |
void Glib::OptionContext::set_main_group | ( | OptionGroup& | group | ) |
Sets an OptionGroup as the main group of the context.
This has the same effect as calling add_group(), the only difference is that the options in the main group are treated differently when generating --help output. Note that the group will not be copied, so it should exist for as long as the context exists.
group | The group to add. |
void Glib::OptionContext::set_summary | ( | const Glib::ustring& | summary | ) |
Adds a string to be displayed in --help output before the list of options.
This is typically a summary of the program functionality.
Note that the summary is translated (see set_translate_func(), set_translation_domain()).
void Glib::OptionContext::set_translate_func | ( | const SlotTranslate& | slot | ) |
Sets the function which is used to translate user-visible strings, for --help output.
Different groups can use different functions.
If you are using gettext(), you only need to set the translation domain, see set_translation_domain().
void Glib::OptionContext::set_translation_domain | ( | const Glib::ustring& | domain | ) |
A convenience function to use gettext() for translating user-visible strings.
GOptionContext* Glib::OptionContext::gobject_ [protected] |
bool Glib::OptionContext::has_ownership_ [protected] |