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.Dialog

Contents

- Exported types
- Methods
  - addActionWidget
  - addButton
  - getContentArea
  - getHeaderBar
  - getResponseForWidget
  - getWidgetForResponse
  - new
  - response
  - setDefaultResponse
  - setResponseSensitive
- Properties
  - useHeaderBar
- Signals
  - close
  - response

Description

Dialogs are a convenient way to prompt the user for a small amount of input.

<picture> <source srcset="dialog-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkDialog" src="dialog.png"> </picture>

Typical uses are to display a message, ask a question, or anything else that does not require extensive effort on the user’s part.

The main area of a `GtkDialog` is called the "content area", and is yours to populate with widgets such a `GtkLabel` or `GtkEntry`, to present your information, questions, or tasks to the user.

In addition, dialogs allow you to add "action widgets". Most commonly, action widgets are buttons. Depending on the platform, action widgets may be presented in the header bar at the top of the window, or at the bottom of the window. To add action widgets, create your `GtkDialog` using `Dialog`.`new_with_buttons`(), or use `dialogAddButton`, `Dialog`.`add_buttons`(), or `dialogAddActionWidget`.

`GtkDialogs` uses some heuristics to decide whether to add a close button to the window decorations. If any of the action buttons use the response ID `ResponseTypeClose` or `ResponseTypeCancel`, the close button is omitted.

Clicking a button that was added as an action widget will emit the Dialog::response signal with a response ID that you specified. GTK will never assign a meaning to positive response IDs; these are entirely user-defined. But for convenience, you can use the response IDs in the `ResponseType` enumeration (these all have values less than zero). If a dialog receives a delete event, the Dialog::response signal will be emitted with the `ResponseTypeDeleteEvent` response ID.

Dialogs are created with a call to `dialogNew` or `Dialog`.`new_with_buttons`(). The latter is recommended; it allows you to set the dialog title, some convenient flags, and add buttons.

A “modal” dialog (that is, one which freezes the rest of the application from user input), can be created by calling `windowSetModal` on the dialog. When using `Dialog`.`new_with_buttons`(), you can also pass the `DialogFlagsModal` flag to make a dialog modal.

For the simple dialog in the following example, a `MessageDialog` would save some effort. But you’d need to create the dialog contents manually if you had more than a simple message in the dialog.

An example for simple `GtkDialog` usage:

### c code

    // Function to open a dialog box with a message
    void
    quick_message (GtkWindow *parent, char *message)
    {
     GtkWidget *dialog, *label, *content_area;
     GtkDialogFlags flags;

     // Create the widgets
     flags = GTK_DIALOG_DESTROY_WITH_PARENT;
     dialog = gtk_dialog_new_with_buttons ("Message",
                                           parent,
                                           flags,
                                           _("_OK"),
                                           GTK_RESPONSE_NONE,
                                           NULL);
     content_area = gtk_dialog_get_content_area (GTK_DIALOG (dialog));
     label = gtk_label_new (message);

     // Ensure that the dialog box is destroyed when the user responds

     g_signal_connect_swapped (dialog,
                               "response",
                               G_CALLBACK (gtk_window_destroy),
                               dialog);

     // Add the label, and show everything we’ve added

     gtk_box_append (GTK_BOX (content_area), label);
     gtk_widget_show (dialog);
    }

# GtkDialog as GtkBuildable

The `GtkDialog` implementation of the `GtkBuildable` interface exposes the `contentArea` as an internal child with the name “content_area”.

`GtkDialog` supports a custom `<action-widgets>` element, which can contain multiple `<action-widget>` elements. The “response” attribute specifies a numeric response, and the content of the element is the id of widget (which should be a child of the dialogs `actionArea`). To mark a response as default, set the “default” attribute of the `<action-widget>` element to true.

`GtkDialog` supports adding action widgets by specifying “action” as the “type” attribute of a `<child>` element. The widget will be added either to the action area or the headerbar of the dialog, depending on the “use-header-bar” property. The response id has to be associated with the action widget using the `<action-widgets>` element.

An example of a `GtkDialog` UI definition fragment:

### xml code

    <object class="GtkDialog" id="dialog1">
      <child type="action">
        <object class="GtkButton" id="button_cancel"/>
      </child>
      <child type="action">
        <object class="GtkButton" id="button_ok">
        </object>
      </child>
      <action-widgets>
        <action-widget response="cancel">button_cancel</action-widget>
        <action-widget response="ok" default="true">button_ok</action-widget>
      </action-widgets>
    </object>

# Accessibility

`GtkDialog` uses the `AccessibleRoleDialog` role.

Synopsis

- newtype Dialog = Dialog (ManagedPtr Dialog)
- class (GObject o, IsDescendantOf Dialog o) => IsDialog o
- toDialog :: (MonadIO m, IsDialog o) => o -> m Dialog
- dialogAddActionWidget :: (HasCallStack, MonadIO m, IsDialog a, IsWidget b) => a -> b -> Int32 -> m ()
- dialogAddButton :: (HasCallStack, MonadIO m, IsDialog a) => a -> Text -> Int32 -> m Widget
- dialogGetContentArea :: (HasCallStack, MonadIO m, IsDialog a) => a -> m Box
- dialogGetHeaderBar :: (HasCallStack, MonadIO m, IsDialog a) => a -> m HeaderBar
- dialogGetResponseForWidget :: (HasCallStack, MonadIO m, IsDialog a, IsWidget b) => a -> b -> m Int32
- dialogGetWidgetForResponse :: (HasCallStack, MonadIO m, IsDialog a) => a -> Int32 -> m (Maybe Widget)
- dialogNew :: (HasCallStack, MonadIO m) => m Dialog
- dialogResponse :: (HasCallStack, MonadIO m, IsDialog a) => a -> Int32 -> m ()
- dialogSetDefaultResponse :: (HasCallStack, MonadIO m, IsDialog a) => a -> Int32 -> m ()
- dialogSetResponseSensitive :: (HasCallStack, MonadIO m, IsDialog a) => a -> Int32 -> Bool -> m ()
- constructDialogUseHeaderBar :: (IsDialog o, MonadIO m) => Int32 -> m (GValueConstruct o)
- getDialogUseHeaderBar :: (MonadIO m, IsDialog o) => o -> m Int32
- type DialogCloseCallback = IO ()
- afterDialogClose :: (IsDialog a, MonadIO m) => a -> ((?self :: a) => DialogCloseCallback) -> m SignalHandlerId
- onDialogClose :: (IsDialog a, MonadIO m) => a -> ((?self :: a) => DialogCloseCallback) -> m SignalHandlerId
- type DialogResponseCallback = Int32 -> IO ()
- afterDialogResponse :: (IsDialog a, MonadIO m) => a -> ((?self :: a) => DialogResponseCallback) -> m SignalHandlerId
- onDialogResponse :: (IsDialog a, MonadIO m) => a -> ((?self :: a) => DialogResponseCallback) -> m SignalHandlerId

# Exported types

newtype Dialog Source #

Memory-managed wrapper type.

Constructors

Dialog (ManagedPtr Dialog) |

#### Instances

Instances details

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

class (GObject o, IsDescendantOf Dialog o) => IsDialog o Source #

Type class for types which can be safely cast to `Dialog`, for instance with `toDialog`.

#### Instances

Instances details

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

toDialog :: (MonadIO m, IsDialog o) => o -> m Dialog Source #

Cast to `Dialog`, 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

actionSetEnabled, activate, activateAction, activateDefault, addActionWidget, addButton, addController, addCssClass, addMnemonicLabel, addTickCallback, allocate, announce, bindProperty, bindPropertyFull, childFocus, close, computeBounds, computeExpand, computePoint, computeTransform, contains, createPangoContext, createPangoLayout, destroy, disposeTemplate, dragCheckThreshold, errorBell, forceFloating, freezeNotify, fullscreen, fullscreenOnMonitor, getv, grabFocus, hasCssClass, hasDefault, hasFocus, hasGroup, hasVisibleFocus, hide, inDestruction, initTemplate, insertActionGroup, insertAfter, insertBefore, isActive, isAncestor, isDrawable, isFloating, isFocus, isFullscreen, isMaximized, isSensitive, isSuspended, isVisible, keynavFailed, listMnemonicLabels, map, maximize, measure, minimize, mnemonicActivate, notify, notifyByPspec, observeChildren, observeControllers, pick, present, presentWithTime, queueAllocate, queueDraw, queueResize, realize, ref, refSink, removeController, removeCssClass, removeMnemonicLabel, removeTickCallback, resetProperty, resetRelation, resetState, response, runDispose, shouldLayout, show, sizeAllocate, snapshotChild, stealData, stealQdata, thawNotify, translateCoordinates, triggerTooltipQuery, unfullscreen, unmap, unmaximize, unminimize, unparent, unrealize, unref, unsetStateFlags, updateNextAccessibleSibling, updatePlatformState, updateProperty, updateRelation, updateState, watchClosure.

#### Getters

getAccessibleId, getAccessibleParent, getAccessibleRole, getAllocatedBaseline, getAllocatedHeight, getAllocatedWidth, getAllocation, getAncestor, getApplication, getAtContext, getBaseline, getBounds, getBuildableId, getCanFocus, getCanTarget, getChild, getChildVisible, getClipboard, getColor, getContentArea, getCssClasses, getCssName, getCursor, getData, getDecorated, getDefaultSize, getDefaultWidget, getDeletable, getDestroyWithParent, getDirection, getDisplay, getFirstAccessibleChild, getFirstChild, getFocus, getFocusChild, getFocusOnClick, getFocusVisible, getFocusable, getFontMap, getFontOptions, getFrameClock, getGravity, getGroup, getHalign, getHandleMenubarAccel, getHasTooltip, getHeaderBar, getHeight, getHexpand, getHexpandSet, getHideOnClose, getIconName, getLastChild, getLayoutManager, getLimitEvents, getMapped, getMarginBottom, getMarginEnd, getMarginStart, getMarginTop, getMnemonicsVisible, getModal, getName, getNative, getNextAccessibleSibling, getNextSibling, getOpacity, getOverflow, getPangoContext, getParent, getPlatformState, getPreferredSize, getPrevSibling, getPrimaryClipboard, getProperty, getQdata, getRealized, getReceivesDefault, getRenderer, getRequestMode, getResizable, getResponseForWidget, getRoot, getScaleFactor, getSensitive, getSettings, getSize, getSizeRequest, getStateFlags, getStyleContext, getSurface, getSurfaceTransform, getTemplateChild, getTitle, getTitlebar, getTooltipMarkup, getTooltipText, getTransientFor, getValign, getVexpand, getVexpandSet, getVisible, getWidgetForResponse, getWidth.

#### Setters

setAccessibleParent, setApplication, setCanFocus, setCanTarget, setChild, setChildVisible, setCssClasses, setCursor, setCursorFromName, setData, setDataFull, setDecorated, setDefaultResponse, setDefaultSize, setDefaultWidget, setDeletable, setDestroyWithParent, setDirection, setDisplay, setFocus, setFocusChild, setFocusOnClick, setFocusVisible, setFocusable, setFontMap, setFontOptions, setGravity, setHalign, setHandleMenubarAccel, setHasTooltip, setHexpand, setHexpandSet, setHideOnClose, setIconName, setLayoutManager, setLimitEvents, setMarginBottom, setMarginEnd, setMarginStart, setMarginTop, setMnemonicsVisible, setModal, setName, setOpacity, setOverflow, setParent, setProperty, setReceivesDefault, setResizable, setResponseSensitive, setSensitive, setSizeRequest, setStartupId, setStateFlags, setTitle, setTitlebar, setTooltipMarkup, setTooltipText, setTransientFor, setValign, setVexpand, setVexpandSet, setVisible.

## addActionWidget

dialogAddActionWidget Source #

Arguments

:: (HasCallStack, MonadIO m, IsDialog a, IsWidget b) |
=> a | `dialog`: a `GtkDialog`
-> b | `child`: an activatable widget
-> Int32 | `responseId`: response ID for `child`
-> m () |

Deprecated: (Since version 4.10)Use `Window` instead

Adds an activatable widget to the action area of a `GtkDialog`.

GTK connects a signal handler that will emit the Dialog::response signal on the dialog when the widget is activated. The widget is appended to the end of the dialog’s action area.

If you want to add a non-activatable widget, simply pack it into the `actionArea` field of the `GtkDialog` struct.

## addButton

dialogAddButton Source #

Arguments

:: (HasCallStack, MonadIO m, IsDialog a) |
=> a | `dialog`: a `GtkDialog`
-> Text | `buttonText`: text of button
-> Int32 | `responseId`: response ID for the button
-> m Widget | Returns: the `GtkButton` widget that was added

Deprecated: (Since version 4.10)Use `Window` instead

Adds a button with the given text.

GTK arranges things so that clicking the button will emit the Dialog::response signal with the given `responseId`. The button is appended to the end of the dialog’s action area. The button widget is returned, but usually you don’t need it.

## getContentArea

dialogGetContentArea Source #

Arguments

:: (HasCallStack, MonadIO m, IsDialog a) |
=> a | `dialog`: a `GtkDialog`
-> m Box | Returns: the content area `GtkBox`.

Deprecated: (Since version 4.10)Use `Window` instead

Returns the content area of `dialog`.

## getHeaderBar

dialogGetHeaderBar Source #

Arguments

:: (HasCallStack, MonadIO m, IsDialog a) |
=> a | `dialog`: a `GtkDialog`
-> m HeaderBar | Returns: the header bar

Deprecated: (Since version 4.10)Use `Window` instead

Returns the header bar of `dialog`.

Note that the headerbar is only used by the dialog if the Dialog:useHeaderBar property is `True`.

## getResponseForWidget

dialogGetResponseForWidget Source #

Arguments

:: (HasCallStack, MonadIO m, IsDialog a, IsWidget b) |
=> a | `dialog`: a `GtkDialog`
-> b | `widget`: a widget in the action area of `dialog`
-> m Int32 | Returns: the response id of `widget`, or `ResponseTypeNone` if `widget` doesn’t have a response id set.

Deprecated: (Since version 4.10)Use `Window` instead

Gets the response id of a widget in the action area of a dialog.

## getWidgetForResponse

dialogGetWidgetForResponse Source #

Arguments

:: (HasCallStack, MonadIO m, IsDialog a) |
=> a | `dialog`: a `GtkDialog`
-> Int32 | `responseId`: the response ID used by the `dialog` widget
-> m (Maybe Widget) | Returns: the `widget` button that uses the given `responseId`

Deprecated: (Since version 4.10)Use `Window` instead

Gets the widget button that uses the given response ID in the action area of a dialog.

## new

dialogNew Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> m Dialog | Returns: the new dialog as a `GtkWidget`

Deprecated: (Since version 4.10)Use `Window` instead

Creates a new dialog box.

Widgets should not be packed into the `GtkWindow` directly, but into the `contentArea` and `actionArea`, as described above.

## response

dialogResponse Source #

Arguments

:: (HasCallStack, MonadIO m, IsDialog a) |
=> a | `dialog`: a `GtkDialog`
-> Int32 | `responseId`: response ID
-> m () |

Deprecated: (Since version 4.10)Use `Window` instead

Emits the response signal with the given response ID.

Used to indicate that the user has responded to the dialog in some way.

## setDefaultResponse

dialogSetDefaultResponse Source #

Arguments

:: (HasCallStack, MonadIO m, IsDialog a) |
=> a | `dialog`: a `GtkDialog`
-> Int32 | `responseId`: a response ID
-> m () |

Deprecated: (Since version 4.10)Use `Window` instead

Sets the default widget for the dialog based on the response ID.

Pressing “Enter” normally activates the default widget.

## setResponseSensitive

dialogSetResponseSensitive Source #

Arguments

:: (HasCallStack, MonadIO m, IsDialog a) |
=> a | `dialog`: a `GtkDialog`
-> Int32 | `responseId`: a response ID
-> Bool | `setting`: `True` for sensitive
-> m () |

Deprecated: (Since version 4.10)Use `Window` instead

A convenient way to sensitize/desensitize dialog buttons.

Calls `gtk_widget_set_sensitive (widget, @setting)` for each widget in the dialog’s action area with the given `responseId`.

# Properties

## useHeaderBar

`True` if the dialog uses a headerbar for action buttons instead of the action-area.

For technical reasons, this property is declared as an integer property, but you should only set it to `True` or `False`.

## Creating a dialog with headerbar

Builtin `GtkDialog` subclasses such as `ColorChooserDialog` set this property according to platform conventions (using the Settings:gtkDialogsUseHeader setting).

Here is how you can achieve the same:

### c code

    g_object_get (settings, "gtk-dialogs-use-header", &header, NULL);
    dialog = g_object_new (GTK_TYPE_DIALOG, header, TRUE, NULL);

constructDialogUseHeaderBar :: (IsDialog o, MonadIO m) => Int32 -> m (GValueConstruct o) Source #

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

getDialogUseHeaderBar :: (MonadIO m, IsDialog o) => o -> m Int32 Source #

Get the value of the “`use-header-bar`” property. When overloading is enabled, this is equivalent to

    get dialog #useHeaderBar

# Signals

## close

type DialogCloseCallback = IO () Source #

Deprecated: (Since version 4.10)Use `Window` instead

Emitted when the user uses a keybinding to close the dialog.

This is a keybinding signal.

The default binding for this signal is the Escape key.

afterDialogClose :: (IsDialog a, MonadIO m) => a -> ((?self :: a) => DialogCloseCallback) -> m SignalHandlerId Source #

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

    after dialog #close 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.

onDialogClose :: (IsDialog a, MonadIO m) => a -> ((?self :: a) => DialogCloseCallback) -> m SignalHandlerId Source #

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

    on dialog #close callback

## response

type DialogResponseCallback Source #

Arguments

= Int32 | `responseId`: the response ID
-> IO () |

Deprecated: (Since version 4.10)Use `Window` instead

Emitted when an action widget is clicked.

The signal is also emitted when the dialog receives a delete event, and when `dialogResponse` is called. On a delete event, the response ID is `ResponseTypeDeleteEvent`. Otherwise, it depends on which action widget was clicked.

afterDialogResponse :: (IsDialog a, MonadIO m) => a -> ((?self :: a) => DialogResponseCallback) -> m SignalHandlerId Source #

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

    after dialog #response 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.

onDialogResponse :: (IsDialog a, MonadIO m) => a -> ((?self :: a) => DialogResponseCallback) -> m SignalHandlerId Source #

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

    on dialog #response callback