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

None

The gtk:application class is a high-level API for writing applications. It supports many 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.

Automatic resources

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 "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. It is also possible to provide the menubar manually using the gtk:application-menubar function.

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 menu 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
                            :flags :default-flags
                            :application-id "com.crategus.application-simple")))
    ;; Connect signal "activate" to the application
    (g:signal-connect app "activate"
        (lambda (application)
          (g:application-hold application)
          ;; Create an application window
          (let ((window (make-instance 'gtk:application-window
                                       :application application
                                       :title "Simple Application"
                                       :default-width 480
                                       :default-height 300)))
            ;; Present the application window
            (gtk:window-present window)
            (g:application-release application))))
  ;; Run the application
  (g:application-run app argv)))    

A resource definition with menus, a shortcuts window and an icon for automatically loading resources:

<?xml version="1.0" encoding="UTF-8"?>
<gresources>
  <gresource prefix="/com/crategus/application/gtk">
    <file>menus.ui</file>
    <file>help-overlay.ui</file>
  </gresource>
  <gresource prefix="/com/crategus/application/icons">
    <file>my-gtk-logo.png</file>
  </gresource>
</gresources>    

The application that automatically loads the resources:

(defun application-resources (&rest argv)
  ;; Register the resources
  (g:with-resource (resource (glib-sys:check-and-create-resources
                                     "gtk4-application.xml"
                                     :package "gtk4-application"
                                     :sourcedir "resource/"))
    (let (;; Create an application
          (app (make-instance 'gtk:application
                               :flags :default-flags
                               :application-id
                               "com.crategus.application")))
      ;; Connect "activate" signal
      (g:signal-connect app "activate"
          (lambda (application)
            (g:application-hold application)
            ;; Create an application window
            (let (;; Define action entries for the menu items
                  (entries '(("about")))
                  (accels '("win-show-help-overlay" "F1"
                            "win.about" "<Control>A"))
                  (window (make-instance 'gtk:application-window
                                         :application application
                                         :title "Application Resources"
                                         :show-menubar t
                                         :icon-name "gtk-logo"
                                         :default-width 480
                                         :default-height 300)))
              ;; Add accelerators for the application
              (iter (for (name accel) on accels by #'cddr)
                    (setf (gtk:application-accels-for-action application name)
                          accel))
              ;; Add the action entries to the application window
              (g:action-map-add-action-entries window entries)
              ;; Present the window
              (gtk:window-present window)
              (g:application-release application))))
      ;; Run the application
      (g:application-run app argv))))    

The "query-end" signal

lambda (application)    :run-first      

application

The gtk:application instance which emitted the signal.

Emitted when the session manager is about to end the session. This signal is only emitted 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.

The "window-added" signal

lambda (application window)    :run-first      

application

The gtk:application instance which emitted the signal.

window

The newly added gtk:window widget.

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

The "window-removed" signal

lambda (application window)    :run-first      

application

The gtk:application instance which emitted the signal.

window

The gtk:window widget that is being removed.

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