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. --  A Gtk_Assistant is a widget used to represent a generally complex 
  32. --  operation split into several steps, guiding the user through its pages and 
  33. --  controlling the page flow to collect the necessary data. 
  34. -- 
  35. --  </description> 
  36. --  <group>Windows</group> 
  37. --  <testgtk>create_assistant.adb</testgtk> 
  38.  
  39. pragma Warnings (Off, "*is already use-visible*"); 
  40. with Gdk.Pixbuf;    use Gdk.Pixbuf; 
  41. with Glib;          use Glib; 
  42. with Glib.Types;    use Glib.Types; 
  43. with Gtk.Buildable; use Gtk.Buildable; 
  44. with Gtk.Widget;    use Gtk.Widget; 
  45. with Gtk.Window;    use Gtk.Window; 
  46.  
  47. package Gtk.Assistant is 
  48.  
  49.    type Gtk_Assistant_Record is new Gtk_Window_Record with null record; 
  50.    type Gtk_Assistant is access all Gtk_Assistant_Record'Class; 
  51.  
  52.    type Gtk_Assistant_Page_Type is 
  53.         (Gtk_Assistant_Page_Content, 
  54.          Gtk_Assistant_Page_Intro, 
  55.          Gtk_Assistant_Page_Confirm, 
  56.          Gtk_Assistant_Page_Summary, 
  57.          Gtk_Assistant_Page_Progress); 
  58.       --  Definition of various page types.  See Get_Page_Type/Set_Page_Type 
  59.       --  for more info. 
  60.  
  61.       type Gtk_Assistant_Page_Func is access function 
  62.         (Current_Page : Gint; 
  63.          D : System.Address) return Gint; 
  64.       pragma Convention (C, Gtk_Assistant_Page_Func); 
  65.  
  66.    ------------------ 
  67.    -- Constructors -- 
  68.    ------------------ 
  69.  
  70.    procedure Gtk_New (Assistant : out Gtk_Assistant); 
  71.    procedure Initialize (Assistant : access Gtk_Assistant_Record'Class); 
  72.    --  Creates a new Gtk.Assistant.Gtk_Assistant. 
  73.    --  Since: gtk+ 2.10 
  74.  
  75.    function Get_Type return Glib.GType; 
  76.    pragma Import (C, Get_Type, "gtk_assistant_get_type"); 
  77.  
  78.    ------------- 
  79.    -- Methods -- 
  80.    ------------- 
  81.  
  82.    procedure Add_Action_Widget 
  83.       (Assistant : access Gtk_Assistant_Record; 
  84.        Child     : access Gtk.Widget.Gtk_Widget_Record'Class); 
  85.    --  Adds a widget to the action area of a Gtk.Assistant.Gtk_Assistant. 
  86.    --  Since: gtk+ 2.10 
  87.    --  "child": a Gtk.Widget.Gtk_Widget 
  88.  
  89.    function Append_Page 
  90.       (Assistant : access Gtk_Assistant_Record; 
  91.        Page      : access Gtk.Widget.Gtk_Widget_Record'Class) return Gint; 
  92.    --  Appends a page to the Assistant. 
  93.    --  Since: gtk+ 2.10 
  94.    --  "page": a Gtk.Widget.Gtk_Widget 
  95.  
  96.    procedure Commit (Assistant : access Gtk_Assistant_Record); 
  97.    --  Erases the visited page history so the back button is not shown on the 
  98.    --  current page, and removes the cancel button from subsequent pages. Use 
  99.    --  this when the information provided up to the current page is hereafter 
  100.    --  deemed permanent and cannot be modified or undone. For example, showing 
  101.    --  a progress page to track a long-running, unreversible operation after 
  102.    --  the user has clicked apply on a confirmation page. 
  103.    --  Since: gtk+ 2.22 
  104.  
  105.    function Get_Current_Page 
  106.       (Assistant : access Gtk_Assistant_Record) return Gint; 
  107.    procedure Set_Current_Page 
  108.       (Assistant : access Gtk_Assistant_Record; 
  109.        Page_Num  : Gint); 
  110.    --  Switches the page to Page_Num. Note that this will only be necessary in 
  111.    --  custom buttons, as the Assistant flow can be set with 
  112.    --  Gtk.Assistant.Set_Forward_Page_Func. 
  113.    --  Since: gtk+ 2.10 
  114.    --  "page_num": index of the page to switch to, starting from 0. If 
  115.    --  negative, the last page will be used. If greater than the number of 
  116.    --  pages in the Assistant, nothing will be done. 
  117.  
  118.    function Get_N_Pages 
  119.       (Assistant : access Gtk_Assistant_Record) return Gint; 
  120.    --  Returns the number of pages in the Assistant 
  121.    --  Since: gtk+ 2.10 
  122.  
  123.    function Get_Nth_Page 
  124.       (Assistant : access Gtk_Assistant_Record; 
  125.        Page_Num  : Gint) return Gtk.Widget.Gtk_Widget; 
  126.    --  Returns the child widget contained in page number Page_Num. if Page_Num 
  127.    --  is out of bounds. 
  128.    --  Since: gtk+ 2.10 
  129.    --  "page_num": The index of a page in the Assistant, or -1 to get the last 
  130.    --  page; 
  131.  
  132.    function Get_Page_Complete 
  133.       (Assistant : access Gtk_Assistant_Record; 
  134.        Page      : access Gtk.Widget.Gtk_Widget_Record'Class) return Boolean; 
  135.    procedure Set_Page_Complete 
  136.       (Assistant : access Gtk_Assistant_Record; 
  137.        Page      : access Gtk.Widget.Gtk_Widget_Record'Class; 
  138.        Complete  : Boolean); 
  139.    --  Sets whether Page contents are complete. This will make 
  140.    --  Since: gtk+ 2.10 
  141.    --  "page": a page of Assistant 
  142.    --  "complete": the completeness status of the page 
  143.  
  144.    function Get_Page_Header_Image 
  145.       (Assistant : access Gtk_Assistant_Record; 
  146.        Page      : access Gtk.Widget.Gtk_Widget_Record'Class) 
  147.        return Gdk.Pixbuf.Gdk_Pixbuf; 
  148.    procedure Set_Page_Header_Image 
  149.       (Assistant : access Gtk_Assistant_Record; 
  150.        Page      : access Gtk.Widget.Gtk_Widget_Record'Class; 
  151.        Pixbuf    : access Gdk.Pixbuf.Gdk_Pixbuf_Record'Class); 
  152.    --  Sets a header image for Page. This image is displayed in the header 
  153.    --  area of the assistant when Page is the current page. 
  154.    --  Since: gtk+ 2.10 
  155.    --  "page": a page of Assistant 
  156.    --  "pixbuf": the new header image Page 
  157.  
  158.    function Get_Page_Side_Image 
  159.       (Assistant : access Gtk_Assistant_Record; 
  160.        Page      : access Gtk.Widget.Gtk_Widget_Record'Class) 
  161.        return Gdk.Pixbuf.Gdk_Pixbuf; 
  162.    procedure Set_Page_Side_Image 
  163.       (Assistant : access Gtk_Assistant_Record; 
  164.        Page      : access Gtk.Widget.Gtk_Widget_Record'Class; 
  165.        Pixbuf    : access Gdk.Pixbuf.Gdk_Pixbuf_Record'Class); 
  166.    --  Sets a header image for Page. This image is displayed in the side area 
  167.    --  of the assistant when Page is the current page. 
  168.    --  Since: gtk+ 2.10 
  169.    --  "page": a page of Assistant 
  170.    --  "pixbuf": the new header image Page 
  171.  
  172.    function Get_Page_Title 
  173.       (Assistant : access Gtk_Assistant_Record; 
  174.        Page      : access Gtk.Widget.Gtk_Widget_Record'Class) 
  175.        return UTF8_String; 
  176.    procedure Set_Page_Title 
  177.       (Assistant : access Gtk_Assistant_Record; 
  178.        Page      : access Gtk.Widget.Gtk_Widget_Record'Class; 
  179.        Title     : UTF8_String); 
  180.    --  Sets a title for Page. The title is displayed in the header area of the 
  181.    --  assistant when Page is the current page. 
  182.    --  Since: gtk+ 2.10 
  183.    --  "page": a page of Assistant 
  184.    --  "title": the new title for Page 
  185.  
  186.    function Get_Page_Type 
  187.       (Assistant : access Gtk_Assistant_Record; 
  188.        Page      : access Gtk.Widget.Gtk_Widget_Record'Class) 
  189.        return Gtk_Assistant_Page_Type; 
  190.    procedure Set_Page_Type 
  191.       (Assistant : access Gtk_Assistant_Record; 
  192.        Page      : access Gtk.Widget.Gtk_Widget_Record'Class; 
  193.        The_Type  : Gtk_Assistant_Page_Type); 
  194.    --  Sets the page type for Page. The page type determines the page behavior 
  195.    --  in the Assistant. 
  196.    --  Since: gtk+ 2.10 
  197.    --  "page": a page of Assistant 
  198.    --  "type": the new type for Page 
  199.  
  200.    function Insert_Page 
  201.       (Assistant : access Gtk_Assistant_Record; 
  202.        Page      : access Gtk.Widget.Gtk_Widget_Record'Class; 
  203.        Position  : Gint) return Gint; 
  204.    --  Inserts a page in the Assistant at a given position. 
  205.    --  Since: gtk+ 2.10 
  206.    --  "page": a Gtk.Widget.Gtk_Widget 
  207.    --  "position": the index (starting at 0) at which to insert the page, or 
  208.    --  -1 to append the page to the Assistant 
  209.  
  210.    function Prepend_Page 
  211.       (Assistant : access Gtk_Assistant_Record; 
  212.        Page      : access Gtk.Widget.Gtk_Widget_Record'Class) return Gint; 
  213.    --  Prepends a page to the Assistant. 
  214.    --  Since: gtk+ 2.10 
  215.    --  "page": a Gtk.Widget.Gtk_Widget 
  216.  
  217.    procedure Remove_Action_Widget 
  218.       (Assistant : access Gtk_Assistant_Record; 
  219.        Child     : access Gtk.Widget.Gtk_Widget_Record'Class); 
  220.    --  Removes a widget from the action area of a Gtk.Assistant.Gtk_Assistant. 
  221.    --  Since: gtk+ 2.10 
  222.    --  "child": a Gtk.Widget.Gtk_Widget 
  223.  
  224.    procedure Set_Forward_Page_Func 
  225.       (Assistant : access Gtk_Assistant_Record; 
  226.        Page_Func : Gtk_Assistant_Page_Func; 
  227.        Data      : System.Address; 
  228.        Destroy   : Glib.G_Destroy_Notify_Address); 
  229.    --  Sets the page forwarding function to be Page_Func, this function will 
  230.    --  be used to determine what will be the next page when the user presses 
  231.    --  the forward button. Setting Page_Func to null will make the assistant to 
  232.    --  use the default forward function, which just goes to the next visible 
  233.    --  page. 
  234.    --  Since: gtk+ 2.10 
  235.    --  "page_func": the Gtk_Assistant_Page_Func, or null to use the default 
  236.    --  one 
  237.    --  "data": user data for Page_Func 
  238.    --  "destroy": destroy notifier for Data 
  239.  
  240.    procedure Update_Buttons_State (Assistant : access Gtk_Assistant_Record); 
  241.    --  Forces Assistant to recompute the buttons state. GTK+ automatically 
  242.    --  takes care of this in most situations, e.g. when the user goes to a 
  243.    --  different page, or when the visibility or completeness of a page 
  244.    --  changes. One situation where it can be necessary to call this function 
  245.    --  is when changing a value on the current page affects the future page 
  246.    --  flow of the assistant. 
  247.    --  Since: gtk+ 2.10 
  248.  
  249.    ---------------------- 
  250.    -- GtkAda additions -- 
  251.    ---------------------- 
  252.  
  253.    generic 
  254.    type Data_Type (<>) is private; 
  255.    package Generic_Assistant_Functions is 
  256.       type Page_Func is access function 
  257.         (Current_Page : Gint; 
  258.          User_Data    : Data_Type) 
  259.       return Gint; 
  260.       --  Spec for page forwarding function. 
  261.  
  262.       type Destroy_Notify is access procedure (User_Data : in out Data_Type); 
  263.       --  Destroy_Notify is called just prior to the destruction of 
  264.       --  User_Data. 
  265.  
  266.       procedure Set_Forward_Page_Func 
  267.         (Assistant : Gtk_Assistant; 
  268.          Func      : Page_Func; 
  269.          User_Data : Data_Type; 
  270.          Destroy   : Destroy_Notify := null); 
  271.       --  Sets the Assistant's page forwarding function to be Func.  This 
  272.       --  function will be used to determine what will be the next page when 
  273.       --  the user presses the forward button. Setting Func to null will make 
  274.       --  the assistant use the default forward function, which just goes 
  275.       --  to the next visible page. 
  276.    end Generic_Assistant_Functions; 
  277.  
  278.    ---------------- 
  279.    -- Interfaces -- 
  280.    ---------------- 
  281.    --  This class implements several interfaces. See Glib.Types 
  282.    -- 
  283.    --  - "Buildable" 
  284.  
  285.    package Implements_Buildable is new Glib.Types.Implements 
  286.      (Gtk.Buildable.Gtk_Buildable, Gtk_Assistant_Record, Gtk_Assistant); 
  287.    function "+" 
  288.      (Widget : access Gtk_Assistant_Record'Class) 
  289.    return Gtk.Buildable.Gtk_Buildable 
  290.    renames Implements_Buildable.To_Interface; 
  291.    function "-" 
  292.      (Interf : Gtk.Buildable.Gtk_Buildable) 
  293.    return Gtk_Assistant 
  294.    renames Implements_Buildable.To_Object; 
  295.  
  296.    ------------- 
  297.    -- Signals -- 
  298.    ------------- 
  299.    --  The following new signals are defined for this widget: 
  300.    -- 
  301.    --  "apply" 
  302.    --     procedure Handler (Self : access Gtk_Assistant_Record'Class); 
  303.    --  The ::apply signal is emitted when the apply button is clicked. The 
  304.    --  default behavior of the Gtk.Assistant.Gtk_Assistant is to switch to the 
  305.    --  page after the current page, unless the current page is the last one. A 
  306.    --  handler for the ::apply signal should carry out the actions for which 
  307.    --  the wizard has collected data. If the action takes a long time to 
  308.    --  complete, you might consider putting a page of type 
  309.    --  %GTK_ASSISTANT_PAGE_PROGRESS after the confirmation page and handle this 
  310.    --  operation within the Gtk.Assistant.Gtk_Assistant::prepare signal of the 
  311.    --  progress page. 
  312.    -- 
  313.    --  "cancel" 
  314.    --     procedure Handler (Self : access Gtk_Assistant_Record'Class); 
  315.    --  The ::cancel signal is emitted when then the cancel button is clicked. 
  316.    -- 
  317.    --  "close" 
  318.    --     procedure Handler (Self : access Gtk_Assistant_Record'Class); 
  319.    --  The ::close signal is emitted either when the close button of a summary 
  320.    --  page is clicked, or when the apply button in the last page in the flow 
  321.    --  (of type %GTK_ASSISTANT_PAGE_CONFIRM) is clicked. 
  322.    -- 
  323.    --  "prepare" 
  324.    --     procedure Handler 
  325.    --       (Self : access Gtk_Assistant_Record'Class; 
  326.    --        Page : Gtk.Widget.Gtk_Widget); 
  327.    --    --  "page": the current page 
  328.    --  The ::prepare signal is emitted when a new page is set as the 
  329.    --  assistant's current page, before making the new page visible. A handler 
  330.    --  for this signal can do any preparation which are necessary before 
  331.    --  showing Page. 
  332.  
  333.    Signal_Apply : constant Glib.Signal_Name := "apply"; 
  334.    Signal_Cancel : constant Glib.Signal_Name := "cancel"; 
  335.    Signal_Close : constant Glib.Signal_Name := "close"; 
  336.    Signal_Prepare : constant Glib.Signal_Name := "prepare"; 
  337.  
  338. end Gtk.Assistant;