g-application, g-action-group, g-action-map, g-object, common-lisp:standard-object, common-lisp:t

None

The gtk-application class handles many important aspects of a GTK application in a convenient fashion, without enforcing a one-size-fits-all application model.

Currently, the gtk-application class handles GTK initialization, application uniqueness, session management, provides some basic scriptability and desktop shell integration by exporting actions and menus and manages a list of toplevel windows whose life cycle is automatically tied to the life cycle of the application.

While the gtk-application class works fine with plain gtk-window widgets, it is recommended to use it together with gtk-application-window widgets.

When GDK threads are enabled, the gtk-application instance will acquire the GDK lock when invoking actions that arrive from other processes. The GDK lock is not touched for local action invocations. In order to have actions invoked in a predictable context it is therefore recommended that the GDK lock be held while invoking actions locally with the g-action-group-activate-action function. The same applies to actions associated with gtk-application-window widgets and to the "activate" and "open" signals of the g-application class.

The gtk-application instance will automatically load menus from the gtk-builder resource located at "gtk/menus.ui", relative to the resource base path of the application, see the g-application-resource-base-path function. The menu with the ID "app-menu" is taken as the application menu of the application and the menu with the ID "menubar" is taken as the menubar of the application. Additional menus, most interesting submenus, can be named and accessed via the gtk-application-menu-by-id function which allows for dynamic population of a part of the menu structure.

If the resources "gtk/menus-appmenu.ui" or "gtk/menus-traditional.ui" are present then these files will be used in preference, depending on the value of the gtk-application-prefers-app-menu function. If the resource "gtk/menus-common.ui" is present it will be loaded as well. This is useful for storing items that are referenced from both "gtk/menus-appmenu.ui" and "gtk/menus-traditional.ui".

It is also possible to provide the menus manually using the gtk-application-app-menu and gtk-application-menubar slot access functions.

The gtk-application instance will also automatically setup an icon search path for the default icon theme by appending "icons" to the resource base path. This allows your application to easily store its icons as resources. See the gtk-icon-theme-add-resource-path function for more information.

If there is a resource located at "gtk/help-overlay.ui" which defines a gtk-shortcuts-window widget with ID "help_overlay" then the gtk-application instance associates an instance of this shortcuts window with each gtk-application-window widget and sets up keyboard accelerators, Control-F1 and Control-?, to open it. To create a menu item that displays the shortcuts window, associate the item with the "win.show-help-overlay" action.

The gtk-application instance optionally registers with a session manager of the users session, if you set the register-session property, and offers various functionality related to the session life cycle.

An application can block various ways to end the session with the gtk-application-inhibit function. Typical use cases for this kind of inhibiting are long-running, uninterruptible operations, such as burning a CD or performing a disk backup. The session manager may not honor the inhibitor, but it can be expected to inform the user about the negative consequences of ending the session while inhibitors are present. A simple application.

(defun application-simple (&rest argv)
  (let (;; Create an application
        (app (make-instance 'gtk-application
                            :application-id "com.crategus.application-simple"
                            :flags :none)))
    ;; Connect signal "activate" to the application
    (g-signal-connect app "activate"
        (lambda (application)
          ;; Create an application window
          (let ((window (make-instance 'gtk-application-window
                                       :application application
                                       :title "Simple Application"
                                       :default-width 500
                                       :default-height 300)))
            ;; Show the application window
            (gtk-widget-show-all window))))
    ;; Run the application
    (g-application-run app argv)))    

The "query-end" signal

 lambda (application)    :run-first      

Emitted when the session manager is about to end the session, only if the register-session property is true. Applications can connect to this signal and call the gtk-application-inhibit function with the :logout value of the gtk-application-inhibit-flags flags to delay the end of the session until the state has been saved. Since 3.24

application

The gtk-application instance which emitted the signal.

The "window-added" signal

 lambda (application window)    :run-first      

Emitted when a gtk-window widget is added to the application through the gtk-application-add-window function.

application

The gtk-application instance which emitted the signal.

window

The newly added gtk-window widget.

The "window-removed" signal

 lambda (application window)    :run-first      

Emitted when a gtk-window widget is removed from the application, either as a side-effect of being destroyed or explicitly through the gtk-application-remove-window function.

application

The gtk-application instance which emitted the signal.

window

The gtk-window widget that is being removed.