Glib::OptionContext Class Reference

An OptionContext defines which options are accepted by the commandline option parser. More...

List of all members.

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: true if automatic help generation is turned on.

void set_ignore_unknown_options (bool ignore_unknown=true)

Sets whether to ignore unknown options or not.

bool get_ignore_unknown_options () const

Returns: true if unknown options are ignored.

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.

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_

Detailed Description

An OptionContext defines which options are accepted by the commandline option parser.

Member Typedef Documentation

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

Constructor & Destructor Documentation

Glib::OptionContext::OptionContext ( const Glib::ustring& parameter_string = Glib::ustring() ) [explicit]

Creates a new option context.

Parameters:

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]

Member Function Documentation

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>-?</option>, <option>--help-all</option> and <option>--help-</option><replaceable>groupname</replaceable> and creates suitable output to stdout.

Since glibmm 2.6:

Parameters:

help_enabled true to enable <option>--help</option>, false to disable it.

bool Glib::OptionContext::get_help_enabled ( ) const

Returns: true if automatic help generation is turned on.

Returns:: true if automatic help generation is turned on.

Since glibmm 2.6:

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.

Since glibmm 2.6:

Parameters:

ignore_unknown true to ignore unknown options, false to produce an error when unknown options are met.

bool Glib::OptionContext::get_ignore_unknown_options ( ) const

Returns: true if unknown options are ignored.

Returns:: true if unknown options are ignored.

Since glibmm 2.6:

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 exit (0).

Note that function depends on the current locale for automatic character set conversion of string and filename arguments.

Parameters:

	argc	A pointer to the number of command line arguments.
	argv	A pointer to the array of command line arguments.
	error	A return location for errors.

Returns:: true if the parsing was successful, false if an error occurred

Since glibmm 2.6:

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.

Parameters:

group

The group to add.

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.

Parameters:

group

The group to add.

GOptionContext* Glib::OptionContext::gobj ( ) [inline]

const GOptionContext* Glib::OptionContext::gobj ( ) const [inline]

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()).

Since glibmm 2.14:

Glib::ustring Glib::OptionContext::get_summary ( ) const

Returns: the summary See set_summary() for more information.

Returns:: The summary

Since glibmm 2.14:

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()).

Since glibmm 2.14:

Glib::ustring Glib::OptionContext::get_description ( ) const

Returns: the description See set_description() for more information.

Returns:: The description

Since glibmm 2.14:

void Glib::OptionContext::set_translation_domain ( const Glib::ustring& domain )

A convenience function to use gettext() for translating user-visible strings.

Since glibmm 2.14:

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().

Since glibmm 2.14:

Member Data Documentation

GOptionContext* Glib::OptionContext::gobject_ [protected]

bool Glib::OptionContext::has_ownership_ [protected]

The documentation for this class was generated from the following file:

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: `true` if automatic help generation is turned on.
void	set_ignore_unknown_options (bool ignore_unknown=true)
	Sets whether to ignore unknown options or not.
bool	get_ignore_unknown_options () const
	Returns: `true` if unknown options are ignored.
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.
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_