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