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 toolbar groups a number of items (buttons, combo boxes,...), generally
32--  at the top of the application window, just below the menu bar. It provides
33--  quick access to the most commonly used features of your application.
34--  It is common for an application to have multiple toolbars.
35--  </description>
36--  <c_version>2.8.17</c_version>
37--  <group>Menus and Toolbars</group>
38--  <testgtk>create_toolbar.adb</testgtk>
39--  <screenshot>gtk-toolbar</screenshot>
40
41with Glib;
42with Glib.Properties;
43with Gtk.Button;
44with Gtk.Container;
45with Gtk.Enums; use Gtk.Enums;
46with Gtk.Tool_Item;
47with Gtk.Widget;
48
49package Gtk.Toolbar is
50
51   type Gtk_Toolbar_Record is new
52     Gtk.Container.Gtk_Container_Record with private;
53   type Gtk_Toolbar is access all Gtk_Toolbar_Record'Class;
54
55   procedure Gtk_New (Widget : out Gtk_Toolbar);
56   procedure Initialize (Widget : access Gtk_Toolbar_Record'Class);
57   --  Create or initialize a new toolbar
58
59   function Get_Type return Glib.GType;
60   --  Return the internal value associated with a Gtk_Toolbar.
61
62   -----------
63   -- Items --
64   -----------
65
66   procedure Insert
67     (Toolbar : access Gtk_Toolbar_Record;
68      Item    : access Gtk.Tool_Item.Gtk_Tool_Item_Record'Class;
69      Pos     : Gint := -1);
70   --  Insert a new item anywhere in the toolbar.
71   --  If Pos is negative, the item is inserted at the end.
72   --  If Pos is 0, the item is inserted first in the toolbar
73
74   function Get_Item_Index
75     (Toolbar : access Gtk_Toolbar_Record;
76      Item    : access Gtk.Tool_Item.Gtk_Tool_Item_Record'Class)
77      return Gint;
78   --  Get the position of Item within the toolbar
79
80   function Get_N_Items
81     (Toolbar : access Gtk_Toolbar_Record) return Gint;
82   --  Return the number of items in the toolbar
83
84   function Get_Nth_Item
85     (Toolbar : access Gtk_Toolbar_Record;
86      N       : Gint)
87      return Gtk.Tool_Item.Gtk_Tool_Item;
88   --  Return the n-th item in the toolbar
89
90   procedure Set_Drop_Highlight_Item
91     (Toolbar   : access Gtk_Toolbar_Record;
92      Tool_Item : access Gtk.Tool_Item.Gtk_Tool_Item_Record'Class;
93      Index     : Gint);
94   --  Highlights Toolbar to give an idea of what it would look like
95   --  if Item was added at the position indicated by Index.
96   --  If Item is %NULL, highlighting is turned off. In that case Index is
97   --  ignored.
98   --
99   --  The item passed to this function must not be part of any widget
100   --  hierarchy. When an item is set as drop highlight item it can not
101   --  be added to any widget hierarchy or used as highlight item for another
102   --  toolbar.
103
104   ---------------------
105   -- Style functions --
106   ---------------------
107
108   procedure Set_Orientation
109     (Toolbar     : access Gtk_Toolbar_Record;
110      Orientation : Gtk_Orientation);
111   function Get_Orientation
112     (Toolbar : access Gtk_Toolbar_Record) return Gtk_Orientation;
113   --  Set or get the orientation (horizontal, vertical) for the toolbar
114
115   procedure Set_Style
116     (Toolbar : access Gtk_Toolbar_Record;
117      Style   : Gtk_Toolbar_Style);
118   function Get_Style
119     (Toolbar : access Gtk_Toolbar_Record) return Gtk_Toolbar_Style;
120   --  Set the style of the toolbar: text only, images only, or both
121
122   procedure Unset_Style (Toolbar : access Gtk_Toolbar_Record);
123   --  Unsets a toolbar style set with Set_Style, so that user preferences
124   --  will be used to determine the toolbar style. These user preferences are
125   --  defined through the current gtk+ theme
126
127   procedure Set_Tooltips
128     (Toolbar : access Gtk_Toolbar_Record;
129      Enable  : Boolean);
130   function Get_Tooltips
131     (Toolbar : access Gtk_Toolbar_Record) return Boolean;
132   --  Sets whether tooltips should be enabled for items in the toolbar
133
134   function Get_Relief_Style
135     (Toolbar : access Gtk_Toolbar_Record)
136      return Gtk_Relief_Style;
137   --  Returns the relief style of buttons on Toolbar. See
138   --  Gtk.Button.Set_Relief for more information on reliefs.
139
140   procedure Set_Show_Arrow
141     (Toolbar    : access Gtk_Toolbar_Record;
142      Show_Arrow : Boolean := True);
143   function Get_Show_Arrow
144     (Toolbar : access Gtk_Toolbar_Record)
145      return Boolean;
146   --  Sets or Gets whether to show an overflow arrow when the toolbar doesn't
147   --  have room for all items on it. If True, the items that have no room are
148   --  still available to the user.
149
150   function Get_Icon_Size
151     (Toolbar : access Gtk_Toolbar_Record) return Gtk_Icon_Size;
152   --  Returns the icon size used in this toolbar
153
154   ----------
155   -- Misc --
156   ----------
157
158   function Get_Drop_Index
159     (Toolbar : access Gtk_Toolbar_Record;
160      X       : Gint;
161      Y       : Gint)
162      return Gint;
163   --  Returns the position corresponding to the indicated point on
164   --  Toolbar. This is useful when dragging items to the toolbar:
165   --  this function returns the position a new item should be
166   --  inserted.
167   --  (X, Y) are the coordinates, in pixels, within the toolbar
168
169   -----------------
170   -- Obsolescent --
171   -----------------
172   --  All subprograms below are now obsolescent in gtk+. They might be removed
173   --  from future versions of gtk+ (and therefore GtkAda).
174   --  To find out whether your code uses any of these, we recommend compiling
175   --  with the -gnatwj switch
176   --  <doc_ignore>
177
178   procedure Gtk_New
179     (Widget      : out Gtk_Toolbar;
180      Orientation : Gtk_Orientation;
181      Style       : Gtk_Toolbar_Style);
182   pragma Obsolescent;
183
184   procedure Initialize
185     (Widget      : access Gtk_Toolbar_Record'Class;
186      Orientation : Gtk_Orientation;
187      Style       : Gtk_Toolbar_Style);
188   pragma Obsolescent;
189
190   type Gtk_Toolbar_Child_Type is
191     (Toolbar_Child_Space,
192      Toolbar_Child_Button,
193      Toolbar_Child_Togglebutton,
194      Toolbar_Child_Radiobutton,
195      Toolbar_Child_Widget);
196   --  This type used to be in Gtk.Enums, but is no longer used outside of the
197   --  obsolescent subprograms in this package. We strongly encourage you to
198   --  move your code to the new Insert API.
199
200   pragma Convention (C, Gtk_Toolbar_Child_Type);
201
202   function Append_Element
203     (Toolbar              : access Gtk_Toolbar_Record;
204      The_Type             : Gtk_Toolbar_Child_Type;
205      Widget               : Gtk.Widget.Gtk_Widget := null;
206      Text                 : UTF8_String := "";
207      Tooltip_Text         : UTF8_String := "";
208      Tooltip_Private_Text : UTF8_String := "";
209      Icon                 : Gtk.Widget.Gtk_Widget := null)
210      return Gtk.Widget.Gtk_Widget;
211   pragma Obsolescent ("Use Gtk.Toolbar.Insert instead"); --  Append_Element
212
213   function Prepend_Element
214     (Toolbar              : access Gtk_Toolbar_Record;
215      The_Type             : Gtk_Toolbar_Child_Type;
216      Widget               : access Gtk.Widget.Gtk_Widget_Record'Class;
217      Text                 : UTF8_String := "";
218      Tooltip_Text         : UTF8_String := "";
219      Tooltip_Private_Text : UTF8_String := "";
220      Icon                 : Gtk.Widget.Gtk_Widget := null)
221      return Gtk.Widget.Gtk_Widget;
222   pragma Obsolescent ("Use Gtk.Toolbar.Insert instead");  --  Prepend_Element
223
224   function Insert_Element
225     (Toolbar              : access Gtk_Toolbar_Record;
226      The_Type             : Gtk_Toolbar_Child_Type;
227      Widget               : access Gtk.Widget.Gtk_Widget_Record'Class;
228      Text                 : UTF8_String := "";
229      Tooltip_Text         : UTF8_String := "";
230      Tooltip_Private_Text : UTF8_String := "";
231      Icon                 : Gtk.Widget.Gtk_Widget := null;
232      Position             : Gint)
233      return Gtk.Widget.Gtk_Widget;
234   pragma Obsolescent ("Use Gtk.Toolbar.Insert instead");  --  Insert_Element
235
236   function Append_Item
237     (Toolbar              : access Gtk_Toolbar_Record;
238      Text                 : UTF8_String := "";
239      Tooltip_Text         : UTF8_String := "";
240      Tooltip_Private_Text : UTF8_String := "";
241      Icon                 : Gtk.Widget.Gtk_Widget := null)
242      return Gtk.Button.Gtk_Button;
243   pragma Obsolescent ("Use Gtk.Toolbar.Insert instead");  --  Append_Item
244
245   function Prepend_Item
246     (Toolbar              : access Gtk_Toolbar_Record;
247      Text                 : UTF8_String := "";
248      Tooltip_Text         : UTF8_String := "";
249      Tooltip_Private_Text : UTF8_String := "";
250      Icon                 : Gtk.Widget.Gtk_Widget := null)
251      return Gtk.Button.Gtk_Button;
252   pragma Obsolescent ("Use Gtk.Toolbar.Insert instead");  --  Prepend_Item
253
254   function Insert_Item
255     (Toolbar              : access Gtk_Toolbar_Record;
256      Text                 : UTF8_String := "";
257      Tooltip_Text         : UTF8_String := "";
258      Tooltip_Private_Text : UTF8_String := "";
259      Icon                 : Gtk.Widget.Gtk_Widget := null;
260      Position             : Gint)
261      return Gtk.Button.Gtk_Button;
262   pragma Obsolescent ("Use Gtk.Toolbar.Insert instead");  --  Insert_Item
263
264   function Insert_Stock
265     (Toolbar              : access Gtk_Toolbar_Record;
266      Stock_Id             : UTF8_String;
267      Tooltip_Text         : UTF8_String := "";
268      Tooltip_Private_Text : UTF8_String := "";
269      Position             : Gint := -1) return Gtk.Button.Gtk_Button;
270   pragma Obsolescent ("Use Gtk.Toolbar.Insert instead");  --  Insert_Stock
271
272   procedure Append_Space (Toolbar : access Gtk_Toolbar_Record);
273   pragma Obsolescent ("Use Gtk.Toolbar.Insert instead");  --  Append_Space
274
275   procedure Prepend_Space (Toolbar : access Gtk_Toolbar_Record);
276   pragma Obsolescent ("Use Gtk.Toolbar.Insert instead");  --  Prepend_Space
277
278   procedure Insert_Space
279     (Toolbar : access Gtk_Toolbar_Record; Position : Gint);
280   pragma Obsolescent ("Use Gtk.Toolbar.Insert instead");  --  Insert_Space
281
282   procedure Remove_Space
283     (Toolbar : access Gtk_Toolbar_Record; Position : Gint);
284   pragma Obsolescent ("Use Gtk.Toolbar.Insert instead");  --  Remove_Space
285
286   procedure Append_Widget
287     (Toolbar              : access Gtk_Toolbar_Record;
288      Widget               : access Gtk.Widget.Gtk_Widget_Record'Class;
289      Tooltip_Text         : UTF8_String := "";
290      Tooltip_Private_Text : UTF8_String := "");
291   pragma Obsolescent ("Use Gtk.Toolbar.Insert instead");  --  Append_Widget
292
293   procedure Prepend_Widget
294     (Toolbar              : access Gtk_Toolbar_Record;
295      Widget               : access Gtk.Widget.Gtk_Widget_Record'Class;
296      Tooltip_Text         : UTF8_String := "";
297      Tooltip_Private_Text : UTF8_String := "");
298   pragma Obsolescent ("Use Gtk.Toolbar.Insert instead");  --  Prepend_Widget
299
300   procedure Insert_Widget
301     (Toolbar              : access Gtk_Toolbar_Record;
302      Widget               : access Gtk.Widget.Gtk_Widget_Record'Class;
303      Tooltip_Text         : UTF8_String := "";
304      Tooltip_Private_Text : UTF8_String := "";
305      Position             : Gint);
306   pragma Obsolescent ("Use Gtk.Toolbar.Insert instead");  --  Insert_Widget
307
308   procedure Set_Icon_Size
309     (Toolbar   : access Gtk_Toolbar_Record;
310      Icon_Size : Gtk_Icon_Size);
311   pragma Obsolescent  --  Set_Icon_Size
312     ("Applications should respect user preferences (gtk+ themes)");
313
314   procedure Unset_Icon_Size (Toolbar : access Gtk_Toolbar_Record);
315   pragma Obsolescent;  --  Unset_Icon_Size
316   --  Unsets icon sizes set through Set_Icon_Size, so that user preferences
317   --  set through the gtk+ theme are used
318
319   --  </doc_ignore>
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   --  <properties>
328   --  Name: Orientation_Property
329   --  Type: Gtk_Orientation
330   --  See:  Set_Orientation / Get_Orientation
331   --
332   --  Name: Toolbar_Style_Property
333   --  Type: Gtk_Toolbar_Style
334   --  See:  Set_Style / Get_Style
335   --
336   --  Name: Show_Arrow_Property
337   --  Type: Boolean
338   --  See:  Set_Show_Arrow / Get_Show_Arrow
339   --
340   --  Name: Tooltips_Property
341   --  Type: Boolean
342   --  See : Set_Tooltips / Get_Tooltips
343   --  </properties>
344
345   Orientation_Property   : constant Gtk.Enums.Property_Gtk_Orientation;
346   Toolbar_Style_Property : constant Gtk.Enums.Property_Gtk_Toolbar_Style;
347   Show_Arrow_Property    : constant Glib.Properties.Property_Boolean;
348   Tooltips_Property      : constant Glib.Properties.Property_Boolean;
349
350   ----------------------
351   -- Child Properties --
352   ----------------------
353   --  The following properties can be set on children of this widget. See
354   --  in particular Gtk.Containers.Child_Set_Property.
355
356   --  <child_properties>
357   --  Name:  Expand_Property
358   --  Type:  Boolean
359   --  Descr: Whether the item should receive extra space when the toolbar
360   --        grows
361   --
362   --  Name:  Homogeneous_Property
363   --  Type:  Boolean
364   --  Descr: Whether the item should be the same size as other homogeneous
365   --        items
366   --  </child_properties>
367
368   Expand_Property      : constant Glib.Properties.Property_Boolean;
369   Homogeneous_Property : constant Glib.Properties.Property_Boolean;
370
371   ----------------------
372   -- Style Properties --
373   ----------------------
374   --  The following properties can be changed through the gtk theme and
375   --  configuration files, and retrieved through Gtk.Widget.Style_Get_Property
376
377   --  <style_properties>
378   --  Name:  Button_Relief_Property
379   --  Type:  Enum
380   --  Descr: Type of bevel around toolbar buttons
381   --
382   --  Name:  Internal_Padding_Property
383   --  Type:  Int
384   --  Descr: Amount of border space between the toolbar shadow and the buttons
385   --
386   --  Name:  Shadow_Type_Property
387   --  Type:  Enum
388   --  Descr: Style of bevel around the toolbar
389   --
390   --  Name:  Space_Size_Property
391   --  Type:  Int
392   --  Descr: Size of spacers
393   --
394   --  Name:  Space_Style_Property
395   --  Type:  Enum
396   --  Descr: Whether spacers are vertical lines or just blank
397   --  </style_properties>
398
399   Button_Relief_Property    : constant Gtk.Enums.Property_Gtk_Relief_Style;
400   Internal_Padding_Property : constant Glib.Properties.Property_Int;
401   Shadow_Type_Property      : constant Gtk.Enums.Property_Gtk_Shadow_Type;
402   Space_Size_Property       : constant Glib.Properties.Property_Int;
403   Space_Style_Property      : constant Gtk.Enums.Property_Toolbar_Space_Style;
404   Icon_Size_Property        : constant Gtk.Enums.Property_Gtk_Icon_Size;
405
406   -------------
407   -- Signals --
408   -------------
409
410   --  <signals>
411   --  The following new signals are defined for this widget:
412   --
413   --  - "orientation-changed"
414   --    procedure Handler
415   --      (Toolbar     : access Gtk_Toolbar_Record'Class;
416   --       Orientation : Gtk_Orientation);
417   --    Emitted when the orientation of the toolbar changes
418   --
419   --  - "style-changed"
420   --    procedure Handler
421   --      (Toolbar     : access Gtk_Toolbar_Record'Class;
422   --       Style       : Gtk_Toolbar_Style);
423   --    Emitted when the style of the toolbar changes
424   --
425   --  - "popup_context_menu"
426   --    function Handler
427   --      (Toolbar      : access Gtk_Toolbar_Record'Class;
428   --       X, Y, Button : Gint) return Boolean;
429   --    Emitted when the user right-clicks the toolbar or uses the keybinding
430   --    to display a popup menu.
431   --    Application developers should handle this signal if they want to
432   --    display a context menu on the toolbar. The context-menu should appear
433   --    at the coordinates given by (x, y). The mouse button number is given
434   --    by the Button parameter (set to -1 if popped up with the keyboard).
435   --    Return value is True if the signal was handled.
436   --
437   --  - "move_focus"
438   --    This signal can't be used in application code, it is internal to GTK
439   --
440   --  - "focus_home_or_end"
441   --    function Handler
442   --       (Toolbar    : access Gtk_Toolbar_Record'Class;
443   --        Focus_Home : Boolean) return Boolean;
444   --    A keybinding signal used internally by GTK+. This signal can't be used
445   --    in application code
446   --
447   --  </signals>
448
449   Signal_Orientation_Changed : constant Glib.Signal_Name :=
450                                  "orientation-changed";
451   Signal_Style_Changed       : constant Glib.Signal_Name :=
452                                  "style-changed";
453   Signal_Popup_Context_Menu  : constant Glib.Signal_Name :=
454                                  "popup_context_menu";
455   Signal_Focus_Home_Or_End   : constant Glib.Signal_Name :=
456                                  "focus_home_or_end";
457   Signal_Move_Focus          : constant Glib.Signal_Name :=
458                                  "move_focus";
459
460private
461   type Gtk_Toolbar_Record is
462     new Gtk.Container.Gtk_Container_Record with null record;
463
464   Orientation_Property   : constant Gtk.Enums.Property_Gtk_Orientation :=
465     Gtk.Enums.Build ("orientation");
466   Toolbar_Style_Property : constant Gtk.Enums.Property_Gtk_Toolbar_Style :=
467     Gtk.Enums.Build ("toolbar-style");
468   Show_Arrow_Property    : constant Glib.Properties.Property_Boolean :=
469     Glib.Properties.Build ("show-arrow");
470   Tooltips_Property : constant Glib.Properties.Property_Boolean :=
471     Glib.Properties.Build ("tooltips");
472
473   Expand_Property : constant Glib.Properties.Property_Boolean :=
474     Glib.Properties.Build ("expand");
475   Homogeneous_Property : constant Glib.Properties.Property_Boolean :=
476     Glib.Properties.Build ("homogeneous");
477
478   Button_Relief_Property : constant Gtk.Enums.Property_Gtk_Relief_Style :=
479     Gtk.Enums.Build ("button-relief");
480   Internal_Padding_Property : constant Glib.Properties.Property_Int :=
481     Glib.Properties.Build ("internal-padding");
482   Shadow_Type_Property : constant Gtk.Enums.Property_Gtk_Shadow_Type :=
483     Gtk.Enums.Build ("shadow-type");
484   Icon_Size_Property : constant Gtk.Enums.Property_Gtk_Icon_Size :=
485     Gtk.Enums.Build ("icon-size");
486   Space_Size_Property : constant Glib.Properties.Property_Int :=
487     Glib.Properties.Build ("space-size");
488   Space_Style_Property : constant Gtk.Enums.Property_Toolbar_Space_Style :=
489     Gtk.Enums.Build ("space-style");
490
491   pragma Import (C, Get_Type, "gtk_toolbar_get_type");
492end Gtk.Toolbar;
493