-----------------------------------------------------------------------
-- GtkAda - Ada95 binding for Gtk+/Gnome --
-- --
-- Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet --
-- Copyright (C) 2000-2011, AdaCore --
-- --
-- This library is free software; you can redistribute it and/or --
-- modify it under the terms of the GNU General Public --
-- License as published by the Free Software Foundation; either --
-- version 2 of the License, or (at your option) any later version. --
-- --
-- This library is distributed in the hope that it will be useful, --
-- but WITHOUT ANY WARRANTY; without even the implied warranty of --
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU --
-- General Public License for more details. --
-- --
-- You should have received a copy of the GNU General Public --
-- License along with this library; if not, write to the --
-- Free Software Foundation, Inc., 59 Temple Place - Suite 330, --
-- Boston, MA 02111-1307, USA. --
-- --
-- --
-- --
-- --
-- --
-- --
-- --
-----------------------------------------------------------------------
--
-- Dialog boxes are a convenient way to prompt the user for a small amount of
-- input, eg. to display a message, ask a question, or anything else that does
-- not require extensive effort on the user's part.
--
-- Gtkada treats a dialog as a window split horizontally. The top section is
-- a Gtk_Vbox, and is where widgets such as a Gtk_Label or a Gtk_Entry should
-- be packed. The second 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. The two areas are separated by a Gtk_Hseparator.
--
-- If 'dialog' is a newly created dialog, the two primary areas of the window
-- can be accessed using Get_Vbox and Get_Action_Area as can be seen from the
-- example, below.
--
-- A 'modal' dialog (that is, one which freezes the rest of the application
-- from user input), can be created by calling Set_Modal on the dialog.
--
-- See Gtkada.Dialogs for a higher level dialog interface.
--
--
-- gtk-dialog
-- Windows
-- create_dialog.adb
pragma Warnings (Off, "*is already use-visible*");
with Glib; use Glib;
with Glib.Properties; use Glib.Properties;
with Glib.Types; use Glib.Types;
with Gtk.Box; use Gtk.Box;
with Gtk.Buildable; use Gtk.Buildable;
with Gtk.Widget; use Gtk.Widget;
with Gtk.Window; use Gtk.Window;
package Gtk.Dialog is
type Gtk_Dialog_Record is new Gtk_Window_Record with null record;
type Gtk_Dialog is access all Gtk_Dialog_Record'Class;
type Gtk_Dialog_Flags is mod 8;
for Gtk_Dialog_Flags'Size use Gint'Size;
pragma Convention (C, Gtk_Dialog_Flags);
Modal : constant Gtk_Dialog_Flags := 2 ** 0;
Destroy_With_Parent : constant Gtk_Dialog_Flags := 2 ** 1;
No_Separator : constant Gtk_Dialog_Flags := 2 ** 2;
-- Various flags that can be set for the dialog, with the following
-- implications:
-- - Modal : the dialog is modal, see Gtk.Window.Set_Modal
-- - Destroy_With_Parent: The dialog is destroyed if its parent is
-- destroyed. See Gtk.Window.Set_Destroy_With_Parent
-- - No_Separator: No separator bar above the buttons.
type Gtk_Response_Type is new Gint;
-- Type used for Response_Id's.
-- Positive values are totally user-interpreted.
-- GtkAda will sometimes return Gtk_Response_None if no Response_Id is
-- available.
--
-- Typical usage is:
-- if Gtk.Dialog.Run (Dialog) = Gtk_Response_Accept then
-- blah;
-- end if;
Gtk_Response_None : constant Gtk_Response_Type := -1;
-- GtkAda returns this if a response widget has no Response_Id,
-- or if the dialog gets programmatically hidden or destroyed.
Gtk_Response_Reject : constant Gtk_Response_Type := -2;
Gtk_Response_Accept : constant Gtk_Response_Type := -3;
-- GtkAda won't return these unless you pass them in
-- as the response for an action widget. They are
-- for your convenience.
Gtk_Response_Delete_Event : constant Gtk_Response_Type := -4;
-- If the dialog is deleted through the button in the titlebar
Gtk_Response_OK : constant Gtk_Response_Type := -5;
Gtk_Response_Cancel : constant Gtk_Response_Type := -6;
Gtk_Response_Close : constant Gtk_Response_Type := -7;
Gtk_Response_Yes : constant Gtk_Response_Type := -8;
Gtk_Response_No : constant Gtk_Response_Type := -9;
Gtk_Response_Apply : constant Gtk_Response_Type := -10;
Gtk_Response_Help : constant Gtk_Response_Type := -11;
-- These are returned from dialogs, and you can also use them
-- yourself if you like.
type Response_Type_Array is array (Natural range <>) of Gtk_Response_Type;
------------------
-- Constructors --
------------------
procedure Gtk_New (Dialog : out Gtk_Dialog);
procedure Initialize (Dialog : access Gtk_Dialog_Record'Class);
procedure Gtk_New
(Dialog : out Gtk_Dialog;
Title : UTF8_String;
Parent : Gtk.Window.Gtk_Window := null;
Flags : Gtk_Dialog_Flags);
procedure Initialize
(Dialog : access Gtk_Dialog_Record'Class;
Title : UTF8_String;
Parent : Gtk.Window.Gtk_Window := null;
Flags : Gtk_Dialog_Flags);
-- Create a new dialog with a specific title, and specific attributes.
-- Parent is the transient parent for the dialog (ie the one that is used
-- for reference for the flag Destroy_With_Parent, or to compute the
-- initial position of the dialog).
-- Since: gtk+ GtkAda 1.0
function Get_Type return Glib.GType;
pragma Import (C, Get_Type, "gtk_dialog_get_type");
-------------
-- Methods --
-------------
procedure Add_Action_Widget
(Dialog : access Gtk_Dialog_Record;
Child : access Gtk.Widget.Gtk_Widget_Record'Class;
Response_Id : Gtk_Response_Type);
-- Adds an activatable widget to the action area of a
-- Gtk.Dialog.Gtk_Dialog, connecting a signal handler that will emit the
-- Gtk.Dialog.Gtk_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 Action_Area field of the Gtk.Dialog.Gtk_Dialog struct.
-- "child": an activatable widget
-- "response_id": response ID for Child
function Add_Button
(Dialog : access Gtk_Dialog_Record;
Text : UTF8_String;
Response_Id : Gtk_Response_Type) return Gtk.Widget.Gtk_Widget;
-- Adds a button with the given text (or a stock button, if Button_Text is
-- a stock ID) and sets things up so that clicking the button will emit the
-- Gtk.Dialog.Gtk_Dialog::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.
-- Returns the button widget that was added
-- "text": text of button, or stock ID
-- "response_id": response ID for the button
function Get_Action_Area
(Dialog : access Gtk_Dialog_Record) return Gtk.Box.Gtk_Box;
-- Returns the action area of Dialog.
-- Since: gtk+ 2.14
function Get_Content_Area
(Dialog : access Gtk_Dialog_Record) return Gtk.Box.Gtk_Box;
-- Returns the content area of Dialog.
-- Since: gtk+ 2.14
function Get_Has_Separator
(Dialog : access Gtk_Dialog_Record) return Boolean;
pragma Obsolescent (Get_Has_Separator);
procedure Set_Has_Separator
(Dialog : access Gtk_Dialog_Record;
Setting : Boolean);
pragma Obsolescent (Set_Has_Separator);
-- Sets whether the dialog has a separator above the buttons.
-- Deprecated since 2.22, This function will be removed in GTK+ 3
-- "setting": True to have a separator
function Get_Response_For_Widget
(Dialog : access Gtk_Dialog_Record;
Widget : access Gtk.Widget.Gtk_Widget_Record'Class)
return Gtk_Response_Type;
-- Gets the response id of a widget in the action area of a dialog. if
-- Widget doesn't have a response id set.
-- Since: gtk+ 2.8
-- "widget": a widget in the action area of Dialog
function Get_Widget_For_Response
(Dialog : access Gtk_Dialog_Record;
Response_Id : Gtk_Response_Type) return Gtk.Widget.Gtk_Widget;
-- Gets the widget button that uses the given response ID in the action
-- area of a dialog.
-- Since: gtk+ 2.20
-- Returns the Widget button that uses the given Response_Id, or null.
-- "response_id": the response ID used by the Dialog widget
procedure Response
(Dialog : access Gtk_Dialog_Record;
Response_Id : Gtk_Response_Type);
-- Emits the Gtk.Dialog.Gtk_Dialog::response signal with the given
-- response ID. Used to indicate that the user has responded to the dialog
-- in some way; typically either you or Gtk.Dialog.Run will be monitoring
-- the ::response signal and take appropriate action.
-- "response_id": response ID
function Run (Dialog : access Gtk_Dialog_Record) return Gtk_Response_Type;
-- Blocks in a recursive main loop until the Dialog either emits the
-- Gtk.Dialog.Gtk_Dialog::response signal, or is destroyed. If the dialog
-- is destroyed during the call to Gtk.Dialog.Run, Gtk.Dialog.Run returns
-- GTK_RESPONSE_NONE. Otherwise, it returns the response ID from the
-- ::response signal emission. Before entering the recursive main loop,
-- Gtk.Dialog.Run calls Gtk.Widget.Show on the dialog for you. Note that
-- you still need to show any children of the dialog yourself. During
-- Gtk.Dialog.Run, the default behavior of
-- Gtk.Widget.Gtk_Widget::delete-event is disabled; if the dialog receives
-- ::delete_event, it will not be destroyed as windows usually are, and
-- Gtk.Dialog.Run will return GTK_RESPONSE_DELETE_EVENT. Also, during
-- Gtk.Dialog.Run the dialog will be modal. You can force Gtk.Dialog.Run to
-- return at any time by calling Gtk.Dialog.Response to emit the ::response
-- signal. Destroying the dialog during Gtk.Dialog.Run is a very bad idea,
-- because your post-run code won't know whether the dialog was destroyed
-- or not. After Gtk.Dialog.Run returns, you are responsible for hiding or
-- destroying the dialog if you wish to do so. Typical usage of this
-- function might be: |[ gint result = gtk_dialog_run (GTK_DIALOG
-- (dialog)); switch (result) { case GTK_RESPONSE_ACCEPT:
-- do_application_specific_something (); break; default:
-- do_nothing_since_dialog_was_cancelled (); break; } gtk_widget_destroy
-- (dialog); ]| Note that even though the recursive main loop gives the
-- effect of a modal dialog (it prevents the user from interacting with
-- other windows in the same window group while the dialog is run),
-- callbacks such as timeouts, IO channel watches, DND drops, etc,
-- will be triggered during a Gtk.Dialog.Run call.
procedure Set_Default_Response
(Dialog : access Gtk_Dialog_Record;
Response_Id : Gtk_Response_Type);
-- Sets the last widget in the dialog's action area with the given
-- Response_Id as the default widget for the dialog. Pressing "Enter"
-- normally activates the default widget.
-- "response_id": a response ID
procedure Set_Response_Sensitive
(Dialog : access Gtk_Dialog_Record;
Response_Id : Gtk_Response_Type;
Setting : Boolean);
-- Calls gtk_widget_set_sensitive (widget, Setting) for
-- each widget in the dialog's action area with the given Response_Id. A
-- convenient way to sensitize/desensitize dialog buttons.
-- "response_id": a response ID
-- "setting": True for sensitive
----------------------
-- GtkAda additions --
----------------------
procedure Set_Alternative_Button_Order_From_Array
(Dialog : access Gtk_Dialog_Record;
New_Order : Response_Type_Array);
-- Sets an alternative button order. If the gtk-alternative-button-order
-- setting is set to %TRUE, the dialog buttons are reordered according to
-- the order of the response ids passed to this function.
--
-- By default, GTK+ dialogs use the button order advocated by the Gnome
-- Human Interface Guidelines with the affirmative button at the far right,
-- and the cancel button left of it. But the builtin GTK+ dialogs and
-- message dialogs' do provide an alternative button order, which is more
-- suitable on some platforms, e.g. Windows.
--
-- Use this function after adding all the buttons to your dialog.
function Gtk_Alternative_Dialog_Button_Order
(Screen : Gdk.Gdk_Screen := null) return Boolean;
-- Returns True if dialogs are expected to use an alternative button order
-- on the given screen (or current screen if null) . See
-- Set_Alternative_Button_Order_From_Array for more details about
-- alternative button order.
--
-- If you need to use this function, you should probably connect to the
-- ::notify:gtk-alternative-button-order signal on the Gtk_Settings object
-- associated to Screen, in order to be notified if the button order
-- setting changes.
--
-- Returns: Whether the alternative button order should be used
------------
-- Fields --
------------
function Get_Vbox
(Dialog : access Gtk_Dialog_Record) return Gtk.Box.Gtk_Box;
----------------
-- Interfaces --
----------------
-- This class implements several interfaces. See Glib.Types
--
-- - "Buildable"
package Implements_Buildable is new Glib.Types.Implements
(Gtk.Buildable.Gtk_Buildable, Gtk_Dialog_Record, Gtk_Dialog);
function "+"
(Widget : access Gtk_Dialog_Record'Class)
return Gtk.Buildable.Gtk_Buildable
renames Implements_Buildable.To_Interface;
function "-"
(Interf : Gtk.Buildable.Gtk_Buildable)
return Gtk_Dialog
renames Implements_Buildable.To_Object;
----------------
-- Properties --
----------------
-- The following properties are defined for this widget. See
-- Glib.Properties for more information on properties)
--
-- Name: Has_Separator_Property
-- Type: Boolean
-- Flags: read-write
-- When True, the dialog has a separator bar above its buttons.
Has_Separator_Property : constant Glib.Properties.Property_Boolean;
-------------
-- Signals --
-------------
-- The following new signals are defined for this widget:
--
-- "close"
-- procedure Handler (Self : access Gtk_Dialog_Record'Class);
-- The ::close signal is a keybinding
-- signal which gets emitted when the user uses a keybinding to
-- close the dialog. The default binding for this signal is the Escape key.
--
-- "response"
-- procedure Handler
-- (Self : access Gtk_Dialog_Record'Class;
-- Response_Id : Gtk_Response_Type);
-- -- "response_id": the response ID
-- Emitted when an action widget is clicked, the dialog receives a delete
-- event, or the application programmer calls Gtk.Dialog.Response. On a
-- delete event, the response ID is GTK_RESPONSE_DELETE_EVENT. Otherwise,
-- it depends on which action widget was clicked.
Signal_Close : constant Glib.Signal_Name := "close";
Signal_Response : constant Glib.Signal_Name := "response";
private
Has_Separator_Property : constant Glib.Properties.Property_Boolean :=
Glib.Properties.Build ("has-separator");
end Gtk.Dialog;