2004-07-02 Mike Kestner <mkestner@ximian.com>

* en/GLib/*.xml : docs for Boxed, ConnectBeforeAttribute, and
	DefaultSignalHandlerAttribute.

svn path=/trunk/gtk-sharp/; revision=30679

doc/ChangeLog

@@ -1,3 +1,8 @@
+2004-07-02  Mike Kestner  <mkestner@ximian.com>
+
+	* en/GLib/*.xml : docs for Boxed, ConnectBeforeAttribute, and 
+	DefaultSignalHandlerAttribute.
+
 2004-07-02  Peter Johanson <latexer@gentoo.org>
 
 	* en/Art/*.xml : docs for some Art API.

doc/en/GLib/Boxed.xml

@@ -11,8 +11,7 @@
   <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>An abstract base class to derive structures and marshal them.</summary>
-    <remarks>
+    <remarks>This class is not used by the generator as of 1.0 and will be removed in future versions.</remarks>
-    </remarks>
   </Docs>
   <Base>
     <BaseTypeName>System.Object</BaseTypeName>
@@ -57,9 +56,9 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added</summary>
+        <summary>Do not use.</summary>
         <returns>a <see cref="T:System.IntPtr" /></returns>
-        <remarks>To be added</remarks>
+        <remarks>Do not use.</remarks>
       </Docs>
     </Member>
     <Member MemberName="Obj">
@@ -70,9 +69,9 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added</summary>
+        <summary>Do not use.</summary>
         <returns>a <see cref="T:System.Object" /></returns>
-        <remarks>To be added</remarks>
+        <remarks>Do not use.</remarks>
       </Docs>
     </Member>
   </Members>

doc/en/GLib/ConnectBeforeAttribute.xml

@@ -9,8 +9,32 @@
   </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>
+    <summary>Identifies a delegate to run before the default signal handler.</summary>
-    <remarks>To be added</remarks>
+    <remarks>
+      <para>
+	Use this attribute to attach an event handler to an object and cause it to be invoked before the default signal handler of the object.   While this mechanism can be used to pierce the object's encapsulation and change the behavior of the object without subclassing it, the cleaner approach would be to subclass the object and override the virtual method for the default signal handler.
+</para>
+      <para>
+	In the following example, the ButtonClicked method will be invoked before the <see cref="M:Gtk.Button.OnClicked" /> virtual method is executed.
+</para>
+      <example>
+        <code lang="C#">
+public class Example {
+	public static int Main (string[] args)
+	{
+		Gtk.Button btn = new Gtk.Button ("Click me");
+		btn.Clicked = new EventHandler (ButtonClicked);
+	}
+
+	[GLib.ConnectBefore]
+	private void ButtonClicked (object o, EventArgs args)
+	{
+		Console.WriteLine ("Got Clicked");
+	}
+}
+  </code>
+      </example>
+    </remarks>
   </Docs>
   <Base>
     <BaseTypeName>System.Attribute</BaseTypeName>
@@ -24,9 +48,10 @@
       <ReturnValue />
       <Parameters />
       <Docs>
-        <summary>To be added</summary>
+        <summary>Public Constructor.</summary>
         <returns>a <see cref="T:GLib.ConnectBeforeAttribute" /></returns>
-        <remarks>To be added</remarks>
+        <remarks>
+        </remarks>
       </Docs>
     </Member>
   </Members>

doc/en/GLib/DefaultSignalHandlerAttribute.xml

@@ -10,8 +10,37 @@
   </AssemblyInfo>
   <ThreadSafetyStatement />
   <Docs>
-    <summary>To be added</summary>
+    <summary>Identifies a virtual class method on a GLib.Object subclass.</summary>
-    <remarks>To be added</remarks>
+    <remarks>
+      <para>
+When a virtual method tagged with this attribute is overridden in a subclass, the method is automatically hooked into the native object's vtable.  For the most part, this is an internal implementation detail, but it can be used by binding code to manually identify GObject virtual methods that can be overridden by subclasses.
+</para>
+      <para>
+The following code identifies the ForAll method as an overridable native method on the <see cref="T:Gtk.Container" /> class. When a managed subclass of Container overrides the ForAll method, at type registration time, the OverrideForall method is invoked to connect up a delegate to the native GtkContainerClass::forall vtable slot.
+</para>
+      <example>
+        <code lang="C#">
+static void Forall_cb (IntPtr container, bool include_internals, IntPtr cb, IntPtr data)
+{
+        Container obj = GLib.Object.GetObject (container, false) as Container;
+        CallbackInvoker invoker = new CallbackInvoker (cb, data);
+        obj.ForAll (include_internals, invoker);
+}
+
+static void OverrideForall (GLib.GType gtype)
+{
+        if (ForallCallback == null)
+                ForallCallback = new ForallDelegate (Forall_cb);
+        gtksharp_container_override_forall (gtype, ForallCallback);
+}
+
+[GLib.DefaultSignalHandler (Type=typeof(Gtk.Container), ConnectionMethod="OverrideForall")]
+protected virtual void ForAll (bool include_internals, CallbackInvoker invoker)
+{
+        gtksharp_container_base_forall (Handle, include_internals, invoker.Callback, invoker.Data);
+} </code>
+      </example>
+    </remarks>
   </Docs>
   <Base>
     <BaseTypeName>System.Attribute</BaseTypeName>
@@ -25,9 +54,9 @@
       <ReturnValue />
       <Parameters />
       <Docs>
-        <summary>To be added</summary>
+        <summary>Public Constructor.</summary>
         <returns>a <see cref="T:GLib.DefaultSignalHandlerAttribute" /></returns>
-        <remarks>To be added</remarks>
+        <remarks />
       </Docs>
     </Member>
     <Member MemberName="ConnectionMethod">
@@ -38,9 +67,9 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added</summary>
+        <summary>The method to invoke to hook into the native object's vtable.</summary>
-        <returns>a <see cref="T:System.String" /></returns>
+        <returns>a <see cref="T:System.String" /> representing the method name to invoke.</returns>
-        <remarks>To be added</remarks>
+        <remarks>This method is invoked during type registration to hook up a callback delegate into the native object's vtable for virtual methods.</remarks>
       </Docs>
     </Member>
     <Member MemberName="Type">
@@ -51,9 +80,9 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added</summary>
+        <summary>The Type of the object which exposes the virtual method.</summary>
         <returns>a <see cref="T:System.Type" /></returns>
-        <remarks>To be added</remarks>
+        <remarks>The type registration code reflects on this type for the <see cref="M:GLib.DefaultSignalHandlerAttribute.ConnectionMethod" /> to invoke.</remarks>
       </Docs>
     </Member>
   </Members>