After the commandline arguments are parsed, the
#GApplication::handle-local-options signal will be emitted. At this
point, the application can inspect the values pointed to by arg_data
in the given #GOptionEntrys.
Unlike #GOptionContext, #GApplication supports giving a null
arg_data for a non-callback #GOptionEntry. This results in the
argument in question being packed into a #GVariantDict which is also
passed to #GApplication::handle-local-options, where it can be
inspected and modified. If gio.types.ApplicationFlags.HandlesCommandLine is
set, then the resulting dictionary is sent to the primary instance,
where gio.application_command_line.ApplicationCommandLine.getOptionsDict will return it.
As it has been passed outside the process at this point, the types of all
values in the options dict must be checked before being used.
This "packing" is done according to the type of the argument --
booleans for normal flags, strings for strings, bytestrings for
filenames, etc. The packing only occurs if the flag is given (ie: we
do not pack a "false" #GVariant in the case that a flag is missing).
In general, it is recommended that all commandline arguments are
parsed locally. The options dictionary should then be used to
transmit the result of the parsing to the primary instance, where
glib.variant_dict.VariantDict.lookup can be used. For local options, it is
possible to either use arg_data in the usual way, or to consult (and
potentially remove) the option from the options dictionary.
This function is new in GLib 2.40. Before then, the only real choice
was to send all of the commandline arguments (options and all) to the
primary instance for handling. #GApplication ignored them completely
on the local side. Calling this function "opts in" to the new
behaviour, and in particular, means that unrecognised options will be
treated as errors. Unrecognised options have never been ignored when
gio.types.ApplicationFlags.HandlesCommandLine is unset.
If #GApplication::handle-local-options needs to see the list of
filenames, then the use of G_OPTION_REMAINING is recommended. If
arg_data is null then G_OPTION_REMAINING can be used as a key into
the options dictionary. If you do use G_OPTION_REMAINING then you
need to handle these arguments for yourself because once they are
consumed, they will no longer be visible to the default handling
(which treats them as filenames to be opened).
Adds main option entries to be handled by application.
This function is comparable to glib.option_context.OptionContext.addMainEntries.
After the commandline arguments are parsed, the #GApplication::handle-local-options signal will be emitted. At this point, the application can inspect the values pointed to by arg_data in the given #GOptionEntrys.
Unlike #GOptionContext, #GApplication supports giving a null arg_data for a non-callback #GOptionEntry. This results in the argument in question being packed into a #GVariantDict which is also passed to #GApplication::handle-local-options, where it can be inspected and modified. If gio.types.ApplicationFlags.HandlesCommandLine is set, then the resulting dictionary is sent to the primary instance, where gio.application_command_line.ApplicationCommandLine.getOptionsDict will return it. As it has been passed outside the process at this point, the types of all values in the options dict must be checked before being used. This "packing" is done according to the type of the argument -- booleans for normal flags, strings for strings, bytestrings for filenames, etc. The packing only occurs if the flag is given (ie: we do not pack a "false" #GVariant in the case that a flag is missing).
In general, it is recommended that all commandline arguments are parsed locally. The options dictionary should then be used to transmit the result of the parsing to the primary instance, where glib.variant_dict.VariantDict.lookup can be used. For local options, it is possible to either use arg_data in the usual way, or to consult (and potentially remove) the option from the options dictionary.
This function is new in GLib 2.40. Before then, the only real choice was to send all of the commandline arguments (options and all) to the primary instance for handling. #GApplication ignored them completely on the local side. Calling this function "opts in" to the new behaviour, and in particular, means that unrecognised options will be treated as errors. Unrecognised options have never been ignored when gio.types.ApplicationFlags.HandlesCommandLine is unset.
If #GApplication::handle-local-options needs to see the list of filenames, then the use of G_OPTION_REMAINING is recommended. If arg_data is null then G_OPTION_REMAINING can be used as a key into the options dictionary. If you do use G_OPTION_REMAINING then you need to handle these arguments for yourself because once they are consumed, they will no longer be visible to the default handling (which treats them as filenames to be opened).
It is important to use the proper GVariant format when retrieving the options with glib.variant_dict.VariantDict.lookup: