Gnome::Gtk4::Dialog
#------------------------------------------------------------------------------- #--[Class Description]---------------------------------------------------------- #-------------------------------------------------------------------------------
Description
Dialogs are a convenient way to prompt the user for a small amount of input.
=for image :src<asset_files/images/dialog.png> :width<30%> :class<inline>
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 Gnome::Gtk4::Dialog is called the "content area", and is yours to populate with widgets such a Gnome::Gtk4::Label or Gnome::Gtk4::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, create your Gnome::Gtk4::Dialog using .new-with-buttons(), or use .add-button(), .add-buttons(), or .add-action-widget().
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 GTK_RESPONSE_CLOSE or GTK_RESPONSE_CANCEL, the
close button is omitted.
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 enumeration ResponseType from Gnome::Gtk4::T-dialog 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 .newdialog() or .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 .set-modal() in class Window
on the dialog. When using .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 Gnome::Gtk4::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 Gnome::Gtk4::Dialog usage:
GtkDialog as GtkBuildable
The Gnome::Gtk4::Dialog implementation of the Gnome::Gtk4::R-Buildable interface exposes the $content-area as an internal child with the name “content_area”.
Gnome::Gtk4::Dialog 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 $action-area). To mark a response
as default, set the “default” attribute of the `<action-widget>` element
to true.
Gnome::Gtk4::Dialog 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 Gnome::Gtk4::Dialog UI definition fragment:
Accessibility
Gnome::Gtk4::Dialog uses the GTK_ACCESSIBLE_ROLE_DIALOG role.
Uml Diagram =for image :src<asset_files/images/plantuml/Dialog.png> :width<70%> :class<inline>
#------------------------------------------------------------------------------- #--[Class Initialization]------------------------------------------------------- #-------------------------------------------------------------------------------
Class initialization
Note: The native version of this class is deprecated in gtk4-lib() since version 4.10
new
:native-object
Create an object using a native object from an object of the same type found elsewhere. See also Gnome::N::TopLevelSupportClass.
multi method new ( N-Object() :$native-object! )
#-------------------------------------------------------------------------------
new-dialog
Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10
Creates a new dialog box.
Widgets should not be packed into the Gnome::Gtk4::Window
directly, but into the $content-area and $action-area,
as described above.
method new-dialog ( --> Gnome::Gtk4::Dialog )
#-------------------------------------------------------------------------------
new-with-buttons
Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10
Creates a new Gnome::Gtk4::Dialog with the given title and transient parent.
The $flags argument can be used to make the dialog modal, have it
destroyed along with its transient parent, or make it use a headerbar.
Button text/response ID pairs should be listed in pairs, with a undefined
pointer ending the list. Button text can be arbitrary text. A response
ID can be any positive number, or one of the values in the
enumeration ResponseType from Gnome::Gtk4::T-dialog enumeration. If the user clicks one of these
buttons, Gnome::Gtk4::Dialog will emit the response signal
with the corresponding response ID.
If a Gnome::Gtk4::Dialog receives a delete event, it will emit response with a
response ID of GTK_RESPONSE_DELETE_EVENT.
However, destroying a dialog does not emit the response signal;
so be careful relying on response when using the
GTK_DIALOG_DESTROY_WITH_PARENT flag.
Here’s a simple example:
method new-with-buttons ( Str $title, N-Object() $parent, UInt $flags, Str $first-button-text, … --> Gnome::Gtk4::Dialog )
$title; Title of the dialog.
$parent; Transient parent of the dialog.
$flags; from
bit field GtkDialogFlags defined in Gnome::Gtk4::T-dialog.$first-button-text; text to go in first button.
…; …. Note that each argument must be specified as a type followed by its value!
#------------------------------------------------------------------------------- #--[Methods]-------------------------------------------------------------------- #-------------------------------------------------------------------------------
Methods
#-------------------------------------------------------------------------------
add-action-widget
Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10
Adds an activatable widget to the action area of a Gnome::Gtk4::Dialog.
GTK connects 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 $action-area field of the Gnome::Gtk4::Dialog struct.
method add-action-widget ( N-Object() $child, Int() $response-id )
$child; an activatable widget.
$response-id; response ID for
$child.
#-------------------------------------------------------------------------------
add-button
Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10
Adds a button with the given text.
GTK arranges things so that clicking the button will emit the
response signal with the given $response-id.
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.
method add-button ( Str $button-text, Int() $response-id --> N-Object )
$button-text; text of button.
$response-id; response ID for the button.
Return value; the Gnome::Gtk4::Button widget that was added.
#-------------------------------------------------------------------------------
add-buttons
Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10
Adds multiple buttons.
This is the same as calling .add-button() repeatedly. The variable argument list should be undefined-terminated as with .new-with-buttons(). Each button must have both text and response ID.
method add-buttons ( Str $first-button-text, … )
$first-button-text; button text.
…; …. Note that each argument must be specified as a type followed by its value!
#-------------------------------------------------------------------------------
get-content-area
Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10
Returns the content area of $dialog.
method get-content-area (--> N-Object )
Return value; the content area Gnome::Gtk4::Box..
#-------------------------------------------------------------------------------
get-header-bar
Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10
Returns the header bar of $dialog.
Note that the headerbar is only used by the dialog if the
use-header-bar property is True.
method get-header-bar (--> N-Object )
Return value; the header bar.
#-------------------------------------------------------------------------------
get-response-for-widget
Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10
Gets the response id of a widget in the action area of a dialog.
method get-response-for-widget ( N-Object() $widget --> Int )
$widget; a widget in the action area of
$dialog.
Return value; the response id of $widget, or GTK_RESPONSE_NONE
if $widget doesn’t have a response id set..
#-------------------------------------------------------------------------------
get-widget-for-response
Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10
Gets the widget button that uses the given response ID in the action area of a dialog.
method get-widget-for-response ( Int() $response-id --> N-Object )
$response-id; the response ID used by the
$dialogwidget.
Return value; the $widget button that uses the given
$response-id.
#-------------------------------------------------------------------------------
response
Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10
Emits the response signal with the given response ID.
Used to indicate that the user has responded to the dialog in some way.
method response ( Int() $response-id )
$response-id; response ID.
#-------------------------------------------------------------------------------
set-default-response
Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10
Sets the default widget for the dialog based on the response ID.
Pressing “Enter” normally activates the default widget.
method set-default-response ( Int() $response-id )
$response-id; a response ID.
#-------------------------------------------------------------------------------
set-response-sensitive
Note: The native version of this routine is deprecated in gtk4-lib() since version 4.10
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 $response-id.
method set-response-sensitive ( Int() $response-id, Bool() $setting )
$response-id; a response ID.
$setting;
Truefor sensitive.
#------------------------------------------------------------------------------- #--[Signal Documentation]------------------------------------------------------- #-------------------------------------------------------------------------------
Signals
close
Emitted when the user uses a keybinding to close the dialog.
This is a [keybinding signal](class.SignalAction.html).
The default binding for this signal is the Escape key.
method handler (
Int :$_handle_id,
N-GObject :$_native-object,
Gnome::Gtk4::Dialog :$_widget,
*%user-options
)
$_handle_id; The registered event handler id.
$_native-object; The native object provided by the Raku object which registered this event. This is a native Gnome::Gtk4::Dialog object.
%user-options; A list of named arguments provided by .register-signal() in class Object.
response
Emitted when an action widget is clicked.
The signal is also emitted when the dialog receives a
delete event, and when .response() is called.
On a delete event, the response ID is GTK_RESPONSE_DELETE_EVENT.
Otherwise, it depends on which action widget was clicked.
method handler (
gint $response-id,
Int :$_handle_id,
N-GObject :$_native-object,
Gnome::Gtk4::Dialog :$_widget,
*%user-options
)
$response-id; the response ID.
$_handle_id; The registered event handler id.
$_native-object; The native object provided by the Raku object which registered this event. This is a native Gnome::Gtk4::Dialog object.
%user-options; A list of named arguments provided by .register-signal() in class Object.