253
255
* For convenience, the restrictions on application identifiers are
254
256
* reproduced here:
255
* - Application identifiers must contain only the ASCII characters "[A-Z][a-z][0-9]_-." and must not begin with a digit.
256
* - Application identifiers must contain at least one '.' (period) character (and thus at least three elements).
257
* - Application identifiers must not begin or end with a '.' (period) character.
258
* - Application identifiers must not contain consecutive '.' (period) characters.
258
* - Application identifiers must contain only the ASCII characters
259
* "[A-Z][a-z][0-9]_-." and must not begin with a digit.
261
* - Application identifiers must contain at least one '.' (period)
262
* character (and thus at least three elements).
264
* - Application identifiers must not begin or end with a '.' (period)
267
* - Application identifiers must not contain consecutive '.' (period)
259
270
* - Application identifiers must not exceed 255 characters.
261
271
* @param application_id A potential application identifier.
262
272
* @return <tt>true</tt> if @a application_id is valid.
407
417
void set_action_group(const Glib::RefPtr<ActionGroup>& action_group);
420
//TODO: We need to be able to add a group, not just some entries,
421
//so we can do pre and post parsing. See https://bugzilla.gnome.org/show_bug.cgi?id=727602
423
//TODO: Custom write the documentation for this method?
424
//_WRAP_METHOD_DOCS_ONLY(g_application_add_main_option_entries)
425
//void add_main_option_entry(Glib::OptionEntry& entry);
426
//__IGNORE(g_application_add_main_option_entries)
429
/** Adds a OptionGroup to the commandline handling of @a application.
431
* This function is comparable to Glib::option_context_add_group().
433
* Unlike g_application_add_main_option_entries(), this function does
434
* not deal with <tt>0</tt> @a arg_data and never transmits options to the
437
* The reason for that is because, by the time the options arrive at the
438
* primary instance, it is typically too late to do anything with them.
439
* Taking the GTK option group as an example: GTK will already have been
440
* initialised by the time the Application::signal_command_line() handler runs.
441
* In the case that this is not the first-running instance of the
442
* application, the existing instance may already have been running for
445
* This means that the options from OptionGroup are only really usable
446
* in the case that the instance of the application being run is the
447
* first instance. Passing options like `--display=` or `--gdk-debug=`
448
* on future runs will have no effect on the existing primary instance.
450
* Calling this function will cause the options in the supplied option
451
* group to be parsed, but it does not cause you to be "opted in" to the
452
* new functionality whereby unrecognised options are rejected even if
453
* APPLICATION_HANDLES_COMMAND_LINE was given.
456
* @param group A OptionGroup.
458
void add_option_group(Glib::OptionGroup& group);
410
461
/** Checks if @a application is registered.
554
605
* is intended to be returned by main(). Although you are expected to pass
555
606
* the @a argc, @a argv parameters from main() to this function, it is possible
556
607
* to pass <tt>0</tt> if @a argv is not available or commandline handling is not
559
* First, the local_command_line() virtual function is invoked.
560
* This function always runs on the local instance. It gets passed a pointer
561
* to a <tt>0</tt>-terminated copy of @a argv and is expected to remove the arguments
562
* that it handled (shifting up remaining arguments). See
563
* <xref linkend="gapplication-example-cmdline2"/> for an example of
564
* parsing @a argv manually. Alternatively, you may use the OptionContext API,
565
* after setting <tt>argc = g_strv_length (argv);</tt>.
567
* The last argument to local_command_line() is a pointer to the @a status
568
* variable which can used to set the exit status that is returned from
569
* g_application_run().
571
* If local_command_line() returns <tt>true</tt>, the command line is expected
572
* to be completely handled, including possibly registering as the primary
573
* instance, calling g_application_activate() or g_application_open(), etc.
575
* If local_command_line() returns <tt>false</tt> then the application is registered
576
* and the Application::signal_command_line() signal is emitted in the primary
577
* instance (which may or may not be this instance). The signal handler
578
* gets passed a ApplicationCommandLine object that (among other things)
579
* contains the remaining commandline arguments that have not been handled
580
* by local_command_line().
582
* If the application has the APPLICATION_HANDLES_COMMAND_LINE
583
* flag set then the default implementation of local_command_line()
584
* always returns <tt>false</tt> immediately, resulting in the commandline
585
* always being handled in the primary instance.
587
* Otherwise, the default implementation of local_command_line() tries
588
* to do a couple of things that are probably reasonable for most
589
* applications. First, g_application_register() is called to attempt
590
* to register the application. If that works, then the command line
591
* arguments are inspected. If no commandline arguments are given, then
592
* g_application_activate() is called. If commandline arguments are
593
* given and the APPLICATION_HANDLES_OPEN flag is set then they
594
* are assumed to be filenames and g_application_open() is called.
596
* If you need to handle commandline arguments that are not filenames,
597
* and you don't mind commandline handling to happen in the primary
598
* instance, you should set APPLICATION_HANDLES_COMMAND_LINE and
599
* process the commandline arguments in your Application::signal_command_line()
600
* signal handler, either manually or using the OptionContext API.
608
* required. Note that on Windows, @a argc and @a argv are ignored, and
609
* Glib::win32_get_command_line() is called internally (for proper support
610
* of Unicode commandline arguments).
612
* Application will attempt to parse the commandline arguments. You
613
* can add commandline flags to the list of recognised options by way of
614
* g_application_add_main_option_entries(). After this, the
615
* Application::signal_handle_local_options() signal is emitted, from which the
616
* application can inspect the values of its OptionEntrys.
618
* Application::signal_handle_local_options() is a good place to handle options
619
* such as `--version`, where an immediate reply from the local process is
620
* desired (instead of communicating with an already-running instance).
621
* A Application::signal_handle_local_options() handler can stop further processing
622
* by returning a non-negative value, which then becomes the exit status of
625
* What happens next depends on the flags: if
626
* APPLICATION_HANDLES_COMMAND_LINE was specified then the remaining
627
* commandline arguments are sent to the primary instance, where a
628
* Application::signal_command_line() signal is emitted. Otherwise, the
629
* remaining commandline arguments are assumed to be a list of files.
630
* If there are no files listed, the application is activated via the
631
* Application::signal_activate() signal. If there are one or more files, and
632
* APPLICATION_HANDLES_OPEN was specified then the files are opened
633
* via the Application::signal_open() signal.
602
635
* If you are interested in doing more complicated local handling of the
603
636
* commandline then you should implement your own Application subclass
604
637
* and override local_command_line(). In this case, you most likely want
605
638
* to return <tt>true</tt> from your local_command_line() implementation to
606
639
* suppress the default handling. See
607
* <xref linkend="gapplication-example-cmdline2"/> for an example.
640
* [gapplication-example-cmdline2.c][gapplication-example-cmdline2]
609
643
* If, after the above is done, the use count of the application is zero
610
644
* then the exit status is returned immediately. If the use count is
917
951
Glib::SignalProxy1< int,const Glib::RefPtr<ApplicationCommandLine>& > signal_command_line();
954
//TODO: Remove no_default_handler when we can break ABI
955
//TODO: Avoid the use of the Variants in the VariantDict?
956
//TODO: Should options definitely be non-const? Confirm that the handler is meant to modify it.
960
* @par Slot Prototype:
961
* <tt>int on_my_%handle_local_options(const Glib::RefPtr<Glib::VariantDict>& options)</tt>
963
* The signal_handle_local_options() signal is emitted on the local instance
964
* after the parsing of the commandline options has occurred.
966
* You can add options to be recognised during commandline option
967
* parsing using g_application_add_main_option_entries() and
968
* g_application_add_option_group().
970
* Signal handlers can inspect @a options (along with values pointed to
971
* from the @a arg_data of an installed OptionEntrys) in order to
972
* decide to perform certain actions, including direct local handling
973
* (which may be useful for options like --version).
975
* If the options have been "handled" then a non-negative value should
976
* be returned. In this case, the return value is the exit status: 0
977
* for success and a positive value for failure. -1 means to continue
980
* In the event that the application is marked
981
* APPLICATION_HANDLES_COMMAND_LINE the "normal processing" will
982
* send the @a option dictionary to the primary instance where it can be
983
* read with Glib::application_command_line_get_options(). The signal
984
* handler can modify the dictionary before returning, and the
985
* modified dictionary will be sent.
987
* In the event that APPLICATION_HANDLES_COMMAND_LINE is not set,
988
* "normal processing" will treat the remaining uncollected command
989
* line arguments as filenames or URIs. If there are no arguments,
990
* the application is activated by g_application_activate(). One or
991
* more arguments results in a call to g_application_open().
993
* If you want to handle the local commandline arguments for yourself
994
* by converting them to calls to g_application_open() or
995
* g_action_group_activate_action() then you must be sure to register
996
* the application first. You should probably not call
997
* g_application_activate() for yourself, however: just return -1 and
998
* allow the default handler to do it for you. This will ensure that
999
* the `--gapplication-service` switch works properly (i.e. no activation
1002
* Note that this signal is emitted from the default implementation of
1003
* local_command_line(). If you override that function and don't
1004
* chain up then this signal will never be emitted.
1006
* You can override local_command_line() if you need more powerful
1007
* capabilities than what is provided here, but this should not
1008
* normally be required.
1011
* @param options The options dictionary.
1014
Glib::SignalProxy1< int,const Glib::RefPtr<Glib::VariantDict>& > signal_handle_local_options();
921
1018
virtual void on_open(const type_vec_files& files, const Glib::ustring& hint);
added
removed
gio/giomm/application.h
