Copyright | Will Thompson Iñaki García Etxebarria and Jonas Platte |
---|---|
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, e.g. 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 Label
or Entry
, 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, use GtkDialog using gtk_dialog_new_with_buttons()
,
dialogAddButton
, gtk_dialog_add_buttons()
, or
dialogAddActionWidget
.
Clicking a button that was added as an action widget will emit the
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
response signal will be emitted with the
GTK_RESPONSE_DELETE_EVENT
response ID.
Dialogs are created with a call to dialogNew
or
gtk_dialog_new_with_buttons()
. gtk_dialog_new_with_buttons()
is
recommended; it allows you to set the dialog title, some convenient
flags, and add simple 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. Use the GTK_WINDOW()
macro to cast the widget returned from
dialogNew
into a Window
. When using gtk_dialog_new_with_buttons()
you can also pass the GTK_DIALOG_MODAL
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 Buildable
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 Dialog
UI definition fragment:
>
>class="GtkDialog" id="dialog1"
> type="action"
> class="GtkButton" id="button_cancel"/
> /child
> type="action"
> class="GtkButton" id="button_ok"
> /object
> /child
> action-widgets
> response="cancel"button_cancel/action-widget
> response="ok" default="true"button_ok/action-widget
> /action-widgets
>/object
Accessibility
GtkDialog uses the GTK_ACCESSIBLE_ROLE_DIALOG
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 C_DialogCloseCallback = Ptr () -> Ptr () -> IO ()
- type DialogCloseCallback = IO ()
- afterDialogClose :: (IsDialog a, MonadIO m) => a -> DialogCloseCallback -> m SignalHandlerId
- genClosure_DialogClose :: MonadIO m => DialogCloseCallback -> m (GClosure C_DialogCloseCallback)
- mk_DialogCloseCallback :: C_DialogCloseCallback -> IO (FunPtr C_DialogCloseCallback)
- noDialogCloseCallback :: Maybe DialogCloseCallback
- onDialogClose :: (IsDialog a, MonadIO m) => a -> DialogCloseCallback -> m SignalHandlerId
- wrap_DialogCloseCallback :: DialogCloseCallback -> C_DialogCloseCallback
- type C_DialogResponseCallback = Ptr () -> Int32 -> Ptr () -> IO ()
- type DialogResponseCallback = Int32 -> IO ()
- afterDialogResponse :: (IsDialog a, MonadIO m) => a -> DialogResponseCallback -> m SignalHandlerId
- genClosure_DialogResponse :: MonadIO m => DialogResponseCallback -> m (GClosure C_DialogResponseCallback)
- mk_DialogResponseCallback :: C_DialogResponseCallback -> IO (FunPtr C_DialogResponseCallback)
- noDialogResponseCallback :: Maybe DialogResponseCallback
- onDialogResponse :: (IsDialog a, MonadIO m) => a -> DialogResponseCallback -> m SignalHandlerId
- wrap_DialogResponseCallback :: DialogResponseCallback -> C_DialogResponseCallback
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, 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, updateProperty, updateRelation, updateState, watchClosure.
Getters
getAccessibleRole, getAllocatedBaseline, getAllocatedHeight, getAllocatedWidth, getAllocation, getAncestor, getApplication, getBuildableId, getCanFocus, getCanTarget, getChild, getChildVisible, getClipboard, getContentArea, getCssClasses, getCssName, getCursor, getData, getDecorated, getDefaultSize, getDefaultWidget, getDeletable, getDestroyWithParent, getDirection, getDisplay, getFirstChild, getFocus, getFocusChild, getFocusOnClick, getFocusVisible, getFocusable, getFontMap, getFontOptions, getFrameClock, getGroup, getHalign, getHasTooltip, getHeaderBar, getHeight, getHexpand, getHexpandSet, getHideOnClose, getIconName, getLastChild, getLayoutManager, getMapped, getMarginBottom, getMarginEnd, getMarginStart, getMarginTop, getMnemonicsVisible, getModal, getName, getNative, getNextSibling, getOpacity, getOverflow, getPangoContext, getParent, 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
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, 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 () |
Adds an activatable widget to the action area of a Dialog
,
connecting a signal handler that will emit the 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 Dialog
struct.
addButton
:: (HasCallStack, MonadIO m, IsDialog a) | |
=> a |
|
-> Text |
|
-> Int32 |
|
-> m Widget | Returns: the |
Adds a button with the given text and sets things up so that
clicking the button will emit the 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
Returns the content area of dialog
.
getHeaderBar
:: (HasCallStack, MonadIO m, IsDialog a) | |
=> a |
|
-> m HeaderBar | Returns: the header bar |
getResponseForWidget
dialogGetResponseForWidget Source #
:: (HasCallStack, MonadIO m, IsDialog a, IsWidget b) | |
=> a |
|
-> b |
|
-> m Int32 | Returns: the response id of |
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 |
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 |
Creates a new dialog box.
Widgets should not be packed into this Window
directly, but into the contentArea
and actionArea
, as described above.
response
:: (HasCallStack, MonadIO m, IsDialog a) | |
=> a |
|
-> Int32 |
|
-> m () |
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 #
:: (HasCallStack, MonadIO m, IsDialog a) | |
=> a |
|
-> Int32 |
|
-> m () |
Sets the last widget in the dialog’s action area with the given responseId
as the default widget for the dialog. Pressing “Enter” normally activates
the default widget.
setResponseSensitive
dialogSetResponseSensitive Source #
:: (HasCallStack, MonadIO m, IsDialog a) | |
=> a |
|
-> Int32 |
|
-> Bool |
|
-> m () |
Calls gtk_widget_set_sensitive (widget, @setting)
for each widget in the dialog’s action area with the given responseId
.
A convenient way to sensitize/desensitize dialog buttons.
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
.
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 C_DialogCloseCallback = Ptr () -> Ptr () -> IO () Source #
Type for the callback on the (unwrapped) C side.
type DialogCloseCallback = IO () Source #
The close signal is a [keybinding signal][GtkSignalAction] which gets emitted when the user uses a keybinding to close the dialog.
The default binding for this signal is the Escape key.
afterDialogClose :: (IsDialog a, MonadIO m) => 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
genClosure_DialogClose :: MonadIO m => DialogCloseCallback -> m (GClosure C_DialogCloseCallback) Source #
Wrap the callback into a GClosure
.
mk_DialogCloseCallback :: C_DialogCloseCallback -> IO (FunPtr C_DialogCloseCallback) Source #
Generate a function pointer callable from C code, from a C_DialogCloseCallback
.
noDialogCloseCallback :: Maybe DialogCloseCallback Source #
A convenience synonym for
.Nothing
:: Maybe
DialogCloseCallback
onDialogClose :: (IsDialog a, MonadIO m) => 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
wrap_DialogCloseCallback :: DialogCloseCallback -> C_DialogCloseCallback Source #
Wrap a DialogCloseCallback
into a C_DialogCloseCallback
.
response
type C_DialogResponseCallback = Ptr () -> Int32 -> Ptr () -> IO () Source #
Type for the callback on the (unwrapped) C side.
type DialogResponseCallback Source #
Emitted when an action widget is clicked, the dialog receives a
delete event, or the application programmer calls dialogResponse
.
On a delete event, the response ID is GTK_RESPONSE_DELETE_EVENT
.
Otherwise, it depends on which action widget was clicked.
afterDialogResponse :: (IsDialog a, MonadIO m) => 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
genClosure_DialogResponse :: MonadIO m => DialogResponseCallback -> m (GClosure C_DialogResponseCallback) Source #
Wrap the callback into a GClosure
.
mk_DialogResponseCallback :: C_DialogResponseCallback -> IO (FunPtr C_DialogResponseCallback) Source #
Generate a function pointer callable from C code, from a C_DialogResponseCallback
.
noDialogResponseCallback :: Maybe DialogResponseCallback Source #
A convenience synonym for
.Nothing
:: Maybe
DialogResponseCallback
onDialogResponse :: (IsDialog a, MonadIO m) => 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