gi-gtk4-4.0.12: Gtk 4.x bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.Gtk.Objects.Application

Contents

- Exported types
- Methods
  - addWindow
  - getAccelsForAction
  - getActionsForAccel
  - getActiveWindow
  - getMenuById
  - getMenubar
  - getWindowById
  - getWindows
  - inhibit
  - listActionDescriptions
  - new
  - removeWindow
  - setAccelsForAction
  - setMenubar
  - uninhibit
- Properties
  - activeWindow
  - menubar
  - registerSession
  - screensaverActive
- Signals
  - queryEnd
  - windowAdded
  - windowRemoved

Description

A high-level API for writing applications.

`GtkApplication` supports many aspects of writing a GTK application in a convenient fashion, without enforcing a one-size-fits-all model.

Currently, it 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 your application.

While `GtkApplication` works fine with plain `Window`s, it is recommended to use it together with `ApplicationWindow`.

## Initialization

A typical `GtkApplication` will create a window in its `GIO.Application::activate`, `GIO.Application::open` or `GIO.Application::command-line` handlers. Note that all of these signals may be emitted multiple times, so handlers must be careful to take existing windows into account.

A typical activate handler should look like this:

    static void
    activate (GApplication *gapp)
    {
      GtkApplication *app = GTK_APPLICATION (gapp);
      GtkWindow *window;

      window = gtk_application_get_active_window (app);
      if (!window)
        window = create_window (app);

      gtk_window_present (window);
    }

## Automatic resources

`GtkApplication` will automatically load menus from the `GtkBuilder` resource located at "gtk/menus.ui", relative to the application's resource base path (see `applicationSetResourceBasePath`). The menu with the ID "menubar" is taken as the application's menubar. Additional menus (most interesting submenus) can be named and accessed via `applicationGetMenuById` which allows for dynamic population of a part of the menu structure.

Note that automatic resource loading uses the resource base path that is set at construction time and will not work if the resource base path is changed at a later time.

It is also possible to provide the menubar manually using `applicationSetMenubar`.

`GtkApplication` 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 `iconThemeAddResourcePath` for more information.

If there is a resource located at `gtk/help-overlay.ui` which defines a `ShortcutsWindow` with ID `help_overlay` then `GtkApplication` associates an instance of this shortcuts window with each `ApplicationWindow` and sets up the keyboard accelerator <kbd>Control</kbd>+<kbd>?</kbd> to open it. To create a menu item that displays the shortcuts window, associate the item with the action `win.show-help-overlay`.

`GtkApplication` will also automatically set the application id as the default window icon. Use `windowSetDefaultIconName` or Window:iconName to override that behavior.

# Inhibiting

An application can block various ways to end the session with the `applicationInhibit` 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

A simple example is available in the GTK source code repository

## See Also

- Using GtkApplication
- Getting Started with GTK: Basics

Synopsis

- newtype Application = Application (ManagedPtr Application)
- class (GObject o, IsDescendantOf Application o) => IsApplication o
- toApplication :: (MonadIO m, IsApplication o) => o -> m Application
- applicationAddWindow :: (HasCallStack, MonadIO m, IsApplication a, IsWindow b) => a -> b -> m ()
- applicationGetAccelsForAction :: (HasCallStack, MonadIO m, IsApplication a) => a -> Text -> m [Text]
- applicationGetActionsForAccel :: (HasCallStack, MonadIO m, IsApplication a) => a -> Text -> m [Text]
- applicationGetActiveWindow :: (HasCallStack, MonadIO m, IsApplication a) => a -> m (Maybe Window)
- applicationGetMenuById :: (HasCallStack, MonadIO m, IsApplication a) => a -> Text -> m (Maybe Menu)
- applicationGetMenubar :: (HasCallStack, MonadIO m, IsApplication a) => a -> m (Maybe MenuModel)
- applicationGetWindowById :: (HasCallStack, MonadIO m, IsApplication a) => a -> Word32 -> m (Maybe Window)
- applicationGetWindows :: (HasCallStack, MonadIO m, IsApplication a) => a -> m [Window]
- applicationInhibit :: (HasCallStack, MonadIO m, IsApplication a, IsWindow b) => a -> Maybe b -> [ApplicationInhibitFlags] -> Maybe Text -> m Word32
- applicationListActionDescriptions :: (HasCallStack, MonadIO m, IsApplication a) => a -> m [Text]
- applicationNew :: (HasCallStack, MonadIO m) => Maybe Text -> [ApplicationFlags] -> m Application
- applicationRemoveWindow :: (HasCallStack, MonadIO m, IsApplication a, IsWindow b) => a -> b -> m ()
- applicationSetAccelsForAction :: (HasCallStack, MonadIO m, IsApplication a) => a -> Text -> [Text] -> m ()
- applicationSetMenubar :: (HasCallStack, MonadIO m, IsApplication a, IsMenuModel b) => a -> Maybe b -> m ()
- applicationUninhibit :: (HasCallStack, MonadIO m, IsApplication a) => a -> Word32 -> m ()
- getApplicationActiveWindow :: (MonadIO m, IsApplication o) => o -> m (Maybe Window)
- clearApplicationMenubar :: (MonadIO m, IsApplication o) => o -> m ()
- constructApplicationMenubar :: (IsApplication o, MonadIO m, IsMenuModel a) => a -> m (GValueConstruct o)
- getApplicationMenubar :: (MonadIO m, IsApplication o) => o -> m (Maybe MenuModel)
- setApplicationMenubar :: (MonadIO m, IsApplication o, IsMenuModel a) => o -> a -> m ()
- constructApplicationRegisterSession :: (IsApplication o, MonadIO m) => Bool -> m (GValueConstruct o)
- getApplicationRegisterSession :: (MonadIO m, IsApplication o) => o -> m Bool
- setApplicationRegisterSession :: (MonadIO m, IsApplication o) => o -> Bool -> m ()
- getApplicationScreensaverActive :: (MonadIO m, IsApplication o) => o -> m Bool
- type ApplicationQueryEndCallback = IO ()
- afterApplicationQueryEnd :: (IsApplication a, MonadIO m) => a -> ((?self :: a) => ApplicationQueryEndCallback) -> m SignalHandlerId
- onApplicationQueryEnd :: (IsApplication a, MonadIO m) => a -> ((?self :: a) => ApplicationQueryEndCallback) -> m SignalHandlerId
- type ApplicationWindowAddedCallback = Window -> IO ()
- afterApplicationWindowAdded :: (IsApplication a, MonadIO m) => a -> ((?self :: a) => ApplicationWindowAddedCallback) -> m SignalHandlerId
- onApplicationWindowAdded :: (IsApplication a, MonadIO m) => a -> ((?self :: a) => ApplicationWindowAddedCallback) -> m SignalHandlerId
- type ApplicationWindowRemovedCallback = Window -> IO ()
- afterApplicationWindowRemoved :: (IsApplication a, MonadIO m) => a -> ((?self :: a) => ApplicationWindowRemovedCallback) -> m SignalHandlerId
- onApplicationWindowRemoved :: (IsApplication a, MonadIO m) => a -> ((?self :: a) => ApplicationWindowRemovedCallback) -> m SignalHandlerId

# Exported types

newtype Application Source #

Memory-managed wrapper type.

Constructors

Application (ManagedPtr Application) |

#### Instances

Instances details

Eq Application Source # |
Instance details Defined in GI.Gtk.Objects.Application Methods (==) :: Application -> Application -> Bool Source # (/=) :: Application -> Application -> Bool Source #
GObject Application Source # |
Instance details Defined in GI.Gtk.Objects.Application
ManagedPtrNewtype Application Source # |
Instance details Defined in GI.Gtk.Objects.Application Methods toManagedPtr :: Application -> ManagedPtr Application Source #
TypedObject Application Source # |
Instance details Defined in GI.Gtk.Objects.Application Methods glibType :: IO GType Source #
HasParentTypes Application Source # |
Instance details Defined in GI.Gtk.Objects.Application
IsGValue (Maybe Application) Source # | Convert `Application` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.Gtk.Objects.Application Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe Application -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe Application) Source #
type ParentTypes Application Source # |
Instance details Defined in GI.Gtk.Objects.Application type ParentTypes Application = '[Application, Object, ActionGroup, ActionMap]

class (GObject o, IsDescendantOf Application o) => IsApplication o Source #

Type class for types which can be safely cast to `Application`, for instance with `toApplication`.

#### Instances

Instances details

(GObject o, IsDescendantOf Application o) => IsApplication o Source # |
Instance details Defined in GI.Gtk.Objects.Application

toApplication :: (MonadIO m, IsApplication o) => o -> m Application Source #

Cast to `Application`, for types for which this is known to be safe. For general casts, use `castTo`.

# Methods

### Click to display all available methods, including inherited ones

Expand

#### Methods

actionAdded, actionEnabledChanged, actionRemoved, actionStateChanged, activate, activateAction, addAction, addActionEntries, addMainOption, addMainOptionEntries, addOptionGroup, addWindow, bindBusyProperty, bindProperty, bindPropertyFull, changeActionState, forceFloating, freezeNotify, getv, hasAction, hold, inhibit, isFloating, listActionDescriptions, listActions, lookupAction, markBusy, notify, notifyByPspec, open, queryAction, quit, ref, refSink, register, release, removeAction, removeActionEntries, removeWindow, run, runDispose, sendNotification, stealData, stealQdata, thawNotify, unbindBusyProperty, uninhibit, unmarkBusy, unref, watchClosure, withdrawNotification.

#### Getters

getAccelsForAction, getActionEnabled, getActionParameterType, getActionState, getActionStateHint, getActionStateType, getActionsForAccel, getActiveWindow, getApplicationId, getData, getDbusConnection, getDbusObjectPath, getFlags, getInactivityTimeout, getIsBusy, getIsRegistered, getIsRemote, getMenuById, getMenubar, getProperty, getQdata, getResourceBasePath, getVersion, getWindowById, getWindows.

#### Setters

setAccelsForAction, setActionGroup, setApplicationId, setData, setDataFull, setDefault, setFlags, setInactivityTimeout, setMenubar, setOptionContextDescription, setOptionContextParameterString, setOptionContextSummary, setProperty, setResourceBasePath, setVersion.

## addWindow

applicationAddWindow Source #

Arguments

:: (HasCallStack, MonadIO m, IsApplication a, IsWindow b) |
=> a | `application`: an application
-> b | `window`: a window
-> m () |

Adds a window to the application.

This call can only happen after the application has started; typically, you should add new application windows in response to the emission of the `GIO.Application::activate` signal.

This call is equivalent to setting the Window:application property of the window to `application`.

Normally, the connection between the application and the window will remain until the window is destroyed, but you can explicitly remove it with `applicationRemoveWindow`.

GTK will keep the application running as long as it has any windows.

## getAccelsForAction

applicationGetAccelsForAction Source #

Arguments

:: (HasCallStack, MonadIO m, IsApplication a) |
=> a | `application`: an application
-> Text | `detailedActionName`: a detailed action name, specifying an action and target to obtain accelerators for
-> m [Text] | Returns: accelerators for `detailedActionName`

Gets the accelerators that are currently associated with the given action.

## getActionsForAccel

applicationGetActionsForAccel Source #

Arguments

:: (HasCallStack, MonadIO m, IsApplication a) |
=> a | `application`: a application
-> Text | `accel`: an accelerator that can be parsed by `acceleratorParse`
-> m [Text] | Returns: actions for `accel`

Returns the list of actions (possibly empty) that the accelerator maps to.

Each item in the list is a detailed action name in the usual form.

This might be useful to discover if an accel already exists in order to prevent installation of a conflicting accelerator (from an accelerator editor or a plugin system, for example). Note that having more than one action per accelerator may not be a bad thing and might make sense in cases where the actions never appear in the same context.

In case there are no actions for a given accelerator, an empty array is returned. `NULL` is never returned.

It is a programmer error to pass an invalid accelerator string.

If you are unsure, check it with `acceleratorParse` first.

## getActiveWindow

applicationGetActiveWindow Source #

Arguments

:: (HasCallStack, MonadIO m, IsApplication a) |
=> a | `application`: an application
-> m (Maybe Window) | Returns: the active window

Gets the “active” window for the application.

The active window is the one that was most recently focused (within the application). This window may not have the focus at the moment if another application has it — this is just the most recently-focused window within this application.

## getMenuById

applicationGetMenuById Source #

Arguments

:: (HasCallStack, MonadIO m, IsApplication a) |
=> a | `application`: an application
-> Text | `id`: the ID of the menu to look up
-> m (Maybe Menu) | Returns: Gets the menu with the given ID from the automatically loaded resources

Gets a menu from automatically loaded resources.

See the section on Automatic resources for more information.

## getMenubar

applicationGetMenubar Source #

Arguments

:: (HasCallStack, MonadIO m, IsApplication a) |
=> a | `application`: an application
-> m (Maybe MenuModel) | Returns: the menubar for windows of the application

Returns the menu model for the menu bar of the application.

## getWindowById

applicationGetWindowById Source #

Arguments

:: (HasCallStack, MonadIO m, IsApplication a) |
=> a | `application`: an application`
-> Word32 | `id`: an identifier number
-> m (Maybe Window) | Returns: the window for the given ID

Returns the window with the given ID.

The ID of a `GtkApplicationWindow` can be retrieved with `applicationWindowGetId`.

## getWindows

applicationGetWindows Source #

Arguments

:: (HasCallStack, MonadIO m, IsApplication a) |
=> a | `application`: an application
-> m [Window] | Returns: the list of windows

Gets a list of the window associated with the application.

The list is sorted by most recently focused window, such that the first element is the currently focused window. (Useful for choosing a parent for a transient window.)

The list that is returned should not be modified in any way. It will only remain valid until the next focus change or window creation or deletion.

## inhibit

applicationInhibit Source #

Arguments

:: (HasCallStack, MonadIO m, IsApplication a, IsWindow b) |
=> a | `application`: the application
-> Maybe b | `window`: a window
-> [ApplicationInhibitFlags] | `flags`: what types of actions should be inhibited
-> Maybe Text | `reason`: a short, human-readable string that explains why these operations are inhibited
-> m Word32 | Returns: A non-zero cookie that is used to uniquely identify this, or 0 if the platform does not support inhibiting or the request failed for some reason

Informs the session manager that certain types of actions should be inhibited.

This is not guaranteed to work on all platforms and for all types of actions.

Applications should invoke this method when they begin an operation that should not be interrupted, such as creating a CD or DVD. The types of actions that may be blocked are specified by the `flags` parameter. When the application completes the operation it should call `applicationUninhibit` to remove the inhibitor. Note that an application can have multiple inhibitors, and all of them must be individually removed. Inhibitors are also cleared when the application exits.

Applications should not expect that they will always be able to block the action. In most cases, users will be given the option to force the action to take place.

The `reason` message should be short and to the point.

If a window is given, the session manager may point the user to this window to find out more about why the action is inhibited.

The cookie that is returned by this function should be used as an argument to `applicationUninhibit` in order to remove the request.

## listActionDescriptions

applicationListActionDescriptions Source #

Arguments

:: (HasCallStack, MonadIO m, IsApplication a) |
=> a | `application`: an application
-> m [Text] | Returns: the detailed action names

Lists the detailed action names which have associated accelerators.

See `applicationSetAccelsForAction`.

## new

applicationNew Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Maybe Text | `applicationId`: The application ID
-> [ApplicationFlags] | `flags`: the application flags
-> m Application | Returns: a new `GtkApplication` instance

Creates a new application instance.

When using `GtkApplication`, it is not necessary to call `init` manually. It is called as soon as the application gets registered as the primary instance.

Concretely, `init` is called in the default handler for the `GApplication::startup` signal. Therefore, `GtkApplication` subclasses should always chain up in their `GIO.Application.startup()` handler before using any GTK API.

Note that commandline arguments are not passed to `init`.

If `application_id` is not `NULL`, then it must be valid. See `applicationIdIsValid`.

If no application ID is given then some features (most notably application uniqueness) will be disabled.

## removeWindow

applicationRemoveWindow Source #

Arguments

:: (HasCallStack, MonadIO m, IsApplication a, IsWindow b) |
=> a | `application`: an application
-> b | `window`: a window
-> m () |

Remove a window from the application.

If the window belongs to the application then this call is equivalent to setting the Window:application property of the window to `NULL`.

The application may stop running as a result of a call to this function, if the window was the last window of the application.

## setAccelsForAction

applicationSetAccelsForAction Source #

Arguments

:: (HasCallStack, MonadIO m, IsApplication a) |
=> a | `application`: an application
-> Text | `detailedActionName`: a detailed action name, specifying an action and target to associate accelerators with
-> [Text] | `accels`: a list of accelerators in the format understood by `acceleratorParse`
-> m () |

Sets zero or more keyboard accelerators that will trigger the given action.

The first item in `accels` will be the primary accelerator, which may be displayed in the UI.

To remove all accelerators for an action, use an empty, zero-terminated array for `accels`.

For the `detailedActionName`, see `actionParseDetailedName` and [Gio.Action.print_detailed_name].

## setMenubar

applicationSetMenubar Source #

Arguments

:: (HasCallStack, MonadIO m, IsApplication a, IsMenuModel b) |
=> a | `application`: an application
-> Maybe b | `menubar`: a menu model
-> m () |

Sets or unsets the menubar for windows of the application.

This is a menubar in the traditional sense.

This can only be done in the primary instance of the application, after it has been registered. `GIO.Application.startup()` is a good place to call this.

Depending on the desktop environment, this may appear at the top of each window, or at the top of the screen. In some environments, if both the application menu and the menubar are set, the application menu will be presented as if it were the first item of the menubar. Other environments treat the two as completely separate — for example, the application menu may be rendered by the desktop shell while the menubar (if set) remains in each individual window.

Use the base `GActionMap` interface to add actions, to respond to the user selecting these menu items.

## uninhibit

applicationUninhibit Source #

Arguments

:: (HasCallStack, MonadIO m, IsApplication a) |
=> a | `application`: the application
-> Word32 | `cookie`: a cookie that was returned by `applicationInhibit`
-> m () |

Removes an inhibitor that has been previously established.

See `applicationInhibit`.

Inhibitors are also cleared when the application exits.

# Properties

## activeWindow

The currently focused window of the application.

getApplicationActiveWindow :: (MonadIO m, IsApplication o) => o -> m (Maybe Window) Source #

Get the value of the “`active-window`” property. When overloading is enabled, this is equivalent to

    get application #activeWindow

## menubar

The menu model to be used for the application's menu bar.

clearApplicationMenubar :: (MonadIO m, IsApplication o) => o -> m () Source #

Set the value of the “`menubar`” property to `Nothing`. When overloading is enabled, this is equivalent to

    clear #menubar

constructApplicationMenubar :: (IsApplication o, MonadIO m, IsMenuModel a) => a -> m (GValueConstruct o) Source #

Construct a `GValueConstruct` with valid value for the “`menubar`” property. This is rarely needed directly, but it is used by `new`.

getApplicationMenubar :: (MonadIO m, IsApplication o) => o -> m (Maybe MenuModel) Source #

Get the value of the “`menubar`” property. When overloading is enabled, this is equivalent to

    get application #menubar

setApplicationMenubar :: (MonadIO m, IsApplication o, IsMenuModel a) => o -> a -> m () Source #

Set the value of the “`menubar`” property. When overloading is enabled, this is equivalent to

    set application [ #menubar := value ]

## registerSession

Set this property to true to register with the session manager.

This will make GTK track the session state (such as the Application:screensaverActive property).

constructApplicationRegisterSession :: (IsApplication o, MonadIO m) => Bool -> m (GValueConstruct o) Source #

Construct a `GValueConstruct` with valid value for the “`register-session`” property. This is rarely needed directly, but it is used by `new`.

getApplicationRegisterSession :: (MonadIO m, IsApplication o) => o -> m Bool Source #

Get the value of the “`register-session`” property. When overloading is enabled, this is equivalent to

    get application #registerSession

setApplicationRegisterSession :: (MonadIO m, IsApplication o) => o -> Bool -> m () Source #

Set the value of the “`register-session`” property. When overloading is enabled, this is equivalent to

    set application [ #registerSession := value ]

## screensaverActive

This property is true if GTK believes that the screensaver is currently active.

Tracking the screensaver state is currently only supported on Linux.

getApplicationScreensaverActive :: (MonadIO m, IsApplication o) => o -> m Bool Source #

Get the value of the “`screensaver-active`” property. When overloading is enabled, this is equivalent to

    get application #screensaverActive

# Signals

## queryEnd

type ApplicationQueryEndCallback = IO () Source #

Emitted when the session manager is about to end the session.

Applications can connect to this signal and call `applicationInhibit` with [flags`gtk`.ApplicationInhibitFlags.logout] to delay the end of the session until state has been saved.

afterApplicationQueryEnd :: (IsApplication a, MonadIO m) => a -> ((?self :: a) => ApplicationQueryEndCallback) -> m SignalHandlerId Source #

Connect a signal handler for the queryEnd signal, to be run after the default handler. When overloading is enabled, this is equivalent to

    after application #queryEnd callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit `?self` parameter. Note that this requires activating the `ImplicitParams` GHC extension.

onApplicationQueryEnd :: (IsApplication a, MonadIO m) => a -> ((?self :: a) => ApplicationQueryEndCallback) -> m SignalHandlerId Source #

Connect a signal handler for the queryEnd signal, to be run before the default handler. When overloading is enabled, this is equivalent to

    on application #queryEnd callback

## windowAdded

type ApplicationWindowAddedCallback Source #

Arguments

= Window | `window`: the newly-added window
-> IO () |

Emitted when a window is added to an application.

See `applicationAddWindow`.

afterApplicationWindowAdded :: (IsApplication a, MonadIO m) => a -> ((?self :: a) => ApplicationWindowAddedCallback) -> m SignalHandlerId Source #

Connect a signal handler for the windowAdded signal, to be run after the default handler. When overloading is enabled, this is equivalent to

    after application #windowAdded callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit `?self` parameter. Note that this requires activating the `ImplicitParams` GHC extension.

onApplicationWindowAdded :: (IsApplication a, MonadIO m) => a -> ((?self :: a) => ApplicationWindowAddedCallback) -> m SignalHandlerId Source #

Connect a signal handler for the windowAdded signal, to be run before the default handler. When overloading is enabled, this is equivalent to

    on application #windowAdded callback

## windowRemoved

type ApplicationWindowRemovedCallback Source #

Arguments

= Window | `window`: the window that is being removed
-> IO () |

Emitted when a window is removed from an application.

This can happen as a side-effect of the window being destroyed or explicitly through `applicationRemoveWindow`.

afterApplicationWindowRemoved :: (IsApplication a, MonadIO m) => a -> ((?self :: a) => ApplicationWindowRemovedCallback) -> m SignalHandlerId Source #

Connect a signal handler for the windowRemoved signal, to be run after the default handler. When overloading is enabled, this is equivalent to

    after application #windowRemoved callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit `?self` parameter. Note that this requires activating the `ImplicitParams` GHC extension.

onApplicationWindowRemoved :: (IsApplication a, MonadIO m) => a -> ((?self :: a) => ApplicationWindowRemovedCallback) -> m SignalHandlerId Source #

Connect a signal handler for the windowRemoved signal, to be run before the default handler. When overloading is enabled, this is equivalent to

    on application #windowRemoved callback