1------------------------------------------------------------------------------
2--                                                                          --
3--      Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet       --
4--                     Copyright (C) 2000-2015, AdaCore                     --
5--                                                                          --
6-- This library is free software;  you can redistribute it and/or modify it --
7-- under terms of the  GNU General Public License  as published by the Free --
8-- Software  Foundation;  either version 3,  or (at your  option) any later --
9-- version. This library is distributed in the hope that it will be useful, --
10-- but WITHOUT ANY WARRANTY;  without even the implied warranty of MERCHAN- --
11-- TABILITY or FITNESS FOR A PARTICULAR PURPOSE.                            --
12--                                                                          --
13-- As a special exception under Section 7 of GPL version 3, you are granted --
14-- additional permissions described in the GCC Runtime Library Exception,   --
15-- version 3.1, as published by the Free Software Foundation.               --
16--                                                                          --
17-- You should have received a copy of the GNU General Public License and    --
18-- a copy of the GCC Runtime Library Exception along with this program;     --
19-- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
20-- <http://www.gnu.org/licenses/>.                                          --
21--                                                                          --
22------------------------------------------------------------------------------
23
24--  <description>
25--  GtkBuildable allows objects to extend and customize their deserialization
26--  from [GtkBuilder UI descriptions][BUILDER-UI]. The interface includes
27--  methods for setting names and properties of objects, parsing custom tags
28--  and constructing child objects.
29--
30--  The GtkBuildable interface is implemented by all widgets and many of the
31--  non-widget objects that are provided by GTK+. The main user of this
32--  interface is Gtk.Builder.Gtk_Builder. There should be very little need for
33--  applications to call any of these functions directly.
34--
35--  An object only needs to implement this interface if it needs to extend the
36--  Gtk.Builder.Gtk_Builder format or run any extra routines at deserialization
37--  time.
38--
39--  </description>
40pragma Ada_2005;
41
42pragma Warnings (Off, "*is already use-visible*");
43with Glib;        use Glib;
44with Glib.Object; use Glib.Object;
45with Glib.Types;  use Glib.Types;
46with Glib.Values; use Glib.Values;
47with Gtk.Builder; use Gtk.Builder;
48
49package Gtk.Buildable is
50
51   type Gtk_Buildable is new Glib.Types.GType_Interface;
52   Null_Gtk_Buildable : constant Gtk_Buildable;
53
54   ------------------
55   -- Constructors --
56   ------------------
57
58   function Get_Type return Glib.GType;
59   pragma Import (C, Get_Type, "gtk_buildable_get_type");
60
61   -------------
62   -- Methods --
63   -------------
64
65   procedure Add_Child
66      (Self     : Gtk_Buildable;
67       Builder  : not null access Gtk.Builder.Gtk_Builder_Record'Class;
68       Child    : not null access Glib.Object.GObject_Record'Class;
69       The_Type : UTF8_String := "");
70   --  Adds a child to Buildable. Type is an optional string describing how
71   --  the child should be added.
72   --  Since: gtk+ 2.12
73   --  "builder": a Gtk.Builder.Gtk_Builder
74   --  "child": child to add
75   --  "type": kind of child or null
76
77   function Construct_Child
78      (Self    : Gtk_Buildable;
79       Builder : not null access Gtk.Builder.Gtk_Builder_Record'Class;
80       Name    : UTF8_String) return Glib.Object.GObject;
81   --  Constructs a child of Buildable with the name Name.
82   --  Gtk.Builder.Gtk_Builder calls this function if a "constructor" has been
83   --  specified in the UI definition.
84   --  Since: gtk+ 2.12
85   --  "builder": Gtk.Builder.Gtk_Builder used to construct this object
86   --  "name": name of child to construct
87
88   procedure Custom_Finished
89      (Self    : Gtk_Buildable;
90       Builder : not null access Gtk.Builder.Gtk_Builder_Record'Class;
91       Child   : access Glib.Object.GObject_Record'Class;
92       Tagname : UTF8_String;
93       Data    : System.Address);
94   --  This is similar to Gtk.Buildable.Parser_Finished but is called once for
95   --  each custom tag handled by the Buildable.
96   --  Since: gtk+ 2.12
97   --  "builder": a Gtk.Builder.Gtk_Builder
98   --  "child": child object or null for non-child tags
99   --  "tagname": the name of the tag
100   --  "data": user data created in custom_tag_start
101
102   procedure Custom_Tag_End
103      (Self    : Gtk_Buildable;
104       Builder : not null access Gtk.Builder.Gtk_Builder_Record'Class;
105       Child   : access Glib.Object.GObject_Record'Class;
106       Tagname : UTF8_String;
107       Data    : in out System.Address);
108   --  This is called at the end of each custom element handled by the
109   --  buildable.
110   --  Since: gtk+ 2.12
111   --  "builder": Gtk.Builder.Gtk_Builder used to construct this object
112   --  "child": child object or null for non-child tags
113   --  "tagname": name of tag
114   --  "data": user data that will be passed in to parser functions
115
116   function Get_Internal_Child
117      (Self      : Gtk_Buildable;
118       Builder   : not null access Gtk.Builder.Gtk_Builder_Record'Class;
119       Childname : UTF8_String) return Glib.Object.GObject;
120   --  Get the internal child called Childname of the Buildable object.
121   --  Since: gtk+ 2.12
122   --  "builder": a Gtk.Builder.Gtk_Builder
123   --  "childname": name of child
124
125   function Get_Name (Self : Gtk_Buildable) return UTF8_String;
126   --  Gets the name of the Buildable object.
127   --  Gtk.Builder.Gtk_Builder sets the name based on the [GtkBuilder UI
128   --  definition][BUILDER-UI] used to construct the Buildable.
129   --  Since: gtk+ 2.12
130
131   procedure Set_Name (Self : Gtk_Buildable; Name : UTF8_String);
132   --  Sets the name of the Buildable object.
133   --  Since: gtk+ 2.12
134   --  "name": name to set
135
136   procedure Parser_Finished
137      (Self    : Gtk_Buildable;
138       Builder : not null access Gtk.Builder.Gtk_Builder_Record'Class);
139   --  Called when the builder finishes the parsing of a [GtkBuilder UI
140   --  definition][BUILDER-UI]. Note that this will be called once for each
141   --  time Gtk.Builder.Add_From_File or Gtk.Builder.Add_From_String is called
142   --  on a builder.
143   --  Since: gtk+ 2.12
144   --  "builder": a Gtk.Builder.Gtk_Builder
145
146   procedure Set_Buildable_Property
147      (Self    : Gtk_Buildable;
148       Builder : not null access Gtk.Builder.Gtk_Builder_Record'Class;
149       Name    : UTF8_String;
150       Value   : in out Glib.Values.GValue);
151   --  Sets the property name Name to Value on the Buildable object.
152   --  Since: gtk+ 2.12
153   --  "builder": a Gtk.Builder.Gtk_Builder
154   --  "name": name of property
155   --  "value": value of property
156
157   ----------------
158   -- Interfaces --
159   ----------------
160   --  This class implements several interfaces. See Glib.Types
161   --
162   --  - "Gtk_Buildable"
163
164   function "+" (W : Gtk_Buildable) return Gtk_Buildable;
165   pragma Inline ("+");
166
167private
168
169Null_Gtk_Buildable : constant Gtk_Buildable :=
170   Gtk_Buildable (Glib.Types.Null_Interface);
171end Gtk.Buildable;
172