[Gtk-sharp-list] ToggleButton Doc and Example

John Luke jluke@cfl.rr.com
24 Apr 2003 13:33:28 -0400


--=-LCSnwo9q0pyTw+eMuz1I
Content-Type: text/plain
Content-Transfer-Encoding: 7bit

Hello,

Here is a diff for gtk-sharp/doc/en/Gtk/ToggleButton.xml and an example
for the documentation.  Can someone commit it if it is ok?

Thanks,
John Luke

--=-LCSnwo9q0pyTw+eMuz1I
Content-Disposition: attachment; filename=ToggleButton.diff
Content-Type: text/x-patch; name=ToggleButton.diff; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit

Index: ToggleButton.xml
===================================================================
RCS file: /mono/gtk-sharp/doc/en/Gtk/ToggleButton.xml,v
retrieving revision 1.5
diff -u -p -r1.5 ToggleButton.xml
--- ToggleButton.xml	8 Mar 2003 06:28:11 -0000	1.5
+++ ToggleButton.xml	24 Apr 2003 00:28:23 -0000
@@ -7,8 +7,66 @@
   </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>A button that can be toggled on and off.</summary>
+    <remarks>
+	  <para>A <see cref="T:Gtk.ToggleButton"/> is a <see cref="T:Gtk.Button"/> which will remain 'pressed-in' when clicked.
+	  Clicking again will cause the toggle button to return to it's normal state.  This is useful if you need to maintain the state of a button.</para>
+	  <example>
+	    <code lang="C#" source="ToggleButton.cs">
+namespace GtkSamples {
+
+	using Gtk;
+	using GtkSharp;
+	using System;
+
+	public class ToggleButtonApp  {
+	
+		ToggleButton btn;
+
+		public static int Main (string[] args)
+		{
+			new ToggleButtonApp();
+			return 0;
+		}
+		
+		public ToggleButtonApp()
+		{
+			Application.Init ();
+			Window win = new Window ("ToggleButton Tester");
+			win.SetDefaultSize (200, 150);
+			win.DeleteEvent += new DeleteEventHandler (Window_Delete);
+			btn = new ToggleButton ("Unselected");
+			btn.Active = false;
+			btn.Toggled += new EventHandler (btn_toggled);
+			win.Add (btn);
+			win.ShowAll ();
+			Application.Run ();
+		}
+
+		void btn_toggled (object obj, EventArgs args)
+		{
+			Console.WriteLine ("Button Toggled");
+			if (btn.Active)
+			{
+				btn.Label = "Unselected";
+			}
+			else
+			{
+				btn.Label = "Selected";
+			}
+		}
+
+		static void Window_Delete (object obj, DeleteEventArgs args)
+		{
+			Application.Quit ();
+			args.RetVal = true;
+		}
+
+	}
+}
+		</code>
+	  </example>
+	</remarks>
   </Docs>
   <Base>
     <BaseTypeName>Gtk.Button</BaseTypeName>
@@ -39,10 +97,10 @@
         <Parameter Name="label" Type="System.String" />
       </Parameters>
       <Docs>
-        <summary>To be added</summary>
-        <param name="label">To be added: an object of type 'string'</param>
-        <returns>To be added: an object of type 'Gtk.ToggleButton'</returns>
-        <remarks>To be added</remarks>
+        <summary>Creates a new <see cref="T:Gtk.ToggleButton"/> with a text label.</summary>
+        <param name="label">a <see cref="T:System.String"/> containing the message to be placed in the toggle button.</param>
+        <returns>a new <see cref="T:Gtk.ToggleButton"/>.</returns>
+        <remarks>Creates a new <see cref="T:Gtk.ToggleButton"/> with a text label.</remarks>
       </Docs>
     </Member>
     <Member MemberName="Toggle">
@@ -53,8 +111,8 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added</summary>
-        <remarks>To be added</remarks>
+        <summary>Emits the <see cref="E:Gtk.ToggleButton.Toggled"/> event</summary>
+        <remarks>Emits the <see cref="E:Gtk.ToggleButton.Toggled"/> event on the <see cref="T:Gtk.ToggleButton"/>. There is no good reason for an application ever to call this function.</remarks>
       </Docs>
     </Member>
     <Member MemberName="Finalize">
@@ -79,7 +137,7 @@
       <Docs>
         <summary>Internal constructor</summary>
         <param name="raw">Pointer to the C object.</param>
-        <returns>An instance of ToggleButton, wrapping the C object.</returns>
+        <returns>An instance of <see cref="T:Gtk.ToggleButton"/>, wrapping the C object.</returns>
         <remarks>
           <para>This is an internal constructor, and should not be used by user code.</para>
         </remarks>
@@ -91,9 +149,9 @@
       <ReturnValue />
       <Parameters />
       <Docs>
-        <summary>To be added</summary>
-        <returns>To be added: an object of type 'Gtk.ToggleButton'</returns>
-        <remarks>To be added</remarks>
+        <summary>Creates a new <see cref="T:Gtk.ToggleButton"/> object</summary>
+        <returns>an object of type <see cref="T:Gtk.ToggleButton"/></returns>
+        <remarks>Creates a new <see cref="T:Gtk.ToggleButton"/>. A widget should be packed into the button, using <see cref="M:Gtk.ToggleButton.NewWithLabel (string label)"/>.</remarks>
       </Docs>
     </Member>
     <Member MemberName=".ctor">
@@ -104,10 +162,10 @@
         <Parameter Name="label" Type="System.String" />
       </Parameters>
       <Docs>
-        <summary>To be added</summary>
-        <param name="label">To be added: an object of type 'string'</param>
-        <returns>To be added: an object of type 'Gtk.ToggleButton'</returns>
-        <remarks>To be added</remarks>
+        <summary>Creates a new <see cref="T:Gtk.ToggleButton"/> with a text label.</summary>
+        <param name="label">a <see cref="T:System.String"/> containing the message to be placed in the toggle button.</param>
+        <returns>an object of type '<see cref="T:Gtk.ToggleButton"/></returns>
+        <remarks>Creates a new <see cref="T:Gtk.ToggleButton"/> with a text label.</remarks>
       </Docs>
     </Member>
     <Member MemberName="GType">
@@ -117,8 +175,8 @@
         <ReturnType>System.UInt32</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>The GLib Type for Gtk.ToggleButton</summary>
-        <returns>The GLib Type for the Gtk.ToggleButton class.</returns>
+        <summary>The <see cref="T:GLib.Type"/> for <see cref="T:Gtk.ToggleButton"/></summary>
+        <returns>The <see cref="T:GLib.Type"/> for the <see cref="T:Gtk.ToggleButton"/></returns>
         <remarks />
       </Docs>
     </Member>
@@ -132,10 +190,18 @@
         <Parameter Name="value" Type="System.Boolean" />
       </Parameters>
       <Docs>
-        <summary>To be added</summary>
-        <param name="value">To be added: an object of type 'bool'</param>
-        <returns>To be added: an object of type 'bool'</returns>
-        <remarks>To be added</remarks>
+        <summary>The Mode of the <see cref="T:Gtk.ToggleButton"/></summary>
+        <param name="value">an object of type <see cref="T:System.Boolean" /></param>
+        <returns>an object of type <see cref="T:System.Boolean" /></returns>
+        <remarks>
+		  		<para>The Mode of the <see cref="T:Gtk.ToggleButton"/></para>
+		  		<para>Sets whether the button is displayed as a separate indicator and label.
+		    		You can call this function on a <see cref="Gtk.CheckButton"/> or a <see cref="Gtk.RadioButton"/> with <see cref="P:Gtk.ToggleButton.DrawIndicator"/> = <see langword="false"/> to make the button look like a normal button
+		  		</para>
+		  		<para>This function only effects instances of classes like <see cref="Gtk.CheckButton"/> and <see cref="Gtk.RadioButton"/>
+		    		that derive from <see cref="T:Gtk.ToggleButton"/>, not instances of <see cref="T:Gtk.ToggleButton"/> itself.
+		  		</para>
+				</remarks>
       </Docs>
     </Member>
     <Member MemberName="Inconsistent">
@@ -148,10 +214,17 @@
         <Parameter Name="value" Type="System.Boolean" />
       </Parameters>
       <Docs>
-        <summary>To be added</summary>
-        <param name="value">To be added: an object of type 'bool'</param>
-        <returns>To be added: an object of type 'bool'</returns>
-        <remarks>To be added</remarks>
+        <summary>Determines if the <see cref="T:Gtk.ToggleButton"/> has an intermediate state.</summary>
+        <param name="value">an object of type 'bool'</param>
+        <returns>an object of type <see cref="T:System.Boolean" /></returns>
+        <remarks>
+					<para>
+						If the user has selected a range of elements (such as some text or spreadsheet cells) that are affected by a toggle button,
+						and the current values in that range are inconsistent, you may want to display the toggle in an "in between" state.
+						This function turns on "in between" display. Normally you would turn off the inconsistent state again if the user toggles the toggle button.
+						This has to be done manually, <see cref="P:Gtk.ToggleButton.Inconsistent"/> only affects visual appearance, it doesn't affect the semantics of the button.
+					</para>
+				</remarks>
       </Docs>
     </Member>
     <Member MemberName="Active">
@@ -164,10 +237,18 @@
         <Parameter Name="value" Type="System.Boolean" />
       </Parameters>
       <Docs>
-        <summary>To be added</summary>
-        <param name="value">To be added: an object of type 'bool'</param>
-        <returns>To be added: an object of type 'bool'</returns>
-        <remarks>To be added</remarks>
+        <summary>Get or set the <see cref="T:Gtk.ToggleButton"/> active</summary>
+        <param name="value">an object of type 'bool'</param>
+        <returns>an object of type <see cref="T:System.Boolean" /></returns>
+        <remarks>
+		  		<para>Get or set the <see cref="T:Gtk.ToggleButton"/> active.</para>
+		  		<para>Get: Queries a GtkToggleButton and returns it's current state.
+						Returns <see langword="true"/> if the toggle button is pressed in and <see langword="false"/> if it is raised.
+					</para>
+					<para>Set: Sets the status of the toggle button. Set to <see langword="true"/> if you want the GtkToggleButton to be 'pressed in', and <see langword="false"/> to raise it.
+						This action causes the toggled signal to be emitted.
+					</para>
+				</remarks>
       </Docs>
     </Member>
     <Member MemberName="DrawIndicator">
@@ -180,10 +261,12 @@
         <Parameter Name="value" Type="System.Boolean" />
       </Parameters>
       <Docs>
-        <summary>To be added</summary>
-        <param name="value">To be added: an object of type 'bool'</param>
-        <returns>To be added: an object of type 'bool'</returns>
-        <remarks>To be added</remarks>
+        <summary>The DrawIndicator property</summary>
+        <param name="value">an object of type <see cref="T:System.Boolean"/></param>
+        <returns>an object of type <see cref="T:System.Boolean"/></returns>
+        <remarks>The DrawIndicator property can be set to <see langword="false"/> to make 
+					<see cref="T:Gtk.CheckButton"/> or <see cref="T:GtkRadioButton"/> look like a normal <see cref="T:Gtk.Button"/>.
+				</remarks>
       </Docs>
     </Member>
     <Member MemberName="Toggled">
@@ -192,8 +275,8 @@
       <ReturnValue />
       <Parameters />
       <Docs>
-        <summary>To be added</summary>
-        <remarks>To be added</remarks>
+        <summary>Triggered when the <see cref="T:Gtk.ToggleButton"/> is clicked.</summary>
+        <remarks>Should be connected if you wish to perform an action whenever the <see cref="T:Gtk.ToggleButton"/>'s state is changed.</remarks>
       </Docs>
     </Member>
     <Member MemberName=".ctor">
@@ -206,11 +289,11 @@
       <Docs>
         <summary>Internal constructor</summary>
         <param name="gtype">GLib type for the type</param>
-        <returns>Creates a new instance of ToggleButton, using the GLib-provided type</returns>
+        <returns>Creates a new instance of <see cref="T:Gtk.ToggleButton"/>, using the GLib-provided type</returns>
         <remarks>
-          <para>This is a constructor used by derivative types of <see cref="T:Gtk.ToggleButton" /> that would have their own GLib type assigned to it.  This is not typically used by C# code.</para>
+          <para>This is a constructor used by derivative types of <see cref="T:Gtk.ToggleButton" /> that would have their own <see cref="T: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>

--=-LCSnwo9q0pyTw+eMuz1I
Content-Disposition: attachment; filename=ToggleButton.cs
Content-Type: text/plain; name=ToggleButton.cs; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit

namespace GtkSamples {

	using Gtk;
	using GtkSharp;
	using System;

	public class ToggleButtonApp  {
	
		ToggleButton btn;

		public static int Main (string[] args)
		{
			new ToggleButtonApp();
			return 0;
		}
		
		public ToggleButtonApp()
		{
			Application.Init ();
			Window win = new Window ("ToggleButton Tester");
			win.SetDefaultSize (200, 150);
			win.DeleteEvent += new DeleteEventHandler (Window_Delete);
			btn = new ToggleButton ("Unselected");
			btn.Active = false;
			btn.Toggled += new EventHandler (btn_toggled);
			win.Add (btn);
			win.ShowAll ();
			Application.Run ();
		}

		void btn_toggled (object obj, EventArgs args)
		{
			Console.WriteLine ("Button Toggled");
			if (btn.Active)
			{
				btn.Label = "Unselected";
			}
			else
			{
				btn.Label = "Selected";
			}
		}

		static void Window_Delete (object obj, DeleteEventArgs args)
		{
			Application.Quit ();
			args.RetVal = true;
		}

	}
}

--=-LCSnwo9q0pyTw+eMuz1I--