## Documentation

Table of Contents
Class Inheritance Tree
Widget Screenshots
Package groups

1.     -----------------------------------------------------------------------

2.     --               GtkAda - Ada95 binding for Gtk+/Gnome               --

3.     --                                                                   --

4.     --                 Copyright (C) 2001-2008, AdaCore                  --

5.     --                                                                   --

6.     -- This library is free software; you can redistribute it and/or     --

7.     -- modify it under the terms of the GNU General Public               --

8.     -- License as published by the Free Software Foundation; either      --

9.     -- version 2 of the License, or (at your option) any later version.  --

10.     --                                                                   --

11.     -- This library is distributed in the hope that it will be useful,   --

12.     -- but WITHOUT ANY WARRANTY; without even the implied warranty of    --

13.     -- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU --

14.     -- General Public License for more details.                          --

15.     --                                                                   --

16.     -- You should have received a copy of the GNU General Public         --

17.     -- License along with this library; if not, write to the             --

18.     -- Free Software Foundation, Inc., 59 Temple Place - Suite 330,      --

19.     -- Boston, MA 02111-1307, USA.                                       --

20.     --                                                                   --

21.     -- As a special exception, if other files instantiate generics from  --

22.     -- this unit, or you link this unit with other files to produce an   --

23.     -- executable, this  unit  does not  by itself cause  the resulting  --

24.     -- executable to be covered by the GNU General Public License. This  --

25.     -- exception does not however invalidate any other reasons why the   --

26.     -- executable file  might be covered by the  GNU Public License.     --

27.     -----------------------------------------------------------------------

29.     --  <description>

30.     --  Note: this package need only be used and understood by people who

31.     --  want to create their own new widgets and their associated properties.

32.     --  Normal usage of properties doesn't require any deep understanding of

33.     --  this package.

34.     --

35.     --  This package provides two generic subpackages that make it easy to

36.     --  declare properties.

37.     --  Each of these packages define two types:

38.     --

39.     --  - Property_RO : this type should be used for a read-only property

40.     --                  of the given type.

41.     --  - Property    : This is for read-write properties

42.     --

43.     --  Each of these two types is associated with one or two primitive

44.     --  operations Get_Property and Set_Property, that allows the modification

45.     --  of properties of this type.

46.     --

47.     --  As a user and creator of new widgets, you should always use the

48.     --  Generic_Enumeration_Property package, since it also registers the

49.     --  enumeration type with gtk+ for a full compatibility with C.

50.     --  </description>

51.     --  <group>Glib, the general-purpose library</group>

53.     with Glib.ObjectTo API docTo specTo body;

54.     with Glib.ValuesTo API docTo specTo body;

56.     package Glib.Generic_PropertiesTo API docTo specTo body is

58.        --------------------------------------------------

59.        -- Generic package for discrete type properties --

60.        --------------------------------------------------

61.        --  This package should be used to implement the

62.        --  Get_Property and Set_Property subprograms for all

63.        --  properties related to enumeration types and simple

64.        --  types.

65.        --  This should be used only for types defined in GtkAda

66.        --  or gtk+ themselves, not for types that you define

67.        --  yourself. Use Generic_Discrete_Type instead.

69.        generic

70.           type Discrete_Type is (<>);

71.        package Generic_Internal_Discrete_PropertyTo API docTo body is

72.           type Property_RO is new Glib.PropertyTo API docTo spec;

73.           type Property is new Glib.PropertyTo API docTo spec;

75.           procedure Set_PropertyTo API docTo body

76.             (Object : access Glib.Object.GObject_RecordTo API docTo specTo body'Class;

77.              Name   : PropertyTo API docTo spec;

78.              Value  : Discrete_TypeTo API docTo spec);

79.           --  Set a property of Object based on Enumeration_Type.

81.           function Get_PropertyTo API docTo body

82.             (Object : access Glib.Object.GObject_RecordTo API docTo specTo body'Class;

83.              Name   : PropertyTo API docTo spec) return Discrete_TypeTo API docTo spec;

84.           pragma Inline (Get_PropertyTo API docTo specTo body);

86.           function Get_PropertyTo API docTo body

87.             (Object : access Glib.Object.GObject_RecordTo API docTo specTo body'Class;

88.              Name   : Property_ROTo API docTo spec) return Discrete_TypeTo API docTo spec;

89.           --  Get a property from Object

91.        end Generic_Internal_Discrete_PropertyTo API docTo specTo body;

93.        -------------------------------------------------

94.        -- Generic package for enumerations properties --

95.        -------------------------------------------------

96.        --  This package should be used to implement the

97.        --  Get_Property and Set_Property subprograms for all

98.        --  properties related to enumeration types and simple

99.        --  types in users' applications.

100.        --  Name is the name registered in gtk+ for the type. This is also

101.        --  the name that appears in all the tools that use introspection

102.        --  to get information about the widgets and their properties, like

103.        --  GUI builders for instance

104.        --

105.        --  !!IMPORTANT!!: For proper usage of properties based on enumeration

106.        --  types, you must specify the Convention C on the type:

107.        --      pragma Convention (C, Enumeration_Type);

109.        generic

110.           Name : String;

111.           type Enumeration is (<>);

112.        package Generic_Enumeration_PropertyTo API docTo body is

114.           -----------------

115.           --  Properties --

116.           -----------------

118.           package Properties is new Generic_Internal_Discrete_PropertyTo API docTo specTo body

119.             (EnumerationTo API docTo spec);

120.           type Property_RO is new Properties.Property_ROTo API docTo spec;

121.           type Property    is new Properties.PropertyTo API docTo spec;

123.           -----------

124.           -- Types --

125.           -----------

127.           function Get_TypeTo API docTo body return Glib.GTypeTo API docTo spec;

128.           --  Return the internal gtk+ type associated with the Ada enumeration

129.           --  Enumeration. You don't need to use such a function for the types

130.           --  defined in standard in GtkAda. Use Glib.Type_From_Name

131.           --  instead.

133.           function Gnew_EnumTo API docTo body

134.             (Name, Nick, Blurb   : String;

135.              Default             : EnumerationTo API docTo spec := EnumerationTo API docTo spec'First;

136.              Flags : Param_FlagsTo API docTo spec := Param_ReadableTo API docTo spec or Param_WritableTo API docTo spec)

137.              return Param_SpecTo API docTo spec;

138.           --  Create a new param_spec (to describe properties), based on the

139.           --  Ada enumeration type Enumeration. This function is used when

140.           --  creating the property with Install_Property on an object.

141.           --  Name, Nick and Blurb should describe the property, not its type.

143.           ------------

144.           -- Values --

145.           ------------

147.           function Get_EnumTo API docTo body (Value : Glib.Values.GValueTo API docTo specTo body) return EnumerationTo API docTo spec;

148.           --  Return the enumeration contained in Value, assuming it is of type

149.           --  Enumeration

151.           procedure Set_EnumTo API docTo body

152.             (ValueTo API docTo body : in out Glib.Values.GValueTo API docTo specTo body; Enum : EnumerationTo API docTo spec);

153.           --  Set the enumeration value for Value. This properly initializes the

154.           --  type of Value, so you don't need to call Init yourself.

156.        private

157.           The_Type : Glib.GTypeTo API docTo spec := Glib.GType_InvalidTo API docTo spec;

158.           pragma Import (C, Get_EnumTo API docTo spec, "g_value_get_enum");

159.        end Generic_Enumeration_PropertyTo API docTo specTo body;

161.        -------------------------------------------------

162.        -- Generic package for record types properties --

163.        -------------------------------------------------

164.        --  This package should be used to implement the

165.        --  Get_Property and Set_Property subprograms for all

166.        --  properties related to record type, like Gdk_Color and

167.        --  Gdk_Rectangle.

168.        --  This should be used only for types defined in GtkAda

169.        --  or gtk+ themselves, not for types that you define

170.        --  yourself.

172.        generic

173.           type Boxed_Type is private;

174.           with function Get_Type return Glib.GTypeTo API docTo spec;

176.           with function To_Address

177.             (B : Boxed_TypeTo API docTo spec; Default : System.Address) return System.Address;

178.           --  Convert B into an address that can be passed to gtk+.

179.           --  Default is the address of the parameters passed by the user (since

180.           --  this function cannot return B'Address, where B might be passed by

181.           --  copy).

183.        package Generic_Internal_Boxed_PropertyTo API docTo body is

184.           type Property_RO is new Glib.PropertyTo API docTo spec;

185.           type Property    is new Glib.PropertyTo API docTo spec;

187.           procedure Set_PropertyTo API docTo body

188.             (Object : access Glib.Object.GObject_RecordTo API docTo specTo body'Class;

189.              Name   : PropertyTo API docTo spec;

190.              Value  : Boxed_TypeTo API docTo spec);

191.           --  Set a property of Object based on Enumeration_Type.

193.           function Get_PropertyTo API docTo body

194.             (Object : access Glib.Object.GObject_RecordTo API docTo specTo body'Class;

195.              Name   : PropertyTo API docTo spec) return Boxed_TypeTo API docTo spec;

196.           pragma Inline (Get_PropertyTo API docTo specTo body);

198.           function Get_PropertyTo API docTo body

199.             (Object : access Glib.Object.GObject_RecordTo API docTo specTo body'Class;

200.              Name   : Property_ROTo API docTo spec) return Boxed_TypeTo API docTo spec;

201.           --  Get a property from Object.

202.           --  Unset_Value is raised if the property is not set

204.           procedure Set_ValueTo API docTo body

205.             (ValueTo API docTo body  : out Glib.Values.GValueTo API docTo specTo body;

206.              Val    : Boxed_TypeTo API docTo spec);

207.           --  Store Val in Value. The latter is properly initialized, and reference

208.           --  counting is handled automatically. You must Unset Value when you are

209.           --  done using it.

211.           function Get_ValueTo API docTo body (ValueTo API docTo body : Glib.Values.GValueTo API docTo specTo body) return Boxed_TypeTo API docTo spec;

212.           --  Get the value stored in Value. Reference counting is automatically

213.           --  handled, and the returned value has been properly referenced.

214.           --  Unset_Value is raised if Value contains no data

216.        end Generic_Internal_Boxed_PropertyTo API docTo specTo body;

218.        Unset_Value : exception;

220.     end Glib.Generic_PropertiesTo API docTo specTo body;