Xfce Foundation Classes
Main Page | Index | Namespace List | Alphabetical List | Class List | File List

# Xfc::G::OptionGroup Class Reference

A C++ wrapper interface for the GOptionGroup. More...

`#include <xfc/glib/option.hh>`

Inheritance diagram for Xfc::G::OptionGroup:

List of all members.

## Public Member Functions

Constructors

- OptionGroup ()
    Constructs a MAIN option group only.
- OptionGroup (const char *name, const char *description, const char *help_description)
    Constructs a new option group.
- OptionGroup (GOptionGroup *group, bool can_free)
    Construct a new option group from an existing GOptionGroup.
- ~OptionGroup ()
    Destrcutor frees the group if the group has not been added to an option context.

Accessors

- GOptionGroup * g_option_group () const
    Get a pointer to the GOptionGroup object.
- operator GOptionGroup * () const
    Conversion operator; Safely converts a G::OptionGroup object into a GOptionGroup pointer.
- const GOptionEntry * get_entries () const
    Obtains a pointer to the internal GOptionGroup array that holds the options added to the group.

Methods

- virtual bool on_parse (const char *option_name, const char *value, Error &error)
    Called to parse options that were added to the group using one of the callback add methods.
- virtual bool on_pre_parse (OptionContext &context, Error &error)
    Callback method, called before parsing the group.
- virtual bool on_post_parse (OptionContext &context, Error &error)
    Callback method, called after parsing the group.
- virtual void on_error (OptionContext &context, const Error &error)
    Callback method, called when a parse error occurs.
- void set_translation_domain (const String &domain)
    A convenience method to use gettext() for translating user-visible strings.

Callback Add Methods

- void add (const char *long_name, char short_name, const char *description, const char *arg_description)
    Adds an option to the group that gets passed to on_parse() to parse the extra argument.
- void add (const char *long_name, char short_name, OptionFlagsField flags, const char *description, const char *arg_description)
    Adds an option to the group that gets passed to on_parse() to parse the extra argument.

Boolean Add Methods

- void add (const char *long_name, char short_name, bool &arg, const char *description)
    Adds an boolean option to the group.
- void add (const char *long_name, char short_name, OptionFlagsField flags, bool &arg, const char *description)
    Adds an boolean option to the group.

Integer Add Methods

- void add (const char *long_name, char short_name, int &arg, const char *description, const char *arg_description)
    Adds an integer option to the group.
- void add (const char *long_name, char short_name, OptionFlagsField flags, int &arg, const char *description, const char *arg_description)
    Adds an integer option to the group.

String Add Methods

- void add (const char *long_name, char short_name, String &arg, const char *description, const char *arg_description)
    Adds a string option to the group.
- void add (const char *long_name, char short_name, OptionFlagsField flags, String &arg, const char *description, const char *arg_description)
    Adds a string option to the group.
- void add (const char *long_name, char short_name, std::vector< String > &arg, const char *description, const char *arg_description)
    Adds a string vector option to the group.
- void add (const char *long_name, char short_name, OptionFlagsField flags, std::vector< String > &arg, const char *description, const char *arg_description)
    Adds a string vector option to the group.

Filename Add Methods

- void add (const char *long_name, char short_name, std::string &arg, const char *description, const char *arg_description)
    Adds a filename option to the group.
- void add (const char *long_name, char short_name, OptionFlagsField flags, std::string &arg, const char *description, const char *arg_description)
    Adds a filename option to the group.
- void add (const char *long_name, char short_name, std::vector< std::string > &arg, const char *description, const char *arg_description)
    Adds a filename vector option to the group.
- void add (const char *long_name, char short_name, OptionFlagsField flags, std::vector< std::string > &arg, const char *description, const char *arg_description)
    Adds a filename vector option to the group.

## Detailed Description

A C++ wrapper interface for the GOptionGroup.

OptionGroup defines the options in a single group. All options in a group share the same translation function. Libaries which need to parse commandline options are expected to provide a function for getting an OptionGroup holding their options, which the application can then add to its G::OptionContext.

## Constructor & Destructor Documentation

Xfc::G::OptionGroup::OptionGroup | ( |  | ) |

| Constructs a MAIN option group only. The MAIN option group does not need to set a user defined "name", "description" or "help_description" so this constructor sets these properties to null. This group should only be used as the MAIN option group and must be passed to the Main::init_with_args() function, the G::OptionContext constructor or the G::OptionContext::set_main_group() method.

Xfc::G::OptionGroup::OptionGroup | ( | const char * | name,
|  | const char * | description,
|  | const char * | help_description
| ) |

Constructs a new option group.

Parameters:

  | name | The name for the option group.
  | description | A description for this group to be shown in --help.
  | help_description | A description for the --help-name option.

The name is used to provide help for the options in this group with --help-name. The description and help_description strings are translated using the translation domain or translation function of the group.

Xfc::G::OptionGroup::OptionGroup | ( | GOptionGroup * | group,
|  | bool | can_free
| ) |

Construct a new option group from an existing GOptionGroup.

Parameters:

  | group | A GOptionGroup.
  | can_free | Set true if the GOptionGroup should be freed by this option group.

This constructor is used to wrap a GOptionGroup pointer in a temporary G::OptionGroup class. You should have no need to use this constructor.

## Member Function Documentation

void Xfc::G::OptionGroup::add | ( | const char * | long_name,
|  | char | short_name,
|  | OptionFlagsField | flags,
|  | std::vector< std::string > & | arg,
|  | const char * | description,
|  | const char * | arg_description
| ) |

Adds a filename vector option to the group.

Parameters:

  | long_name | The long name of the option.
  | short_name | The short name of the option.
  | flags | One or more flags from G::OptionFlags enumeration.
  | arg | A vector of std::string to store the filename values.
  | description | The description for the option in --help output
  | arg_description | The placeholder to use for the extra argument parsed by the option in --help output.

The long name of an option can be used to specify it in a commandline as --long_name. Every option must have a long name. To resolve conflicts if multiple option groups contain the same long name, it is also possible to specify the option as --groupname-long_name. If an option has a short name, it can be specified as -short_name in a commandline. The description and arg_description are translated using the translate_func of the group (see set_translation_domain()).

void Xfc::G::OptionGroup::add | ( | const char * | long_name,
|  | char | short_name,
|  | std::vector< std::string > & | arg,
|  | const char * | description,
|  | const char * | arg_description
| ) |

Adds a filename vector option to the group.

Parameters:

  | long_name | The long name of the option.
  | short_name | The short name of the option.
  | arg | A vector of std::string to store the filename values.
  | description | The description for the option in --help output
  | arg_description | The placeholder to use for the extra argument parsed by the option in --help output.

The long name of an option can be used to specify it in a commandline as --long_name. Every option must have a long name. To resolve conflicts if multiple option groups contain the same long name, it is also possible to specify the option as --groupname-long_name. If an option has a short name, it can be specified as -short_name in a commandline. The description and arg_description are translated using the translate_func of the group (see set_translation_domain()).

void Xfc::G::OptionGroup::add | ( | const char * | long_name,
|  | char | short_name,
|  | OptionFlagsField | flags,
|  | std::string & | arg,
|  | const char * | description,
|  | const char * | arg_description
| ) |

Adds a filename option to the group.

Parameters:

  | long_name | The long name of the option.
  | short_name | The short name of the option.
  | flags | One or more flags from G::OptionFlags enumeration.
  | arg | The return location to store the filename.
  | description | The description for the option in --help output
  | arg_description | The placeholder to use for the extra argument parsed by the option in --help output.

The long name of an option can be used to specify it in a commandline as --long_name. Every option must have a long name. To resolve conflicts if multiple option groups contain the same long name, it is also possible to specify the option as --groupname-long_name. If an option has a short name, it can be specified as -short_name in a commandline. The description and arg_description are translated using the translate_func of the group (see set_translation_domain()).

void Xfc::G::OptionGroup::add | ( | const char * | long_name,
|  | char | short_name,
|  | std::string & | arg,
|  | const char * | description,
|  | const char * | arg_description
| ) |

Adds a filename option to the group.

Parameters:

  | long_name | The long name of the option.
  | short_name | The short name of the option.
  | arg | The return location to store the filename.
  | description | The description for the option in --help output
  | arg_description | The placeholder to use for the extra argument parsed by the option in --help output.

The long name of an option can be used to specify it in a commandline as --long_name. Every option must have a long name. To resolve conflicts if multiple option groups contain the same long name, it is also possible to specify the option as --groupname-long_name. If an option has a short name, it can be specified as -short_name in a commandline. The description and arg_description are translated using the translate_func of the group (see set_translation_domain()).

void Xfc::G::OptionGroup::add | ( | const char * | long_name,
|  | char | short_name,
|  | OptionFlagsField | flags,
|  | std::vector< String > & | arg,
|  | const char * | description,
|  | const char * | arg_description
| ) |

Adds a string vector option to the group.

Parameters:

  | long_name | The long name of the option.
  | short_name | The short name of the option.
  | flags | One or more flags from G::OptionFlags enumeration.
  | arg | A vector of String to store the string values.
  | description | The description for the option in --help output
  | arg_description | The placeholder to use for the extra argument parsed by the option in --help output.

The long name of an option can be used to specify it in a commandline as --long_name. Every option must have a long name. To resolve conflicts if multiple option groups contain the same long name, it is also possible to specify the option as --groupname-long_name. If an option has a short name, it can be specified as -short_name in a commandline. The description and arg_description are translated using the translate_func of the group (see set_translation_domain()).

void Xfc::G::OptionGroup::add | ( | const char * | long_name,
|  | char | short_name,
|  | std::vector< String > & | arg,
|  | const char * | description,
|  | const char * | arg_description
| ) |

Adds a string vector option to the group.

Parameters:

  | long_name | The long name of the option.
  | short_name | The short name of the option.
  | arg | A vector of String to store the string values.
  | description | The description for the option in --help output
  | arg_description | The placeholder to use for the extra argument parsed by the option in --help output.

The long name of an option can be used to specify it in a commandline as --long_name. Every option must have a long name. To resolve conflicts if multiple option groups contain the same long name, it is also possible to specify the option as --groupname-long_name. If an option has a short name, it can be specified as -short_name in a commandline. The description and arg_description are translated using the translate_func of the group (see set_translation_domain()).

void Xfc::G::OptionGroup::add | ( | const char * | long_name,
|  | char | short_name,
|  | OptionFlagsField | flags,
|  | String & | arg,
|  | const char * | description,
|  | const char * | arg_description
| ) |

Adds a string option to the group.

Parameters:

  | long_name | The long name of the option.
  | short_name | The short name of the option.
  | flags | One or more flags from G::OptionFlags enumeration.
  | arg | The return location to store the string.
  | description | The description for the option in --help output
  | arg_description | The placeholder to use for the extra argument parsed by the option in --help output.

The long name of an option can be used to specify it in a commandline as --long_name. Every option must have a long name. To resolve conflicts if multiple option groups contain the same long name, it is also possible to specify the option as --groupname-long_name. If an option has a short name, it can be specified as -short_name in a commandline. The description and arg_description are translated using the translate_func of the group (see set_translation_domain()).

void Xfc::G::OptionGroup::add | ( | const char * | long_name,
|  | char | short_name,
|  | String & | arg,
|  | const char * | description,
|  | const char * | arg_description
| ) |

Adds a string option to the group.

Parameters:

  | long_name | The long name of the option.
  | short_name | The short name of the option.
  | arg | The return location to store the string.
  | description | The description for the option in --help output
  | arg_description | The placeholder to use for the extra argument parsed by the option in --help output.

The long name of an option can be used to specify it in a commandline as --long_name. Every option must have a long name. To resolve conflicts if multiple option groups contain the same long name, it is also possible to specify the option as --groupname-long_name. If an option has a short name, it can be specified as -short_name in a commandline. The description and arg_description are translated using the translate_func of the group (see set_translation_domain()).

void Xfc::G::OptionGroup::add | ( | const char * | long_name,
|  | char | short_name,
|  | OptionFlagsField | flags,
|  | int & | arg,
|  | const char * | description,
|  | const char * | arg_description
| ) |

Adds an integer option to the group.

Parameters:

  | long_name | The long name of the option.
  | short_name | The short name of the option.
  | flags | One or more flags from G::OptionFlags enumeration.
  | arg | The return location to store the integer value.
  | description | The description for the option in --help output
  | arg_description | The placeholder to use for the extra argument parsed by the option in --help output.

The long name of an option can be used to specify it in a commandline as --long_name. Every option must have a long name. To resolve conflicts if multiple option groups contain the same long name, it is also possible to specify the option as --groupname-long_name. If an option has a short name, it can be specified as -short_name in a commandline. The description and arg_description are translated using the translate_func of the group (see set_translation_domain()).

void Xfc::G::OptionGroup::add | ( | const char * | long_name,
|  | char | short_name,
|  | int & | arg,
|  | const char * | description,
|  | const char * | arg_description
| ) |

Adds an integer option to the group.

Parameters:

  | long_name | The long name of the option.
  | short_name | The short name of the option.
  | arg | The return location to store the integer value.
  | description | The description for the option in --help output
  | arg_description | The placeholder to use for the extra argument parsed by the option in --help output.

The long name of an option can be used to specify it in a commandline as --long_name. Every option must have a long name. To resolve conflicts if multiple option groups contain the same long name, it is also possible to specify the option as --groupname-long_name. If an option has a short name, it can be specified as -short_name in a commandline. The description and arg_description are translated using the translate_func of the group (see set_translation_domain()).

void Xfc::G::OptionGroup::add | ( | const char * | long_name,
|  | char | short_name,
|  | OptionFlagsField | flags,
|  | bool & | arg,
|  | const char * | description
| ) |

Adds an boolean option to the group.

Parameters:

  | long_name | The long name of the option.
  | short_name | The short name of the option.
  | flags | One or more flags from G::OptionFlags enumeration.
  | arg | The return location to store the boolean value.
  | description | The description for the option in --help output

The long name of an option can be used to specify it in a commandline as --long_name. Every option must have a long name. To resolve conflicts if multiple option groups contain the same long name, it is also possible to specify the option as --groupname-long_name. If an option has a short name, it can be specified as -short_name in a commandline. The description is translated using the translate_func of the group (see set_translation_domain()).

void Xfc::G::OptionGroup::add | ( | const char * | long_name,
|  | char | short_name,
|  | bool & | arg,
|  | const char * | description
| ) |

Adds an boolean option to the group.

Parameters:

  | long_name | The long name of the option.
  | short_name | The short name of the option.
  | arg | The return location to store the boolean value.
  | description | The description for the option in --help output

The long name of an option can be used to specify it in a commandline as --long_name. Every option must have a long name. To resolve conflicts if multiple option groups contain the same long name, it is also possible to specify the option as --groupname-long_name. If an option has a short name, it can be specified as -short_name in a commandline. The description is translated using the translate_func of the group (see set_translation_domain()).

void Xfc::G::OptionGroup::add | ( | const char * | long_name,
|  | char | short_name,
|  | OptionFlagsField | flags,
|  | const char * | description,
|  | const char * | arg_description
| ) |

Adds an option to the group that gets passed to on_parse() to parse the extra argument.

Parameters:

  | long_name | The long name of the option.
  | short_name | The short name of the option.
  | flags | One or more flags from G::OptionFlags enumeration.
  | description | The description for the option in --help output
  | arg_description | The placeholder to use for the extra argument parsed by the option in --help output.

The long name of an option can be used to specify it in a commandline as --long_name. Every option must have a long name. To resolve conflicts if multiple option groups contain the same long name, it is also possible to specify the option as --groupname-long_name. If an option has a short name, it can be specified as -short_name in a commandline. The description and arg_description are translated using the translate_func of the group (see set_translation_domain()).

void Xfc::G::OptionGroup::add | ( | const char * | long_name,
|  | char | short_name,
|  | const char * | description,
|  | const char * | arg_description
| ) |

Adds an option to the group that gets passed to on_parse() to parse the extra argument.

Parameters:

  | long_name | The long name of the option.
  | short_name | The short name of the option.
  | description | The description for the option in --help output
  | arg_description | The placeholder to use for the extra argument parsed by the option in --help output.

The long name of an option can be used to specify it in a commandline as --long_name. Every option must have a long name. To resolve conflicts if multiple option groups contain the same long name, it is also possible to specify the option as --groupname-long_name. If an option has a short name, it can be specified as -short_name in a commandline. The description and arg_description are translated using the translate_func of the group (see set_translation_domain()).

const GOptionEntry* Xfc::G::OptionGroup::get_entries | ( |  | ) | const

Obtains a pointer to the internal GOptionGroup array that holds the options added to the group.

Returns:
  A pointer to the internal GOptionGroup array.

This is an internal method called by Main::init_with_args(). It is of no real use to the application programmer.

virtual void Xfc::G::OptionGroup::on_error | ( | OptionContext & | context,
|  | const Error & | error
| ) | `[virtual]`

Callback method, called when a parse error occurs.

Parameters:

  | context | The active option context.
  | error | The G::Error containing details about the parse error.

virtual bool Xfc::G::OptionGroup::on_parse | ( | const char * | option_name,
|  | const char * | value,
|  | Error & | error
| ) | `[virtual]`

Called to parse options that were added to the group using one of the callback add methods.

Parameters:

  | option_name | The name of the option being parsed.
  | value | The value to be parsed.
  | error | The return location for errors.

Returns:
  true if the option was successfully parsed, false if an error occurred.

This method is a group-wide callback that is called to parse any options added to the group using one of the callback add methods. The option_name will be either a single dash followed by a single letter (for a short name) or two dashes followed by a long option name. The error code G::OPTION_ERROR_FAILED should be used for any errors that occur during parsing.

virtual bool Xfc::G::OptionGroup::on_post_parse | ( | OptionContext & | context,
|  | Error & | error
| ) | `[virtual]`

Callback method, called after parsing the group.

Parameters:

  | context | The active option context.
  | error | The return location for error details.

Returns:
  true if the method completed successfully, false if an error occurred.

Override this method if your option group has any post-parse processing to do. If you do, be sure to call or return this parent method because it does some essential processing.

virtual bool Xfc::G::OptionGroup::on_pre_parse | ( | OptionContext & | context,
|  | Error & | error
| ) | `[virtual]`

Callback method, called before parsing the group.

Parameters:

  | context | The active option context.
  | error | The return location for error details.

Returns:
  true if the method completed successfully, false if an error occurred.

Override this method if your option group has any pre-parse processing to do.

void Xfc::G::OptionGroup::set_translation_domain | ( | const String & | domain | ) |

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

Parameters:

  | domain | The domain to use.

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

- option.hh

Xfce Foundation Classes

Copyright © 2004-2005 The XFC Development Team | XFC 4.3