## Documentation

Table of Contents
Class Inheritance Tree
Widget Screenshots
Package groups

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

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

3.     --                                                                   --

4.     --                    Copyright (C) 2010, 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.     --  A Gtk_Link_Button is like a regular button with contents that

31.     --  appear like a web browser hyperlink.  It is associated with a

32.     --  URI.  The URI is passed to a callback procedure that is invoked

33.     --  when the user clicks the button.  This widget also keeps track of

34.     --  whether it has been clicked, and changes color after it has been

35.     --  visited.

36.     --  </description>

37.     --  <c_version>2.16.6</c_version>

38.     --  <group>Buttons and Toggles</group>

39.     --  <testgtk>create_link_buttons.adb</testgtk>

41.     with Interfaces.C.Strings;

43.     with Glib.PropertiesTo API docTo specTo body;

44.     with Gtk.ButtonTo API docTo specTo body;

45.     with Gtk.WidgetTo API docTo specTo body;      use Gtk.WidgetTo API docTo specTo body;

47.     package Gtk.Link_ButtonTo API docTo specTo body is

49.        type Gtk_Link_Button_RecordTo API docTo body is new

50.          Gtk.Button.Gtk_Button_RecordTo API docTo spec with private;

51.        type Gtk_Link_Button is access all Gtk_Link_Button_RecordTo API docTo specTo body'Class;

53.        function Get_TypeTo API docTo body return GTypeTo API docTo spec;

54.        --  Return the internal value associated with a Gtk_Link_Button.

56.        function Get_UriTo API docTo body

57.          (Link_Button : access Gtk_Link_Button_RecordTo API docTo specTo body) return String;

58.        --  Retrieves the URI set using Set_Uri.

59.        --  Return value: a valid URI.  The returned string is owned by the

60.        --  link button and should not be modified or freed.

62.        function Get_VisitedTo API docTo body

63.          (Link_Button : access Gtk_Link_Button_RecordTo API docTo specTo body) return Boolean;

64.        --  Retrieves the 'visited' state of the URI where the Link_Button

65.        --  points. The button becomes visited when it is clicked. If the URI

66.        --  is changed on the button, the 'visited' state is unset again.

67.        --

68.        --  The state may also be changed using Set_Visited.

69.        --

70.        --  Return value: True if the link has been visited, False otherwise

72.        procedure Gtk_NewTo API docTo body (Widget : out Gtk_Link_ButtonTo API docTo spec; Uri : String);

73.        --  Creates a new Gtk_Link_Button_Record with the URI as its text.

75.        procedure InitializeTo API docTo body

76.          (Widget : access Gtk_Link_Button_RecordTo API docTo specTo body'Class; Uri : String);

77.        --  Creates a new Gtk_Link_Button_Record with the URI as its text.

79.        procedure Gtk_New_With_LabelTo API docTo body

80.          (Widget : out Gtk_Link_ButtonTo API docTo spec;

81.           Uri    : String;

82.           Label  : String);

83.        --  Creates a new Gtk_Link_Button_Record containing a label.

85.        procedure Initialize_With_LabelTo API docTo body

86.          (Widget : access Gtk_Link_Button_RecordTo API docTo specTo body'Class;

87.           Uri    : String;

88.           Label  : String);

89.        --  Creates a new Gtk_Link_Button containing a label.

91.        procedure Set_UriTo API docTo body

92.          (Link_Button : access Gtk_Link_Button_RecordTo API docTo specTo body;

93.           Uri         : String);

94.        --  Sets Uri as the URI where the Gtk_Link_Button points. As a side-effect

95.        --  this unsets the 'visited' state of the button.

97.        type Uri_Func is access procedure

98.          (Button : System.Address;

99.           Link   : Interfaces.C.Strings.chars_ptr;

100.           Data   : System.Address);

101.        pragma Convention (C, Uri_FuncTo API docTo spec);

102.        --  This is a low-level callback function to be used with Set_Uri_Hook.

103.        --  See package Generic_Uri_Hook below for a higher-level interface.

104.        --

105.        --  You could convert the parameters to Ada types with the following

106.        --  declarations:

107.        --

108.        --     Stub        : Gtk_Link_Button_Record;

109.        --     Link_Button : constant Gtk_Link_Button :=

110.        --                     Gtk_Link_Button (Get_User_Data (Button, Stub));

111.        --     Link_String : constant String := Interfaces.C.Strings.Value (Link);

112.        --

113.        --  You'd also perform an appropriate conversion on Data using

114.        --  Ada.Unchecked_Conversion.

116.        function Set_Uri_HookTo API docTo body

117.          (Func    : Uri_FuncTo API docTo spec;

118.           Data    : System.Address;

119.           Destroy : G_Destroy_NotifyTo API docTo spec)

120.           return Uri_FuncTo API docTo spec;

121.        --  Func: a function called each time a Gtk_Link_Button is clicked, or null

122.        --  Data: user data to be passed to Func, or null

123.        --  Destroy: called when Data is no longer needed, or null

124.        --

125.        --  Sets Func as the subprogram that should be invoked every time a user

126.        --  clicks a Gtk_Link_Button. This function is called before every

127.        --  callback registered for the "clicked" signal.

128.        --

129.        --  Returns the previously set hook function.

131.        generic

132.           type Data_Type (<>) is private;

133.        package Generic_Uri_HookTo API docTo body is

134.           type Uri_Handler is access procedure

135.             (Button    : access Gtk_Link_Button_RecordTo API docTo specTo body'Class;

136.              Link      : UTF8_StringTo API docTo spec;

137.              User_Data : Data_TypeTo API docTo spec);

138.           --  A callback that is invoked when the user presses a hyperlink.

140.           type Destroy_Notify is access procedure (User_Data : in out Data_TypeTo API docTo spec);

141.           --  Destroy_Notify is called just prior to the destruction of

142.           --  User_Data.

144.           procedure Set_Uri_HookTo API docTo body

145.             (Handler   : Uri_HandlerTo API docTo spec;

146.              User_Data : Data_TypeTo API docTo spec;

147.              Destroy   : Destroy_NotifyTo API docTo spec);

148.           --  Sets Handler as the subprogram that should be invoked every time

149.           --  a user clicks a Gtk_Link_Button. This subprogram is called before

150.           --  every callback registered for the "clicked" signal.

151.           --

152.           --  If no uri hook has been set, GTK+ defaults to calling gtk_show_uri().

153.        end Generic_Uri_HookTo API docTo specTo body;

155.        procedure Set_VisitedTo API docTo body

156.          (Link_Button : access Gtk_Link_Button_RecordTo API docTo specTo body;

157.           Visited     : Boolean);

158.        --  Sets the 'visited' state of the URI where the #GtkLinkButton

159.        --  points.  See Get_Visited for more details.

161.        Uri_Property : constant Glib.Properties.Property_StringTo API docTo spec;

162.        Visited_Property : constant Glib.Properties.Property_BooleanTo API docTo spec;

164.     private

166.        type Gtk_Link_Button_RecordTo API docTo spec is new

167.          Gtk.Button.Gtk_Button_RecordTo API docTo spec with null record;

169.        Uri_PropertyTo API docTo spec : constant Glib.Properties.Property_StringTo API docTo spec :=

170.          Glib.Properties.BuildTo API docTo specTo body ("uri");

171.        Visited_PropertyTo API docTo spec : constant Glib.Properties.Property_BooleanTo API docTo spec :=

172.          Glib.Properties.BuildTo API docTo specTo body ("visited");

174.        pragma Import (C, Get_TypeTo API docTo spec, "gtk_link_button_get_type");

176.     end Gtk.Link_ButtonTo API docTo specTo body;