Copyright | Will Thompson Iñaki García Etxebarria and Jonas Platte |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria |
Safe Haskell | None |
Language | Haskell2010 |
Dialog boxes 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.
GTK+ treats a dialog as a window split vertically. The top section is a
Box
, and is where widgets such as a Label
or a Entry
should
be packed. The bottom area is known as the
“action area”. This is generally used for
packing buttons into the dialog which may perform functions such as
cancel, ok, or apply.
Dialog
boxes 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.
If you add buttons to Dialog
using gtk_dialog_new_with_buttons()
,
dialogAddButton
, gtk_dialog_add_buttons()
, or
dialogAddActionWidget
, clicking the button will emit a signal
called response 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 a response ID of GTK_RESPONSE_DELETE_EVENT
.
For the simple dialog in the following example, in reality you’d probably
use MessageDialog
to save yourself 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, gchar *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
and actionArea
as internal children with the names
“content_area” and “action_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
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 # | |
IsGValue Dialog Source # | Convert |
ManagedPtrNewtype Dialog Source # | |
Defined in GI.Gtk.Objects.Dialog toManagedPtr :: Dialog -> ManagedPtr Dialog # | |
TypedObject Dialog Source # | |
Defined in GI.Gtk.Objects.Dialog | |
GObject Dialog Source # | |
Defined in GI.Gtk.Objects.Dialog | |
HasParentTypes Dialog Source # | |
Defined in GI.Gtk.Objects.Dialog | |
type ParentTypes Dialog Source # | |
Defined in GI.Gtk.Objects.Dialog type ParentTypes Dialog = '[Window, Widget, Object, ImplementorIface, 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
Overloaded methods
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 |
Returns the header bar of dialog
. Note that the
headerbar is only used by the dialog if the
Dialog
:use-header-bar
property is True
.
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][GtkBindingSignal] 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