g-application-add-main-option-entries (application entries)

application -- a g-application instance
entries -- a list of option entries

Adds main option entries to be handled by the application.

See the g-option-context-add-main-entries function for a documentation of the list of option entries.

After the command line arguments are parsed, the "handle-local-options" signal will be emitted. At this point, the application can inspect the values pointed to by the arg-data field in the given option entries.

Unlike the g-option-context implementation, the g-application class supports giving nil for the arg-data field for a non-callback option entry. This results in the argument in question being packed into a g-variant-dict parameter which is also passed to the "handle-local-options" signal handler, where it can be inspected and modified. If the :handles-command-line flag is set, then the resulting dictionary is sent to the primary instance, where the g-application-command-line-options-dict function will return it. 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, i.e. we do not pack a g-variant parameter in the case that a flag is missing.

In general, it is recommended that all command line arguments are parsed locally. The options dictionary should then be used to transmit the result of the parsing to the primary instance, where the g-variant-dict-lookup function can be used. For local options, it is possible to either use the arg-data field 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 command line arguments, options and all, to the primary instance for handling. The g-application instance 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 the :handles-command-line flag is unset.

If the "handle-local-options" signal needs to see the list of filenames, then the use of G_OPTION_REMAINING is recommended. If the arg-data field is nil 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 g-variant parameter format when retrieving the options with the g-variant-dict-lookup function:

• for :none, use "b"
• for :string, use "&s"
• for :int, use "i"
• for :int64, use "x"
• for :double, use "d"
• for :filename, use "^ay"
• for :string-array, use "&as"
• for :filename-array, use "^aay"