1 /* 2 * This file is part of gtkD. 3 * 4 * gtkD is free software; you can redistribute it and/or modify 5 * it under the terms of the GNU Lesser General Public License 6 * as published by the Free Software Foundation; either version 3 7 * of the License, or (at your option) any later version, with 8 * some exceptions, please read the COPYING file. 9 * 10 * gtkD is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public License 16 * along with gtkD; if not, write to the Free Software 17 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA 18 */ 19 20 // generated automatically - do not change 21 // find conversion definition on APILookup.txt 22 // implement new conversion functionalities on the wrap.utils pakage 23 24 25 module gio.Application; 26 27 private import gio.ActionGroupIF; 28 private import gio.ActionGroupT; 29 private import gio.ActionMapIF; 30 private import gio.ActionMapT; 31 private import gio.ApplicationCommandLine; 32 private import gio.Cancellable; 33 private import gio.DBusConnection; 34 private import gio.File; 35 private import gio.FileIF; 36 private import gio.Notification; 37 private import glib.ConstructionException; 38 private import glib.ErrorG; 39 private import glib.GException; 40 private import glib.OptionGroup; 41 private import glib.Str; 42 private import glib.VariantDict; 43 private import gobject.ObjectG; 44 private import gobject.Signals; 45 public import gtkc.gdktypes; 46 private import gtkc.gio; 47 public import gtkc.giotypes; 48 49 50 /** 51 * A #GApplication is the foundation of an application. It wraps some 52 * low-level platform-specific services and is intended to act as the 53 * foundation for higher-level application classes such as 54 * #GtkApplication or #MxApplication. In general, you should not use 55 * this class outside of a higher level framework. 56 * 57 * GApplication provides convenient life cycle management by maintaining 58 * a "use count" for the primary application instance. The use count can 59 * be changed using g_application_hold() and g_application_release(). If 60 * it drops to zero, the application exits. Higher-level classes such as 61 * #GtkApplication employ the use count to ensure that the application 62 * stays alive as long as it has any opened windows. 63 * 64 * Another feature that GApplication (optionally) provides is process 65 * uniqueness. Applications can make use of this functionality by 66 * providing a unique application ID. If given, only one application 67 * with this ID can be running at a time per session. The session 68 * concept is platform-dependent, but corresponds roughly to a graphical 69 * desktop login. When your application is launched again, its 70 * arguments are passed through platform communication to the already 71 * running program. The already running instance of the program is 72 * called the "primary instance"; for non-unique applications this is 73 * the always the current instance. On Linux, the D-Bus session bus 74 * is used for communication. 75 * 76 * The use of #GApplication differs from some other commonly-used 77 * uniqueness libraries (such as libunique) in important ways. The 78 * application is not expected to manually register itself and check 79 * if it is the primary instance. Instead, the main() function of a 80 * #GApplication should do very little more than instantiating the 81 * application instance, possibly connecting signal handlers, then 82 * calling g_application_run(). All checks for uniqueness are done 83 * internally. If the application is the primary instance then the 84 * startup signal is emitted and the mainloop runs. If the application 85 * is not the primary instance then a signal is sent to the primary 86 * instance and g_application_run() promptly returns. See the code 87 * examples below. 88 * 89 * If used, the expected form of an application identifier is very close 90 * to that of of a 91 * [DBus bus name](http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface). 92 * Examples include: "com.example.MyApp", "org.example.internal-apps.Calculator". 93 * For details on valid application identifiers, see g_application_id_is_valid(). 94 * 95 * On Linux, the application identifier is claimed as a well-known bus name 96 * on the user's session bus. This means that the uniqueness of your 97 * application is scoped to the current session. It also means that your 98 * application may provide additional services (through registration of other 99 * object paths) at that bus name. The registration of these object paths 100 * should be done with the shared GDBus session bus. Note that due to the 101 * internal architecture of GDBus, method calls can be dispatched at any time 102 * (even if a main loop is not running). For this reason, you must ensure that 103 * any object paths that you wish to register are registered before #GApplication 104 * attempts to acquire the bus name of your application (which happens in 105 * g_application_register()). Unfortunately, this means that you cannot use 106 * g_application_get_is_remote() to decide if you want to register object paths. 107 * 108 * GApplication also implements the #GActionGroup and #GActionMap 109 * interfaces and lets you easily export actions by adding them with 110 * g_action_map_add_action(). When invoking an action by calling 111 * g_action_group_activate_action() on the application, it is always 112 * invoked in the primary instance. The actions are also exported on 113 * the session bus, and GIO provides the #GDBusActionGroup wrapper to 114 * conveniently access them remotely. GIO provides a #GDBusMenuModel wrapper 115 * for remote access to exported #GMenuModels. 116 * 117 * There is a number of different entry points into a GApplication: 118 * 119 * - via 'Activate' (i.e. just starting the application) 120 * 121 * - via 'Open' (i.e. opening some files) 122 * 123 * - by handling a command-line 124 * 125 * - via activating an action 126 * 127 * The #GApplication::startup signal lets you handle the application 128 * initialization for all of these in a single place. 129 * 130 * Regardless of which of these entry points is used to start the 131 * application, GApplication passes some "platform data from the 132 * launching instance to the primary instance, in the form of a 133 * #GVariant dictionary mapping strings to variants. To use platform 134 * data, override the @before_emit or @after_emit virtual functions 135 * in your #GApplication subclass. When dealing with 136 * #GApplicationCommandLine objects, the platform data is 137 * directly available via g_application_command_line_get_cwd(), 138 * g_application_command_line_get_environ() and 139 * g_application_command_line_get_platform_data(). 140 * 141 * As the name indicates, the platform data may vary depending on the 142 * operating system, but it always includes the current directory (key 143 * "cwd"), and optionally the environment (ie the set of environment 144 * variables and their values) of the calling process (key "environ"). 145 * The environment is only added to the platform data if the 146 * %G_APPLICATION_SEND_ENVIRONMENT flag is set. #GApplication subclasses 147 * can add their own platform data by overriding the @add_platform_data 148 * virtual function. For instance, #GtkApplication adds startup notification 149 * data in this way. 150 * 151 * To parse commandline arguments you may handle the 152 * #GApplication::command-line signal or override the local_command_line() 153 * vfunc, to parse them in either the primary instance or the local instance, 154 * respectively. 155 * 156 * For an example of opening files with a GApplication, see 157 * [gapplication-example-open.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-open.c). 158 * 159 * For an example of using actions with GApplication, see 160 * [gapplication-example-actions.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-actions.c). 161 * 162 * For an example of using extra D-Bus hooks with GApplication, see 163 * [gapplication-example-dbushooks.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-dbushooks.c). 164 * 165 * Since: 2.28 166 */ 167 public class Application : ObjectG, ActionGroupIF, ActionMapIF 168 { 169 /** the main Gtk struct */ 170 protected GApplication* gApplication; 171 172 /** Get the main Gtk struct */ 173 public GApplication* getApplicationStruct() 174 { 175 return gApplication; 176 } 177 178 /** the main Gtk struct as a void* */ 179 protected override void* getStruct() 180 { 181 return cast(void*)gApplication; 182 } 183 184 protected override void setStruct(GObject* obj) 185 { 186 gApplication = cast(GApplication*)obj; 187 super.setStruct(obj); 188 } 189 190 /** 191 * Sets our main struct and passes it to the parent class. 192 */ 193 public this (GApplication* gApplication, bool ownedRef = false) 194 { 195 this.gApplication = gApplication; 196 super(cast(GObject*)gApplication, ownedRef); 197 } 198 199 // add the ActionGroup capabilities 200 mixin ActionGroupT!(GApplication); 201 202 // add the ActionMap capabilities 203 mixin ActionMapT!(GApplication); 204 205 /** 206 */ 207 208 public static GType getType() 209 { 210 return g_application_get_type(); 211 } 212 213 /** 214 * Creates a new #GApplication instance. 215 * 216 * If non-%NULL, the application id must be valid. See 217 * g_application_id_is_valid(). 218 * 219 * If no application ID is given then some features of #GApplication 220 * (most notably application uniqueness) will be disabled. 221 * 222 * Params: 223 * applicationId = the application id 224 * flags = the application flags 225 * 226 * Return: a new #GApplication instance 227 * 228 * Throws: ConstructionException GTK+ fails to create the object. 229 */ 230 public this(string applicationId, GApplicationFlags flags) 231 { 232 auto p = g_application_new(Str.toStringz(applicationId), flags); 233 234 if(p is null) 235 { 236 throw new ConstructionException("null returned by new"); 237 } 238 239 this(cast(GApplication*) p, true); 240 } 241 242 /** 243 * Returns the default #GApplication instance for this process. 244 * 245 * Normally there is only one #GApplication per process and it becomes 246 * the default when it is created. You can exercise more control over 247 * this by using g_application_set_default(). 248 * 249 * If there is no default application then %NULL is returned. 250 * 251 * Return: the default application for this process, or %NULL 252 * 253 * Since: 2.32 254 */ 255 public static Application getDefault() 256 { 257 auto p = g_application_get_default(); 258 259 if(p is null) 260 { 261 return null; 262 } 263 264 return ObjectG.getDObject!(Application)(cast(GApplication*) p); 265 } 266 267 /** 268 * Checks if @application_id is a valid application identifier. 269 * 270 * A valid ID is required for calls to g_application_new() and 271 * g_application_set_application_id(). 272 * 273 * For convenience, the restrictions on application identifiers are 274 * reproduced here: 275 * 276 * - Application identifiers must contain only the ASCII characters 277 * "[A-Z][a-z][0-9]_-." and must not begin with a digit. 278 * 279 * - Application identifiers must contain at least one '.' (period) 280 * character (and thus at least three elements). 281 * 282 * - Application identifiers must not begin or end with a '.' (period) 283 * character. 284 * 285 * - Application identifiers must not contain consecutive '.' (period) 286 * characters. 287 * 288 * - Application identifiers must not exceed 255 characters. 289 * 290 * Params: 291 * applicationId = a potential application identifier 292 * 293 * Return: %TRUE if @application_id is valid 294 */ 295 public static bool idIsValid(string applicationId) 296 { 297 return g_application_id_is_valid(Str.toStringz(applicationId)) != 0; 298 } 299 300 /** 301 * Activates the application. 302 * 303 * In essence, this results in the #GApplication::activate signal being 304 * emitted in the primary instance. 305 * 306 * The application must be registered before calling this function. 307 * 308 * Since: 2.28 309 */ 310 public void activate() 311 { 312 g_application_activate(gApplication); 313 } 314 315 /** 316 * Add an option to be handled by @application. 317 * 318 * Calling this function is the equivalent of calling 319 * g_application_add_main_option_entries() with a single #GOptionEntry 320 * that has its arg_data member set to %NULL. 321 * 322 * The parsed arguments will be packed into a #GVariantDict which 323 * is passed to #GApplication::handle-local-options. If 324 * %G_APPLICATION_HANDLES_COMMAND_LINE is set, then it will also 325 * be sent to the primary instance. See 326 * g_application_add_main_option_entries() for more details. 327 * 328 * See #GOptionEntry for more documentation of the arguments. 329 * 330 * Params: 331 * longName = the long name of an option used to specify it in a commandline 332 * shortName = the short name of an option 333 * flags = flags from #GOptionFlags 334 * arg = the type of the option, as a #GOptionArg 335 * description = the description for the option in `--help` output 336 * argDescription = the placeholder to use for the extra argument 337 * parsed by the option in `--help` output 338 * 339 * Since: 2.42 340 */ 341 public void addMainOption(string longName, char shortName, GOptionFlags flags, GOptionArg arg, string description, string argDescription) 342 { 343 g_application_add_main_option(gApplication, Str.toStringz(longName), shortName, flags, arg, Str.toStringz(description), Str.toStringz(argDescription)); 344 } 345 346 /** 347 * Adds main option entries to be handled by @application. 348 * 349 * This function is comparable to g_option_context_add_main_entries(). 350 * 351 * After the commandline arguments are parsed, the 352 * #GApplication::handle-local-options signal will be emitted. At this 353 * point, the application can inspect the values pointed to by @arg_data 354 * in the given #GOptionEntrys. 355 * 356 * Unlike #GOptionContext, #GApplication supports giving a %NULL 357 * @arg_data for a non-callback #GOptionEntry. This results in the 358 * argument in question being packed into a #GVariantDict which is also 359 * passed to #GApplication::handle-local-options, where it can be 360 * inspected and modified. If %G_APPLICATION_HANDLES_COMMAND_LINE is 361 * set, then the resulting dictionary is sent to the primary instance, 362 * where g_application_command_line_get_options_dict() will return it. 363 * This "packing" is done according to the type of the argument -- 364 * booleans for normal flags, strings for strings, bytestrings for 365 * filenames, etc. The packing only occurs if the flag is given (ie: we 366 * do not pack a "false" #GVariant in the case that a flag is missing). 367 * 368 * In general, it is recommended that all commandline arguments are 369 * parsed locally. The options dictionary should then be used to 370 * transmit the result of the parsing to the primary instance, where 371 * g_variant_dict_lookup() can be used. For local options, it is 372 * possible to either use @arg_data in the usual way, or to consult (and 373 * potentially remove) the option from the options dictionary. 374 * 375 * This function is new in GLib 2.40. Before then, the only real choice 376 * was to send all of the commandline arguments (options and all) to the 377 * primary instance for handling. #GApplication ignored them completely 378 * on the local side. Calling this function "opts in" to the new 379 * behaviour, and in particular, means that unrecognised options will be 380 * treated as errors. Unrecognised options have never been ignored when 381 * %G_APPLICATION_HANDLES_COMMAND_LINE is unset. 382 * 383 * If #GApplication::handle-local-options needs to see the list of 384 * filenames, then the use of %G_OPTION_REMAINING is recommended. If 385 * @arg_data is %NULL then %G_OPTION_REMAINING can be used as a key into 386 * the options dictionary. If you do use %G_OPTION_REMAINING then you 387 * need to handle these arguments for yourself because once they are 388 * consumed, they will no longer be visible to the default handling 389 * (which treats them as filenames to be opened). 390 * 391 * Params: 392 * entries = a 393 * %NULL-terminated list of #GOptionEntrys 394 * 395 * Since: 2.40 396 */ 397 public void addMainOptionEntries(GOptionEntry[] entries) 398 { 399 g_application_add_main_option_entries(gApplication, entries.ptr); 400 } 401 402 /** 403 * Adds a #GOptionGroup to the commandline handling of @application. 404 * 405 * This function is comparable to g_option_context_add_group(). 406 * 407 * Unlike g_application_add_main_option_entries(), this function does 408 * not deal with %NULL @arg_data and never transmits options to the 409 * primary instance. 410 * 411 * The reason for that is because, by the time the options arrive at the 412 * primary instance, it is typically too late to do anything with them. 413 * Taking the GTK option group as an example: GTK will already have been 414 * initialised by the time the #GApplication::command-line handler runs. 415 * In the case that this is not the first-running instance of the 416 * application, the existing instance may already have been running for 417 * a very long time. 418 * 419 * This means that the options from #GOptionGroup are only really usable 420 * in the case that the instance of the application being run is the 421 * first instance. Passing options like `--display=` or `--gdk-debug=` 422 * on future runs will have no effect on the existing primary instance. 423 * 424 * Calling this function will cause the options in the supplied option 425 * group to be parsed, but it does not cause you to be "opted in" to the 426 * new functionality whereby unrecognised options are rejected even if 427 * %G_APPLICATION_HANDLES_COMMAND_LINE was given. 428 * 429 * Params: 430 * group = a #GOptionGroup 431 * 432 * Since: 2.40 433 */ 434 public void addOptionGroup(OptionGroup group) 435 { 436 g_application_add_option_group(gApplication, (group is null) ? null : group.getOptionGroupStruct()); 437 } 438 439 /** 440 * Marks @application as busy (see g_application_mark_busy()) while 441 * @property on @object is %TRUE. 442 * 443 * The binding holds a reference to @application while it is active, but 444 * not to @object. Instead, the binding is destroyed when @object is 445 * finalized. 446 * 447 * Params: 448 * object = a #GObject 449 * property = the name of a boolean property of @object 450 * 451 * Since: 2.44 452 */ 453 public void bindBusyProperty(ObjectG object, string property) 454 { 455 g_application_bind_busy_property(gApplication, (object is null) ? null : object.getObjectGStruct(), Str.toStringz(property)); 456 } 457 458 /** 459 * Gets the unique identifier for @application. 460 * 461 * Return: the identifier for @application, owned by @application 462 * 463 * Since: 2.28 464 */ 465 public string getApplicationId() 466 { 467 return Str.toString(g_application_get_application_id(gApplication)); 468 } 469 470 /** 471 * Gets the #GDBusConnection being used by the application, or %NULL. 472 * 473 * If #GApplication is using its D-Bus backend then this function will 474 * return the #GDBusConnection being used for uniqueness and 475 * communication with the desktop environment and other instances of the 476 * application. 477 * 478 * If #GApplication is not using D-Bus then this function will return 479 * %NULL. This includes the situation where the D-Bus backend would 480 * normally be in use but we were unable to connect to the bus. 481 * 482 * This function must not be called before the application has been 483 * registered. See g_application_get_is_registered(). 484 * 485 * Return: a #GDBusConnection, or %NULL 486 * 487 * Since: 2.34 488 */ 489 public DBusConnection getDbusConnection() 490 { 491 auto p = g_application_get_dbus_connection(gApplication); 492 493 if(p is null) 494 { 495 return null; 496 } 497 498 return ObjectG.getDObject!(DBusConnection)(cast(GDBusConnection*) p); 499 } 500 501 /** 502 * Gets the D-Bus object path being used by the application, or %NULL. 503 * 504 * If #GApplication is using its D-Bus backend then this function will 505 * return the D-Bus object path that #GApplication is using. If the 506 * application is the primary instance then there is an object published 507 * at this path. If the application is not the primary instance then 508 * the result of this function is undefined. 509 * 510 * If #GApplication is not using D-Bus then this function will return 511 * %NULL. This includes the situation where the D-Bus backend would 512 * normally be in use but we were unable to connect to the bus. 513 * 514 * This function must not be called before the application has been 515 * registered. See g_application_get_is_registered(). 516 * 517 * Return: the object path, or %NULL 518 * 519 * Since: 2.34 520 */ 521 public string getDbusObjectPath() 522 { 523 return Str.toString(g_application_get_dbus_object_path(gApplication)); 524 } 525 526 /** 527 * Gets the flags for @application. 528 * 529 * See #GApplicationFlags. 530 * 531 * Return: the flags for @application 532 * 533 * Since: 2.28 534 */ 535 public GApplicationFlags getFlags() 536 { 537 return g_application_get_flags(gApplication); 538 } 539 540 /** 541 * Gets the current inactivity timeout for the application. 542 * 543 * This is the amount of time (in milliseconds) after the last call to 544 * g_application_release() before the application stops running. 545 * 546 * Return: the timeout, in milliseconds 547 * 548 * Since: 2.28 549 */ 550 public uint getInactivityTimeout() 551 { 552 return g_application_get_inactivity_timeout(gApplication); 553 } 554 555 /** 556 * Gets the application's current busy state, as set through 557 * g_application_mark_busy() or g_application_bind_busy_property(). 558 * 559 * Return: %TRUE if @application is currenty marked as busy 560 * 561 * Since: 2.44 562 */ 563 public bool getIsBusy() 564 { 565 return g_application_get_is_busy(gApplication) != 0; 566 } 567 568 /** 569 * Checks if @application is registered. 570 * 571 * An application is registered if g_application_register() has been 572 * successfully called. 573 * 574 * Return: %TRUE if @application is registered 575 * 576 * Since: 2.28 577 */ 578 public bool getIsRegistered() 579 { 580 return g_application_get_is_registered(gApplication) != 0; 581 } 582 583 /** 584 * Checks if @application is remote. 585 * 586 * If @application is remote then it means that another instance of 587 * application already exists (the 'primary' instance). Calls to 588 * perform actions on @application will result in the actions being 589 * performed by the primary instance. 590 * 591 * The value of this property cannot be accessed before 592 * g_application_register() has been called. See 593 * g_application_get_is_registered(). 594 * 595 * Return: %TRUE if @application is remote 596 * 597 * Since: 2.28 598 */ 599 public bool getIsRemote() 600 { 601 return g_application_get_is_remote(gApplication) != 0; 602 } 603 604 /** 605 * Gets the resource base path of @application. 606 * 607 * See g_application_set_resource_base_path() for more information. 608 * 609 * Return: the base resource path, if one is set 610 * 611 * Since: 2.42 612 */ 613 public string getResourceBasePath() 614 { 615 return Str.toString(g_application_get_resource_base_path(gApplication)); 616 } 617 618 /** 619 * Increases the use count of @application. 620 * 621 * Use this function to indicate that the application has a reason to 622 * continue to run. For example, g_application_hold() is called by GTK+ 623 * when a toplevel window is on the screen. 624 * 625 * To cancel the hold, call g_application_release(). 626 */ 627 public void hold() 628 { 629 g_application_hold(gApplication); 630 } 631 632 /** 633 * Increases the busy count of @application. 634 * 635 * Use this function to indicate that the application is busy, for instance 636 * while a long running operation is pending. 637 * 638 * The busy state will be exposed to other processes, so a session shell will 639 * use that information to indicate the state to the user (e.g. with a 640 * spinner). 641 * 642 * To cancel the busy indication, use g_application_unmark_busy(). 643 * 644 * Since: 2.38 645 */ 646 public void markBusy() 647 { 648 g_application_mark_busy(gApplication); 649 } 650 651 /** 652 * Opens the given files. 653 * 654 * In essence, this results in the #GApplication::open signal being emitted 655 * in the primary instance. 656 * 657 * @n_files must be greater than zero. 658 * 659 * @hint is simply passed through to the ::open signal. It is 660 * intended to be used by applications that have multiple modes for 661 * opening files (eg: "view" vs "edit", etc). Unless you have a need 662 * for this functionality, you should use "". 663 * 664 * The application must be registered before calling this function 665 * and it must have the %G_APPLICATION_HANDLES_OPEN flag set. 666 * 667 * Params: 668 * files = an array of #GFiles to open 669 * nFiles = the length of the @files array 670 * hint = a hint (or ""), but never %NULL 671 * 672 * Since: 2.28 673 */ 674 public void open(FileIF[] files, string hint) 675 { 676 GFile*[] filesArray = new GFile*[files.length]; 677 for ( int i = 0; i < files.length; i++ ) 678 { 679 filesArray[i] = files[i].getFileStruct(); 680 } 681 682 g_application_open(gApplication, filesArray.ptr, cast(int)files.length, Str.toStringz(hint)); 683 } 684 685 /** 686 * Immediately quits the application. 687 * 688 * Upon return to the mainloop, g_application_run() will return, 689 * calling only the 'shutdown' function before doing so. 690 * 691 * The hold count is ignored. 692 * 693 * The result of calling g_application_run() again after it returns is 694 * unspecified. 695 * 696 * Since: 2.32 697 */ 698 public void quit() 699 { 700 g_application_quit(gApplication); 701 } 702 703 /** 704 * Attempts registration of the application. 705 * 706 * This is the point at which the application discovers if it is the 707 * primary instance or merely acting as a remote for an already-existing 708 * primary instance. This is implemented by attempting to acquire the 709 * application identifier as a unique bus name on the session bus using 710 * GDBus. 711 * 712 * If there is no application ID or if %G_APPLICATION_NON_UNIQUE was 713 * given, then this process will always become the primary instance. 714 * 715 * Due to the internal architecture of GDBus, method calls can be 716 * dispatched at any time (even if a main loop is not running). For 717 * this reason, you must ensure that any object paths that you wish to 718 * register are registered before calling this function. 719 * 720 * If the application has already been registered then %TRUE is 721 * returned with no work performed. 722 * 723 * The #GApplication::startup signal is emitted if registration succeeds 724 * and @application is the primary instance (including the non-unique 725 * case). 726 * 727 * In the event of an error (such as @cancellable being cancelled, or a 728 * failure to connect to the session bus), %FALSE is returned and @error 729 * is set appropriately. 730 * 731 * Note: the return value of this function is not an indicator that this 732 * instance is or is not the primary instance of the application. See 733 * g_application_get_is_remote() for that. 734 * 735 * Params: 736 * cancellable = a #GCancellable, or %NULL 737 * 738 * Return: %TRUE if registration succeeded 739 * 740 * Since: 2.28 741 * 742 * Throws: GException on failure. 743 */ 744 public bool register(Cancellable cancellable) 745 { 746 GError* err = null; 747 748 auto p = g_application_register(gApplication, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err) != 0; 749 750 if (err !is null) 751 { 752 throw new GException( new ErrorG(err) ); 753 } 754 755 return p; 756 } 757 758 /** 759 * Decrease the use count of @application. 760 * 761 * When the use count reaches zero, the application will stop running. 762 * 763 * Never call this function except to cancel the effect of a previous 764 * call to g_application_hold(). 765 */ 766 public void release() 767 { 768 g_application_release(gApplication); 769 } 770 771 /** 772 * Runs the application. 773 * 774 * This function is intended to be run from main() and its return value 775 * is intended to be returned by main(). Although you are expected to pass 776 * the @argc, @argv parameters from main() to this function, it is possible 777 * to pass %NULL if @argv is not available or commandline handling is not 778 * required. Note that on Windows, @argc and @argv are ignored, and 779 * g_win32_get_command_line() is called internally (for proper support 780 * of Unicode commandline arguments). 781 * 782 * #GApplication will attempt to parse the commandline arguments. You 783 * can add commandline flags to the list of recognised options by way of 784 * g_application_add_main_option_entries(). After this, the 785 * #GApplication::handle-local-options signal is emitted, from which the 786 * application can inspect the values of its #GOptionEntrys. 787 * 788 * #GApplication::handle-local-options is a good place to handle options 789 * such as `--version`, where an immediate reply from the local process is 790 * desired (instead of communicating with an already-running instance). 791 * A #GApplication::handle-local-options handler can stop further processing 792 * by returning a non-negative value, which then becomes the exit status of 793 * the process. 794 * 795 * What happens next depends on the flags: if 796 * %G_APPLICATION_HANDLES_COMMAND_LINE was specified then the remaining 797 * commandline arguments are sent to the primary instance, where a 798 * #GApplication::command-line signal is emitted. Otherwise, the 799 * remaining commandline arguments are assumed to be a list of files. 800 * If there are no files listed, the application is activated via the 801 * #GApplication::activate signal. If there are one or more files, and 802 * %G_APPLICATION_HANDLES_OPEN was specified then the files are opened 803 * via the #GApplication::open signal. 804 * 805 * If you are interested in doing more complicated local handling of the 806 * commandline then you should implement your own #GApplication subclass 807 * and override local_command_line(). In this case, you most likely want 808 * to return %TRUE from your local_command_line() implementation to 809 * suppress the default handling. See 810 * [gapplication-example-cmdline2.c][gapplication-example-cmdline2] 811 * for an example. 812 * 813 * If, after the above is done, the use count of the application is zero 814 * then the exit status is returned immediately. If the use count is 815 * non-zero then the default main context is iterated until the use count 816 * falls to zero, at which point 0 is returned. 817 * 818 * If the %G_APPLICATION_IS_SERVICE flag is set, then the service will 819 * run for as much as 10 seconds with a use count of zero while waiting 820 * for the message that caused the activation to arrive. After that, 821 * if the use count falls to zero the application will exit immediately, 822 * except in the case that g_application_set_inactivity_timeout() is in 823 * use. 824 * 825 * This function sets the prgname (g_set_prgname()), if not already set, 826 * to the basename of argv[0]. 827 * 828 * Since 2.40, applications that are not explicitly flagged as services 829 * or launchers (ie: neither %G_APPLICATION_IS_SERVICE or 830 * %G_APPLICATION_IS_LAUNCHER are given as flags) will check (from the 831 * default handler for local_command_line) if "--gapplication-service" 832 * was given in the command line. If this flag is present then normal 833 * commandline processing is interrupted and the 834 * %G_APPLICATION_IS_SERVICE flag is set. This provides a "compromise" 835 * solution whereby running an application directly from the commandline 836 * will invoke it in the normal way (which can be useful for debugging) 837 * while still allowing applications to be D-Bus activated in service 838 * mode. The D-Bus service file should invoke the executable with 839 * "--gapplication-service" as the sole commandline argument. This 840 * approach is suitable for use by most graphical applications but 841 * should not be used from applications like editors that need precise 842 * control over when processes invoked via the commandline will exit and 843 * what their exit status will be. 844 * 845 * Params: 846 * argc = the argc from main() (or 0 if @argv is %NULL) 847 * argv = the argv from main(), or %NULL 848 * 849 * Return: the exit status 850 * 851 * Since: 2.28 852 */ 853 public int run(string[] argv) 854 { 855 return g_application_run(gApplication, cast(int)argv.length, Str.toStringzArray(argv)); 856 } 857 858 /** 859 * Sends a notification on behalf of @application to the desktop shell. 860 * There is no guarantee that the notification is displayed immediately, 861 * or even at all. 862 * 863 * Notifications may persist after the application exits. It will be 864 * D-Bus-activated when the notification or one of its actions is 865 * activated. 866 * 867 * Modifying @notification after this call has no effect. However, the 868 * object can be reused for a later call to this function. 869 * 870 * @id may be any string that uniquely identifies the event for the 871 * application. It does not need to be in any special format. For 872 * example, "new-message" might be appropriate for a notification about 873 * new messages. 874 * 875 * If a previous notification was sent with the same @id, it will be 876 * replaced with @notification and shown again as if it was a new 877 * notification. This works even for notifications sent from a previous 878 * execution of the application, as long as @id is the same string. 879 * 880 * @id may be %NULL, but it is impossible to replace or withdraw 881 * notifications without an id. 882 * 883 * If @notification is no longer relevant, it can be withdrawn with 884 * g_application_withdraw_notification(). 885 * 886 * Params: 887 * id = id of the notification, or %NULL 888 * notification = the #GNotification to send 889 * 890 * Since: 2.40 891 */ 892 public void sendNotification(string id, Notification notification) 893 { 894 g_application_send_notification(gApplication, Str.toStringz(id), (notification is null) ? null : notification.getNotificationStruct()); 895 } 896 897 /** 898 * This used to be how actions were associated with a #GApplication. 899 * Now there is #GActionMap for that. 900 * 901 * Deprecated: Use the #GActionMap interface instead. Never ever 902 * mix use of this API with use of #GActionMap on the same @application 903 * or things will go very badly wrong. This function is known to 904 * introduce buggy behaviour (ie: signals not emitted on changes to the 905 * action group), so you should really use #GActionMap instead. 906 * 907 * Params: 908 * actionGroup = a #GActionGroup, or %NULL 909 * 910 * Since: 2.28 911 */ 912 public void setActionGroup(ActionGroupIF actionGroup) 913 { 914 g_application_set_action_group(gApplication, (actionGroup is null) ? null : actionGroup.getActionGroupStruct()); 915 } 916 917 /** 918 * Sets the unique identifier for @application. 919 * 920 * The application id can only be modified if @application has not yet 921 * been registered. 922 * 923 * If non-%NULL, the application id must be valid. See 924 * g_application_id_is_valid(). 925 * 926 * Params: 927 * applicationId = the identifier for @application 928 * 929 * Since: 2.28 930 */ 931 public void setApplicationId(string applicationId) 932 { 933 g_application_set_application_id(gApplication, Str.toStringz(applicationId)); 934 } 935 936 /** 937 * Sets or unsets the default application for the process, as returned 938 * by g_application_get_default(). 939 * 940 * This function does not take its own reference on @application. If 941 * @application is destroyed then the default application will revert 942 * back to %NULL. 943 * 944 * Since: 2.32 945 */ 946 public void setDefault() 947 { 948 g_application_set_default(gApplication); 949 } 950 951 /** 952 * Sets the flags for @application. 953 * 954 * The flags can only be modified if @application has not yet been 955 * registered. 956 * 957 * See #GApplicationFlags. 958 * 959 * Params: 960 * flags = the flags for @application 961 * 962 * Since: 2.28 963 */ 964 public void setFlags(GApplicationFlags flags) 965 { 966 g_application_set_flags(gApplication, flags); 967 } 968 969 /** 970 * Sets the current inactivity timeout for the application. 971 * 972 * This is the amount of time (in milliseconds) after the last call to 973 * g_application_release() before the application stops running. 974 * 975 * This call has no side effects of its own. The value set here is only 976 * used for next time g_application_release() drops the use count to 977 * zero. Any timeouts currently in progress are not impacted. 978 * 979 * Params: 980 * inactivityTimeout = the timeout, in milliseconds 981 * 982 * Since: 2.28 983 */ 984 public void setInactivityTimeout(uint inactivityTimeout) 985 { 986 g_application_set_inactivity_timeout(gApplication, inactivityTimeout); 987 } 988 989 /** 990 * Sets (or unsets) the base resource path of @application. 991 * 992 * The path is used to automatically load various [application 993 * resources][gresource] such as menu layouts and action descriptions. 994 * The various types of resources will be found at fixed names relative 995 * to the given base path. 996 * 997 * By default, the resource base path is determined from the application 998 * ID by prefixing '/' and replacing each '.' with '/'. This is done at 999 * the time that the #GApplication object is constructed. Changes to 1000 * the application ID after that point will not have an impact on the 1001 * resource base path. 1002 * 1003 * As an example, if the application has an ID of "org.example.app" then 1004 * the default resource base path will be "/org/example/app". If this 1005 * is a #GtkApplication (and you have not manually changed the path) 1006 * then Gtk will then search for the menus of the application at 1007 * "/org/example/app/gtk/menus.ui". 1008 * 1009 * See #GResource for more information about adding resources to your 1010 * application. 1011 * 1012 * You can disable automatic resource loading functionality by setting 1013 * the path to %NULL. 1014 * 1015 * Changing the resource base path once the application is running is 1016 * not recommended. The point at which the resource path is consulted 1017 * for forming paths for various purposes is unspecified. 1018 * 1019 * Params: 1020 * resourcePath = the resource path to use 1021 * 1022 * Since: 2.42 1023 */ 1024 public void setResourceBasePath(string resourcePath) 1025 { 1026 g_application_set_resource_base_path(gApplication, Str.toStringz(resourcePath)); 1027 } 1028 1029 /** 1030 * Destroys a binding between @property and the busy state of 1031 * @application that was previously created with 1032 * g_application_bind_busy_property(). 1033 * 1034 * Params: 1035 * object = a #GObject 1036 * property = the name of a boolean property of @object 1037 * 1038 * Since: 2.44 1039 */ 1040 public void unbindBusyProperty(ObjectG object, string property) 1041 { 1042 g_application_unbind_busy_property(gApplication, (object is null) ? null : object.getObjectGStruct(), Str.toStringz(property)); 1043 } 1044 1045 /** 1046 * Decreases the busy count of @application. 1047 * 1048 * When the busy count reaches zero, the new state will be propagated 1049 * to other processes. 1050 * 1051 * This function must only be called to cancel the effect of a previous 1052 * call to g_application_mark_busy(). 1053 * 1054 * Since: 2.38 1055 */ 1056 public void unmarkBusy() 1057 { 1058 g_application_unmark_busy(gApplication); 1059 } 1060 1061 /** 1062 * Withdraws a notification that was sent with 1063 * g_application_send_notification(). 1064 * 1065 * This call does nothing if a notification with @id doesn't exist or 1066 * the notification was never sent. 1067 * 1068 * This function works even for notifications sent in previous 1069 * executions of this application, as long @id is the same as it was for 1070 * the sent notification. 1071 * 1072 * Note that notifications are dismissed when the user clicks on one 1073 * of the buttons in a notification or triggers its default action, so 1074 * there is no need to explicitly withdraw the notification in that case. 1075 * 1076 * Params: 1077 * id = id of a previously sent notification 1078 * 1079 * Since: 2.40 1080 */ 1081 public void withdrawNotification(string id) 1082 { 1083 g_application_withdraw_notification(gApplication, Str.toStringz(id)); 1084 } 1085 1086 int[string] connectedSignals; 1087 1088 void delegate(Application)[] onActivateListeners; 1089 /** 1090 * The ::activate signal is emitted on the primary instance when an 1091 * activation occurs. See g_application_activate(). 1092 */ 1093 void addOnActivate(void delegate(Application) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 1094 { 1095 if ( "activate" !in connectedSignals ) 1096 { 1097 Signals.connectData( 1098 this, 1099 "activate", 1100 cast(GCallback)&callBackActivate, 1101 cast(void*)this, 1102 null, 1103 connectFlags); 1104 connectedSignals["activate"] = 1; 1105 } 1106 onActivateListeners ~= dlg; 1107 } 1108 extern(C) static void callBackActivate(GApplication* applicationStruct, Application _application) 1109 { 1110 foreach ( void delegate(Application) dlg; _application.onActivateListeners ) 1111 { 1112 dlg(_application); 1113 } 1114 } 1115 1116 int delegate(ApplicationCommandLine, Application)[] onCommandLineListeners; 1117 /** 1118 * The ::command-line signal is emitted on the primary instance when 1119 * a commandline is not handled locally. See g_application_run() and 1120 * the #GApplicationCommandLine documentation for more information. 1121 * 1122 * Params: 1123 * commandLine = a #GApplicationCommandLine representing the 1124 * passed commandline 1125 * 1126 * Return: An integer that is set as the exit status for the calling 1127 * process. See g_application_command_line_set_exit_status(). 1128 */ 1129 void addOnCommandLine(int delegate(ApplicationCommandLine, Application) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 1130 { 1131 if ( "command-line" !in connectedSignals ) 1132 { 1133 Signals.connectData( 1134 this, 1135 "command-line", 1136 cast(GCallback)&callBackCommandLine, 1137 cast(void*)this, 1138 null, 1139 connectFlags); 1140 connectedSignals["command-line"] = 1; 1141 } 1142 onCommandLineListeners ~= dlg; 1143 } 1144 extern(C) static int callBackCommandLine(GApplication* applicationStruct, GApplicationCommandLine* commandLine, Application _application) 1145 { 1146 return _application.onCommandLineListeners[0](ObjectG.getDObject!(ApplicationCommandLine)(commandLine), _application); 1147 } 1148 1149 int delegate(VariantDict, Application)[] onHandleLocalOptionsListeners; 1150 /** 1151 * The ::handle-local-options signal is emitted on the local instance 1152 * after the parsing of the commandline options has occurred. 1153 * 1154 * You can add options to be recognised during commandline option 1155 * parsing using g_application_add_main_option_entries() and 1156 * g_application_add_option_group(). 1157 * 1158 * Signal handlers can inspect @options (along with values pointed to 1159 * from the @arg_data of an installed #GOptionEntrys) in order to 1160 * decide to perform certain actions, including direct local handling 1161 * (which may be useful for options like --version). 1162 * 1163 * In the event that the application is marked 1164 * %G_APPLICATION_HANDLES_COMMAND_LINE the "normal processing" will 1165 * send the @option dictionary to the primary instance where it can be 1166 * read with g_application_command_line_get_options(). The signal 1167 * handler can modify the dictionary before returning, and the 1168 * modified dictionary will be sent. 1169 * 1170 * In the event that %G_APPLICATION_HANDLES_COMMAND_LINE is not set, 1171 * "normal processing" will treat the remaining uncollected command 1172 * line arguments as filenames or URIs. If there are no arguments, 1173 * the application is activated by g_application_activate(). One or 1174 * more arguments results in a call to g_application_open(). 1175 * 1176 * If you want to handle the local commandline arguments for yourself 1177 * by converting them to calls to g_application_open() or 1178 * g_action_group_activate_action() then you must be sure to register 1179 * the application first. You should probably not call 1180 * g_application_activate() for yourself, however: just return -1 and 1181 * allow the default handler to do it for you. This will ensure that 1182 * the `--gapplication-service` switch works properly (i.e. no activation 1183 * in that case). 1184 * 1185 * Note that this signal is emitted from the default implementation of 1186 * local_command_line(). If you override that function and don't 1187 * chain up then this signal will never be emitted. 1188 * 1189 * You can override local_command_line() if you need more powerful 1190 * capabilities than what is provided here, but this should not 1191 * normally be required. 1192 * 1193 * Params: 1194 * options = the options dictionary 1195 * 1196 * Return: an exit code. If you have handled your options and want 1197 * to exit the process, return a non-negative option, 0 for success, 1198 * and a positive value for failure. To continue, return -1 to let 1199 * the default option processing continue. 1200 * 1201 * Since: 2.40 1202 */ 1203 void addOnHandleLocalOptions(int delegate(VariantDict, Application) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 1204 { 1205 if ( "handle-local-options" !in connectedSignals ) 1206 { 1207 Signals.connectData( 1208 this, 1209 "handle-local-options", 1210 cast(GCallback)&callBackHandleLocalOptions, 1211 cast(void*)this, 1212 null, 1213 connectFlags); 1214 connectedSignals["handle-local-options"] = 1; 1215 } 1216 onHandleLocalOptionsListeners ~= dlg; 1217 } 1218 extern(C) static int callBackHandleLocalOptions(GApplication* applicationStruct, GVariantDict* options, Application _application) 1219 { 1220 return _application.onHandleLocalOptionsListeners[0](new VariantDict(options), _application); 1221 } 1222 1223 void delegate(void*, int, string, Application)[] onOpenListeners; 1224 /** 1225 * The ::open signal is emitted on the primary instance when there are 1226 * files to open. See g_application_open() for more information. 1227 * 1228 * Params: 1229 * files = an array of #GFiles 1230 * nFiles = the length of @files 1231 * hint = a hint provided by the calling instance 1232 */ 1233 void addOnOpen(void delegate(void*, int, string, Application) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 1234 { 1235 if ( "open" !in connectedSignals ) 1236 { 1237 Signals.connectData( 1238 this, 1239 "open", 1240 cast(GCallback)&callBackOpen, 1241 cast(void*)this, 1242 null, 1243 connectFlags); 1244 connectedSignals["open"] = 1; 1245 } 1246 onOpenListeners ~= dlg; 1247 } 1248 extern(C) static void callBackOpen(GApplication* applicationStruct, void* files, int nFiles, char* hint, Application _application) 1249 { 1250 foreach ( void delegate(void*, int, string, Application) dlg; _application.onOpenListeners ) 1251 { 1252 dlg(files, nFiles, Str.toString(hint), _application); 1253 } 1254 } 1255 1256 void delegate(Application)[] onShutdownListeners; 1257 /** 1258 * The ::shutdown signal is emitted only on the registered primary instance 1259 * immediately after the main loop terminates. 1260 */ 1261 void addOnShutdown(void delegate(Application) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 1262 { 1263 if ( "shutdown" !in connectedSignals ) 1264 { 1265 Signals.connectData( 1266 this, 1267 "shutdown", 1268 cast(GCallback)&callBackShutdown, 1269 cast(void*)this, 1270 null, 1271 connectFlags); 1272 connectedSignals["shutdown"] = 1; 1273 } 1274 onShutdownListeners ~= dlg; 1275 } 1276 extern(C) static void callBackShutdown(GApplication* applicationStruct, Application _application) 1277 { 1278 foreach ( void delegate(Application) dlg; _application.onShutdownListeners ) 1279 { 1280 dlg(_application); 1281 } 1282 } 1283 1284 void delegate(Application)[] onStartupListeners; 1285 /** 1286 * The ::startup signal is emitted on the primary instance immediately 1287 * after registration. See g_application_register(). 1288 */ 1289 void addOnStartup(void delegate(Application) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 1290 { 1291 if ( "startup" !in connectedSignals ) 1292 { 1293 Signals.connectData( 1294 this, 1295 "startup", 1296 cast(GCallback)&callBackStartup, 1297 cast(void*)this, 1298 null, 1299 connectFlags); 1300 connectedSignals["startup"] = 1; 1301 } 1302 onStartupListeners ~= dlg; 1303 } 1304 extern(C) static void callBackStartup(GApplication* applicationStruct, Application _application) 1305 { 1306 foreach ( void delegate(Application) dlg; _application.onStartupListeners ) 1307 { 1308 dlg(_application); 1309 } 1310 } 1311 }