From 2efbf0e96a5f92cccdacac58d530879c4374b478 Mon Sep 17 00:00:00 2001
From: John Luke <jluke@mono-cvs.ximian.com>
Date: Sat, 10 May 2003 02:51:23 +0000
Subject: [PATCH] Add first draft for Tooltips.xml

svn path=/trunk/gtk-sharp/; revision=14434
---
 doc/ChangeLog           |  4 ++
 doc/en/Gtk/Tooltips.xml | 97 ++++++++++++++++++++++++++++++++---------
 2 files changed, 81 insertions(+), 20 deletions(-)

diff --git a/doc/ChangeLog b/doc/ChangeLog
index f64e257e7..61e638b78 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,7 @@
+2003-05-09  John Luke  <jluke@cfl.rr.com>
+
+	* en/Gtk/ToolTips.xml: Add first draft, example.
+
 2003-05-08  Lee Mallabone  <gnome@fonicmonkey.net>
 
 	* en/Gtk/*.xml:
diff --git a/doc/en/Gtk/Tooltips.xml b/doc/en/Gtk/Tooltips.xml
index a8ff6fac7..e9623c520 100644
--- a/doc/en/Gtk/Tooltips.xml
+++ b/doc/en/Gtk/Tooltips.xml
@@ -7,8 +7,62 @@
   </AssemblyInfo>
   <ThreadSafetyStatement>Gtk# is thread aware, but not thread safe; See the <link location="node:gtk-sharp/programming/threads">Gtk# Thread Programming</link> for details.</ThreadSafetyStatement>
   <Docs>
-    <summary>To be added</summary>
-    <remarks>To be added</remarks>
+    <summary>Add Tooltips to your widgets.</summary>
+    <remarks>
+			<para>Tooltips are the messages that appear next to a widget when the mouse pointer is held over it for a short amount of time.
+				They are especially helpful for adding more verbose descriptions of things such as <see cref="T:Gtk.Button"/> in a toolbar.</para>
+			<para>An individual tooltip belongs to a group of tooltips.
+				A group is created by calling the constructor <see cref="C:Gtk.Tooltips()"/>.
+				Every tooltip in the group can then be turned off with <see cref="M:Gtk.Tooltips.Disable()"/> and on with <see cref="M:Gtk.Tooltips.Enable()"/>.</para>
+			<para>To assign a tip to a particular <see cref="T:Gtk.Widget"/>, <see cref="M:Gtk.Tooltips.SetTip(widget, string, string)"/> is used.</para>
+			<para>Note: Tooltips can only be set on widgets which have their own X window.
+				To add a tooltip to a <see cref="T:Gtk.Widget"/> that does not have its own <see cref="T:Gtk.Window"/>, place the widget inside a <see cref="T:Gtk.EventBox"/> and add a tooltip to that instead.</para>
+			<para>The default appearance of all tooltips in a program is determined by the current Gtk theme that the user has selected.</para>
+			<example>
+				<code lang="C#">
+using Gtk;
+using GtkSharp;
+ 
+class ToolTipsExample
+{
+        static void Main()
+        {
+ 
+                Application.Init();
+ 
+                Window win = new Window("Tooltips");
+                Button load_button, save_button;
+                HBox hbox;
+                Tooltips button_bar_tips;
+    
+                button_bar_tips = new Tooltips ();
+    
+                // Create the buttons and pack them into a Gtk.HBox
+                hbox = new HBox (true, 2);
+                win.Add(hbox);
+ 
+                load_button = new Button ("Load a file");
+                hbox.Add(load_button);
+    
+                save_button = new Button ("Save a file");
+                hbox.Add(save_button);
+    
+                // Add the tips
+                button_bar_tips.SetTip (load_button,
+                        "Load a new document into this window",
+                        "longer explanation");
+                
+		button_bar_tips.SetTip (save_button,
+                        "Saves the current document to a file",
+                        "longer explanation");
+                
+		win.ShowAll();
+                Application.Run();
+        }
+}
+				</code>
+			</example>
+		</remarks>
   </Docs>
   <Base>
     <BaseTypeName>Gtk.Object</BaseTypeName>
@@ -31,8 +85,8 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added</summary>
-        <remarks>To be added</remarks>
+        <summary>Allows the user to see your tooltips as they navigate your application.</summary>
+        <remarks>Allows the user to see your tooltips as they navigate your application.</remarks>
       </Docs>
     </Member>
     <Member MemberName="Disable">
@@ -43,8 +97,9 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added</summary>
-        <remarks>To be added</remarks>
+        <summary>Causes all tooltips in the tooltips group to become inactive.</summary>
+        <remarks>Causes all tooltips in the tooltips group to become inactive.
+					Any widgets that have tips associated with that group will no longer display their tips until they are enabled again with <see cref="M:Gtk.Tooltips.Enable()"/>.</remarks>
       </Docs>
     </Member>
     <Member MemberName="ForceWindow">
@@ -55,8 +110,9 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added</summary>
-        <remarks>To be added</remarks>
+        <summary>Ensures that the window used for displaying the given tooltip is created.</summary>
+        <remarks>Ensures that the window used for displaying the given tooltip is created.
+					(Applications should never have to call this function, since Gtk# takes care of this.) </remarks>
       </Docs>
     </Member>
     <Member MemberName="SetTip">
@@ -71,11 +127,11 @@
         <Parameter Name="tip_private" Type="System.String" />
       </Parameters>
       <Docs>
-        <summary>To be added</summary>
-        <param name="widget">To be added: an object of type 'Gtk.Widget'</param>
-        <param name="tip_text">To be added: an object of type 'string'</param>
-        <param name="tip_private">To be added: an object of type 'string'</param>
-        <remarks>To be added</remarks>
+        <summary>Adds a tooltip containing the specified message to the specified <see cref="T:Gtk.Widget"/>.</summary>
+        <param name="widget">an object of type <see cref="T:Gtk.Widget"/></param>
+        <param name="tip_text">an object of type <see cref="System.String"/></param>
+        <param name="tip_private">an object of type <see cref="System.String"/></param>
+        <remarks>Adds a tooltip containing the specified message to the specified <see cref="T:Gtk.Widget"/>.</remarks>
       </Docs>
     </Member>
     <Member MemberName="Finalize">
@@ -112,9 +168,10 @@
       <ReturnValue />
       <Parameters />
       <Docs>
-        <summary>To be added</summary>
-        <returns>To be added: an object of type 'Gtk.Tooltips'</returns>
-        <remarks>To be added</remarks>
+        <summary>Creates an empty group of tooltips.</summary>
+        <returns>an object of type <see cref="T:Gtk.Tooltips"/></returns>
+        <remarks>Creates an empty group of tooltips. This function initializes a <see cref="T:Gtk.TooltipsData"/> structure.
+					Without at least one such structure, you can not add individual tips to your application.</remarks>
       </Docs>
     </Member>
     <Member MemberName="GType">
@@ -124,8 +181,8 @@
         <ReturnType>System.UInt32</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>The GLib Type for Gtk.Tooltips</summary>
-        <returns>The GLib Type for the Gtk.Tooltips class.</returns>
+        <summary>The <see cref="T:GLib.Type"/> for <see cref="T:Gtk.Tooltips"/></summary>
+        <returns>The <see cref="T:GLib.Type"/> for the <see cref="T:Gtk.Tooltips"/> class.</returns>
         <remarks />
       </Docs>
     </Member>
@@ -139,11 +196,11 @@
       <Docs>
         <summary>Internal constructor</summary>
         <param name="gtype">GLib type for the type</param>
-        <returns>Creates a new instance of Tooltips, using the GLib-provided type</returns>
+        <returns>Creates a new instance of <see cref="T:Gtk.Tooltips"/>, using the GLib-provided type</returns>
         <remarks>
           <para>This is a constructor used by derivative types of <see cref="T:Gtk.Tooltips" /> that would have their own GLib type assigned to it.  This is not typically used by C# code.</para>
         </remarks>
       </Docs>
     </Member>
   </Members>
-</Type>
\ No newline at end of file
+</Type>