Copyright | Will Thompson and Iñaki García Etxebarria |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria |
Safe Haskell | Safe-Inferred |
Language | Haskell2010 |
Dialogs are a convenient way to prompt the user for a small amount of input.
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
Memory-managed wrapper type.
Instances
Eq Dialog Source # | |
GObject Dialog Source # | |
Defined in GI.Gtk.Objects.Dialog | |
ManagedPtrNewtype Dialog Source # | |
Defined in GI.Gtk.Objects.Dialog toManagedPtr :: Dialog -> ManagedPtr Dialog | |
TypedObject Dialog Source # | |
Defined in GI.Gtk.Objects.Dialog | |
HasParentTypes Dialog Source # | |
Defined in GI.Gtk.Objects.Dialog | |
IsGValue (Maybe Dialog) Source # | Convert |
Defined in GI.Gtk.Objects.Dialog gvalueGType_ :: IO GType gvalueSet_ :: Ptr GValue -> Maybe Dialog -> IO () gvalueGet_ :: Ptr GValue -> IO (Maybe Dialog) | |
type ParentTypes Dialog Source # | |
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 #
Instances
(GObject o, IsDescendantOf Dialog o) => IsDialog o Source # | |
Defined in GI.Gtk.Objects.Dialog |
Methods
Click to display all available methods, including inherited ones
Methods
actionSetEnabled, activate, activateAction, activateDefault, addActionWidget, addButton, addController, addCssClass, addMnemonicLabel, addTickCallback, allocate, 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, 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, updateProperty, updateRelation, updateState, watchClosure.
Getters
getAccessibleParent, getAccessibleRole, getAllocatedBaseline, getAllocatedHeight, getAllocatedWidth, getAllocation, getAncestor, getApplication, getAtContext, 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, getGroup, getHalign, getHandleMenubarAccel, getHasTooltip, getHeaderBar, getHeight, getHexpand, getHexpandSet, getHideOnClose, getIconName, getLastChild, getLayoutManager, 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, setHalign, setHandleMenubarAccel, setHasTooltip, setHexpand, setHexpandSet, setHideOnClose, setIconName, setLayoutManager, 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 #
:: (HasCallStack, MonadIO m, IsDialog a, IsWidget b) | |
=> a |
|
-> b |
|
-> Int32 |
|
-> 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
:: (HasCallStack, MonadIO m, IsDialog a) | |
=> a |
|
-> Text |
|
-> Int32 |
|
-> m Widget | Returns: the |
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
:: (HasCallStack, MonadIO m, IsDialog a) | |
=> a |
|
-> m Box | Returns: the content area |
Deprecated: (Since version 4.10)Use Window
instead
Returns the content area of dialog
.
getHeaderBar
:: (HasCallStack, MonadIO m, IsDialog a) | |
=> a |
|
-> 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 #
:: (HasCallStack, MonadIO m, IsDialog a, IsWidget b) | |
=> a |
|
-> b |
|
-> m Int32 | Returns: the response id of |
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 #
:: (HasCallStack, MonadIO m, IsDialog a) | |
=> a |
|
-> Int32 |
|
-> m (Maybe Widget) | Returns: the |
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
:: (HasCallStack, MonadIO m) | |
=> m Dialog | Returns: the new dialog as a |
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
:: (HasCallStack, MonadIO m, IsDialog a) | |
=> a |
|
-> Int32 |
|
-> m () |
setDefaultResponse
dialogSetDefaultResponse Source #
:: (HasCallStack, MonadIO m, IsDialog a) | |
=> a |
|
-> Int32 |
|
-> 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 #
:: (HasCallStack, MonadIO m, IsDialog a) | |
=> a |
|
-> Int32 |
|
-> Bool |
|
-> 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 #
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