1. ----------------------------------------------------------------------- 
  2. --               GtkAda - Ada95 binding for Gtk+/Gnome               -- 
  3. --                                                                   -- 
  4. --   Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet   -- 
  5. --                Copyright (C) 2000-2013, AdaCore                   -- 
  6. --                                                                   -- 
  7. -- This library is free software; you can redistribute it and/or     -- 
  8. -- modify it under the terms of the GNU General Public               -- 
  9. -- License as published by the Free Software Foundation; either      -- 
  10. -- version 2 of the License, or (at your option) any later version.  -- 
  11. --                                                                   -- 
  12. -- This library is distributed in the hope that it will be useful,   -- 
  13. -- but WITHOUT ANY WARRANTY; without even the implied warranty of    -- 
  14. -- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU -- 
  15. -- General Public License for more details.                          -- 
  16. --                                                                   -- 
  17. -- You should have received a copy of the GNU General Public         -- 
  18. -- License along with this library; if not, write to the             -- 
  19. -- Free Software Foundation, Inc., 59 Temple Place - Suite 330,      -- 
  20. -- Boston, MA 02111-1307, USA.                                       -- 
  21. --                                                                   -- 
  22. -- As a special exception, if other files instantiate generics from  -- 
  23. -- this unit, or you link this unit with other files to produce an   -- 
  24. -- executable, this  unit  does not  by itself cause  the resulting  -- 
  25. -- executable to be covered by the GNU General Public License. This  -- 
  26. -- exception does not however invalidate any other reasons why the   -- 
  27. -- executable file  might be covered by the  GNU Public License.     -- 
  28. ----------------------------------------------------------------------- 
  29.  
  30. --  <description> 
  31. --  Dialog boxes are a convenient way to prompt the user for a small amount of 
  32. --  input, eg. to display a message, ask a question, or anything else that does 
  33. --  not require extensive effort on the user's part. 
  34. -- 
  35. --  Gtkada treats a dialog as a window split horizontally. The top section is 
  36. --  a Gtk_Vbox, and is where widgets such as a Gtk_Label or a Gtk_Entry should 
  37. --  be packed. The second area is known as the action_area. This is generally 
  38. --  used for packing buttons into the dialog which may perform functions such 
  39. --  as cancel, ok, or apply. The two areas are separated by a Gtk_Hseparator. 
  40. -- 
  41. --  If 'dialog' is a newly created dialog, the two primary areas of the window 
  42. --  can be accessed using Get_Vbox and Get_Action_Area as can be seen from the 
  43. --  example, below. 
  44. -- 
  45. --  A 'modal' dialog (that is, one which freezes the rest of the application 
  46. --  from user input), can be created by calling Set_Modal on the dialog. 
  47. -- 
  48. --  See Gtkada.Dialogs for a higher level dialog interface. 
  49. -- 
  50. --  </description> 
  51. --  <screenshot>gtk-dialog</screenshot> 
  52. --  <group>Windows</group> 
  53. --  <testgtk>create_dialog.adb</testgtk> 
  54.  
  55. pragma Warnings (Off, "*is already use-visible*"); 
  56. with Glib;            use Glib; 
  57. with Glib.Properties; use Glib.Properties; 
  58. with Glib.Types;      use Glib.Types; 
  59. with Gtk.Box;         use Gtk.Box; 
  60. with Gtk.Buildable;   use Gtk.Buildable; 
  61. with Gtk.Widget;      use Gtk.Widget; 
  62. with Gtk.Window;      use Gtk.Window; 
  63.  
  64. package Gtk.Dialog is 
  65.  
  66.    type Gtk_Dialog_Record is new Gtk_Window_Record with null record; 
  67.    type Gtk_Dialog is access all Gtk_Dialog_Record'Class; 
  68.  
  69.    type Gtk_Dialog_Flags is mod 8; 
  70.    for Gtk_Dialog_Flags'Size use Gint'Size; 
  71.    pragma Convention (C, Gtk_Dialog_Flags); 
  72.    Modal               : constant Gtk_Dialog_Flags := 2 ** 0; 
  73.    Destroy_With_Parent : constant Gtk_Dialog_Flags := 2 ** 1; 
  74.    No_Separator        : constant Gtk_Dialog_Flags := 2 ** 2; 
  75.    --  Various flags that can be set for the dialog, with the following 
  76.    --  implications: 
  77.    --     - Modal : the dialog is modal, see Gtk.Window.Set_Modal 
  78.    --     - Destroy_With_Parent: The dialog is destroyed if its parent is 
  79.    --       destroyed. See Gtk.Window.Set_Destroy_With_Parent 
  80.    --     - No_Separator: No separator bar above the buttons. 
  81.  
  82.    type Gtk_Response_Type is new Gint; 
  83.    --  Type used for Response_Id's. 
  84.    --  Positive values are totally user-interpreted. 
  85.    --  GtkAda will sometimes return Gtk_Response_None if no Response_Id is 
  86.    --  available. 
  87.    -- 
  88.    --  Typical usage is: 
  89.    --    if Gtk.Dialog.Run (Dialog) = Gtk_Response_Accept then 
  90.    --       blah; 
  91.    --    end if; 
  92.  
  93.    Gtk_Response_None : constant Gtk_Response_Type := -1; 
  94.    --  GtkAda returns this if a response widget has no Response_Id, 
  95.    --  or if the dialog gets programmatically hidden or destroyed. 
  96.  
  97.    Gtk_Response_Reject : constant Gtk_Response_Type := -2; 
  98.    Gtk_Response_Accept : constant Gtk_Response_Type := -3; 
  99.    --  GtkAda won't return these unless you pass them in 
  100.    --  as the response for an action widget. They are 
  101.    --  for your convenience. 
  102.  
  103.    Gtk_Response_Delete_Event : constant Gtk_Response_Type := -4; 
  104.    --  If the dialog is deleted through the button in the titlebar 
  105.  
  106.    Gtk_Response_OK     : constant Gtk_Response_Type := -5; 
  107.    Gtk_Response_Cancel : constant Gtk_Response_Type := -6; 
  108.    Gtk_Response_Close  : constant Gtk_Response_Type := -7; 
  109.    Gtk_Response_Yes    : constant Gtk_Response_Type := -8; 
  110.    Gtk_Response_No     : constant Gtk_Response_Type := -9; 
  111.    Gtk_Response_Apply  : constant Gtk_Response_Type := -10; 
  112.    Gtk_Response_Help   : constant Gtk_Response_Type := -11; 
  113.    --  These are returned from dialogs, and you can also use them 
  114.    --  yourself if you like. 
  115.  
  116.    type Response_Type_Array is array (Natural range <>) of Gtk_Response_Type; 
  117.  
  118.    ------------------ 
  119.    -- Constructors -- 
  120.    ------------------ 
  121.  
  122.    procedure Gtk_New (Dialog : out Gtk_Dialog); 
  123.    procedure Initialize (Dialog : access Gtk_Dialog_Record'Class); 
  124.  
  125.    procedure Gtk_New 
  126.       (Dialog : out Gtk_Dialog; 
  127.        Title  : UTF8_String; 
  128.        Parent : Gtk.Window.Gtk_Window := null; 
  129.        Flags  : Gtk_Dialog_Flags); 
  130.    procedure Initialize 
  131.       (Dialog : access Gtk_Dialog_Record'Class; 
  132.        Title  : UTF8_String; 
  133.        Parent : Gtk.Window.Gtk_Window := null; 
  134.        Flags  : Gtk_Dialog_Flags); 
  135.    --  Create a new dialog with a specific title, and specific attributes. 
  136.    --  Parent is the transient parent for the dialog (ie the one that is used 
  137.    --  for reference for the flag Destroy_With_Parent, or to compute the 
  138.    --  initial position of the dialog). 
  139.    --  Since: gtk+ GtkAda 1.0 
  140.  
  141.    function Get_Type return Glib.GType; 
  142.    pragma Import (C, Get_Type, "gtk_dialog_get_type"); 
  143.  
  144.    ------------- 
  145.    -- Methods -- 
  146.    ------------- 
  147.  
  148.    procedure Add_Action_Widget 
  149.       (Dialog      : access Gtk_Dialog_Record; 
  150.        Child       : access Gtk.Widget.Gtk_Widget_Record'Class; 
  151.        Response_Id : Gtk_Response_Type); 
  152.    --  Adds an activatable widget to the action area of a 
  153.    --  Gtk.Dialog.Gtk_Dialog, connecting a signal handler that will emit the 
  154.    --  Gtk.Dialog.Gtk_Dialog::response signal on the dialog when the widget is 
  155.    --  activated. The widget is appended to the end of the dialog's action 
  156.    --  area. If you want to add a non-activatable widget, simply pack it into 
  157.    --  the Action_Area field of the Gtk.Dialog.Gtk_Dialog struct. 
  158.    --  "child": an activatable widget 
  159.    --  "response_id": response ID for Child 
  160.  
  161.    function Add_Button 
  162.       (Dialog      : access Gtk_Dialog_Record; 
  163.        Text        : UTF8_String; 
  164.        Response_Id : Gtk_Response_Type) return Gtk.Widget.Gtk_Widget; 
  165.    --  Adds a button with the given text (or a stock button, if Button_Text is 
  166.    --  a stock ID) and sets things up so that clicking the button will emit the 
  167.    --  Gtk.Dialog.Gtk_Dialog::response signal with the given Response_Id. The 
  168.    --  button is appended to the end of the dialog's action area. The button 
  169.    --  widget is returned, but usually you don't need it. 
  170.    --  "text": text of button, or stock ID 
  171.    --  "response_id": response ID for the button 
  172.  
  173.    function Get_Action_Area 
  174.       (Dialog : access Gtk_Dialog_Record) return Gtk.Box.Gtk_Box; 
  175.    --  Returns the action area of Dialog. 
  176.    --  Since: gtk+ 2.14 
  177.  
  178.    function Get_Content_Area 
  179.       (Dialog : access Gtk_Dialog_Record) return Gtk.Box.Gtk_Box; 
  180.    --  Returns the content area of Dialog. 
  181.    --  Since: gtk+ 2.14 
  182.  
  183.    function Get_Has_Separator 
  184.       (Dialog : access Gtk_Dialog_Record) return Boolean; 
  185.    pragma Obsolescent (Get_Has_Separator); 
  186.    procedure Set_Has_Separator 
  187.       (Dialog  : access Gtk_Dialog_Record; 
  188.        Setting : Boolean); 
  189.    pragma Obsolescent (Set_Has_Separator); 
  190.    --  Sets whether the dialog has a separator above the buttons. 
  191.    --  Deprecated since 2.22, This function will be removed in GTK+ 3 
  192.    --  "setting": True to have a separator 
  193.  
  194.    function Get_Response_For_Widget 
  195.       (Dialog : access Gtk_Dialog_Record; 
  196.        Widget : access Gtk.Widget.Gtk_Widget_Record'Class) 
  197.        return Gtk_Response_Type; 
  198.    --  Gets the response id of a widget in the action area of a dialog. if 
  199.    --  Widget doesn't have a response id set. 
  200.    --  Since: gtk+ 2.8 
  201.    --  "widget": a widget in the action area of Dialog 
  202.  
  203.    function Get_Widget_For_Response 
  204.       (Dialog      : access Gtk_Dialog_Record; 
  205.        Response_Id : Gtk_Response_Type) return Gtk.Widget.Gtk_Widget; 
  206.    --  Gets the widget button that uses the given response ID in the action 
  207.    --  area of a dialog. 
  208.    --  Since: gtk+ 2.20 
  209.    --  "response_id": the response ID used by the Dialog widget 
  210.  
  211.    procedure Response 
  212.       (Dialog      : access Gtk_Dialog_Record; 
  213.        Response_Id : Gtk_Response_Type); 
  214.    --  Emits the Gtk.Dialog.Gtk_Dialog::response signal with the given 
  215.    --  response ID. Used to indicate that the user has responded to the dialog 
  216.    --  in some way; typically either you or Gtk.Dialog.Run will be monitoring 
  217.    --  the ::response signal and take appropriate action. 
  218.    --  "response_id": response ID 
  219.  
  220.    function Run (Dialog : access Gtk_Dialog_Record) return Gtk_Response_Type; 
  221.    --  Blocks in a recursive main loop until the Dialog either emits the 
  222.    --  Gtk.Dialog.Gtk_Dialog::response signal, or is destroyed. If the dialog 
  223.    --  is destroyed during the call to Gtk.Dialog.Run, Gtk.Dialog.Run returns 
  224.    --  GTK_RESPONSE_NONE. Otherwise, it returns the response ID from the 
  225.    --  ::response signal emission. Before entering the recursive main loop, 
  226.    --  Gtk.Dialog.Run calls Gtk.Widget.Show on the dialog for you. Note that 
  227.    --  you still need to show any children of the dialog yourself. During 
  228.    --  Gtk.Dialog.Run, the default behavior of 
  229.    --  Gtk.Widget.Gtk_Widget::delete-event is disabled; if the dialog receives 
  230.    --  ::delete_event, it will not be destroyed as windows usually are, and 
  231.    --  Gtk.Dialog.Run will return GTK_RESPONSE_DELETE_EVENT. Also, during 
  232.    --  Gtk.Dialog.Run the dialog will be modal. You can force Gtk.Dialog.Run to 
  233.    --  return at any time by calling Gtk.Dialog.Response to emit the ::response 
  234.    --  signal. Destroying the dialog during Gtk.Dialog.Run is a very bad idea, 
  235.    --  because your post-run code won't know whether the dialog was destroyed 
  236.    --  or not. After Gtk.Dialog.Run returns, you are responsible for hiding or 
  237.    --  destroying the dialog if you wish to do so. Typical usage of this 
  238.    --  function might be: |[ gint result = gtk_dialog_run (GTK_DIALOG 
  239.    --  (dialog)); switch (result) { case GTK_RESPONSE_ACCEPT: 
  240.    --  do_application_specific_something (); break; default: 
  241.    --  do_nothing_since_dialog_was_cancelled (); break; } gtk_widget_destroy 
  242.    --  (dialog); ]| Note that even though the recursive main loop gives the 
  243.    --  effect of a modal dialog (it prevents the user from interacting with 
  244.    --  other windows in the same window group while the dialog is run), 
  245.    --  callbacks such as timeouts, IO channel watches, DND drops, etc, 
  246.    --  <emphasis>will</emphasis> be triggered during a Gtk.Dialog.Run call. 
  247.  
  248.    procedure Set_Default_Response 
  249.       (Dialog      : access Gtk_Dialog_Record; 
  250.        Response_Id : Gtk_Response_Type); 
  251.    --  Sets the last widget in the dialog's action area with the given 
  252.    --  Response_Id as the default widget for the dialog. Pressing "Enter" 
  253.    --  normally activates the default widget. 
  254.    --  "response_id": a response ID 
  255.  
  256.    procedure Set_Response_Sensitive 
  257.       (Dialog      : access Gtk_Dialog_Record; 
  258.        Response_Id : Gtk_Response_Type; 
  259.        Setting     : Boolean); 
  260.    --  Calls <literal>gtk_widget_set_sensitive (widget, Setting)</literal> for 
  261.    --  each widget in the dialog's action area with the given Response_Id. A 
  262.    --  convenient way to sensitize/desensitize dialog buttons. 
  263.    --  "response_id": a response ID 
  264.    --  "setting": True for sensitive 
  265.  
  266.    ---------------------- 
  267.    -- GtkAda additions -- 
  268.    ---------------------- 
  269.  
  270.    procedure Set_Alternative_Button_Order_From_Array 
  271.      (Dialog    : access Gtk_Dialog_Record; 
  272.       New_Order : Response_Type_Array); 
  273.    --  Sets an alternative button order. If the gtk-alternative-button-order 
  274.    --  setting is set to %TRUE, the dialog buttons are reordered according to 
  275.    --  the order of the response ids passed to this function. 
  276.    -- 
  277.    --  By default, GTK+ dialogs use the button order advocated by the Gnome 
  278.    --  Human Interface Guidelines with the affirmative button at the far right, 
  279.    --  and the cancel button left of it. But the builtin GTK+ dialogs and 
  280.    --  message dialogs' do provide an alternative button order, which is more 
  281.    --  suitable on some platforms, e.g. Windows. 
  282.    -- 
  283.    --  Use this function after adding all the buttons to your dialog. 
  284.  
  285.    function Gtk_Alternative_Dialog_Button_Order 
  286.      (Screen : Gdk.Gdk_Screen := null)  return Boolean; 
  287.    --  Returns True if dialogs are expected to use an alternative button order 
  288.    --  on the given screen (or current screen if null) . See 
  289.    --  Set_Alternative_Button_Order_From_Array for more details about 
  290.    --  alternative button order. 
  291.    -- 
  292.    --  If you need to use this function, you should probably connect to the 
  293.    --  ::notify:gtk-alternative-button-order signal on the Gtk_Settings object 
  294.    --  associated to Screen, in order to be notified if the button order 
  295.    --  setting changes. 
  296.    -- 
  297.    --  Returns: Whether the alternative button order should be used 
  298.  
  299.    ------------ 
  300.    -- Fields -- 
  301.    ------------ 
  302.  
  303.    function Get_Vbox 
  304.       (Dialog : access Gtk_Dialog_Record) return Gtk.Box.Gtk_Box; 
  305.  
  306.    ---------------- 
  307.    -- Interfaces -- 
  308.    ---------------- 
  309.    --  This class implements several interfaces. See Glib.Types 
  310.    -- 
  311.    --  - "Buildable" 
  312.  
  313.    package Implements_Buildable is new Glib.Types.Implements 
  314.      (Gtk.Buildable.Gtk_Buildable, Gtk_Dialog_Record, Gtk_Dialog); 
  315.    function "+" 
  316.      (Widget : access Gtk_Dialog_Record'Class) 
  317.    return Gtk.Buildable.Gtk_Buildable 
  318.    renames Implements_Buildable.To_Interface; 
  319.    function "-" 
  320.      (Interf : Gtk.Buildable.Gtk_Buildable) 
  321.    return Gtk_Dialog 
  322.    renames Implements_Buildable.To_Object; 
  323.  
  324.    ---------------- 
  325.    -- Properties -- 
  326.    ---------------- 
  327.    --  The following properties are defined for this widget. See 
  328.    --  Glib.Properties for more information on properties) 
  329.    -- 
  330.    --  Name: Has_Separator_Property 
  331.    --  Type: Boolean 
  332.    --  Flags: read-write 
  333.    --  When True, the dialog has a separator bar above its buttons. 
  334.  
  335.    Has_Separator_Property : constant Glib.Properties.Property_Boolean; 
  336.  
  337.    ------------- 
  338.    -- Signals -- 
  339.    ------------- 
  340.    --  The following new signals are defined for this widget: 
  341.    -- 
  342.    --  "close" 
  343.    --     procedure Handler (Self : access Gtk_Dialog_Record'Class); 
  344.    --  The ::close signal is a <link linkend="keybinding-signals">keybinding 
  345.    --  signal</link> which gets emitted when the user uses a keybinding to 
  346.    --  close the dialog. The default binding for this signal is the Escape key. 
  347.    -- 
  348.    --  "response" 
  349.    --     procedure Handler 
  350.    --       (Self        : access Gtk_Dialog_Record'Class; 
  351.    --        Response_Id : Gtk_Response_Type); 
  352.    --    --  "response_id": the response ID 
  353.    --  Emitted when an action widget is clicked, the dialog receives a delete 
  354.    --  event, or the application programmer calls Gtk.Dialog.Response. On a 
  355.    --  delete event, the response ID is GTK_RESPONSE_DELETE_EVENT. Otherwise, 
  356.    --  it depends on which action widget was clicked. 
  357.  
  358.    Signal_Close : constant Glib.Signal_Name := "close"; 
  359.    Signal_Response : constant Glib.Signal_Name := "response"; 
  360.  
  361. private 
  362.    Has_Separator_Property : constant Glib.Properties.Property_Boolean := 
  363.      Glib.Properties.Build ("has-separator"); 
  364. end Gtk.Dialog;