GtkSharp/doc/en/Gtk/SpinButton.xml

<Type Name="SpinButton" FullName="Gtk.SpinButton">
  <TypeSignature Language="C#" Maintainer="Lee Mallabone" Value="public class SpinButton : Gtk.Entry" />
  <AssemblyInfo>
    <AssemblyName>gtk-sharp</AssemblyName>
    <AssemblyPublicKey>
    </AssemblyPublicKey>
    <AssemblyVersion>2.12.0.0</AssemblyVersion>
  </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>Retrieve an integer or floating-point number from the user.</summary>
    <remarks>
      <para>A SpinButton is an ideal way to allow the user to enter a numeric value. Rather than having to directly type a number into an <see cref="T:Gtk.Entry" />, a SpinButton allows the user to click on one of two arrows to increment or decrement the displayed value. A value can still be typed in, with the added benefit that it can be checked to ensure it is within a given range.</para>
      <para>To precisely configure a SpinButton, an <see cref="T:Gtk.Adjustment" /> is used. Though it is not mandatory, its use allows fine control over the 'spinning' properties of the SpinButton.</para>
      <para>A SpinButton is typically created by setting up an <see cref="T:Gtk.Adjustment" /> and passing that to the SpinButton's constructor. The value entered by a user can then be retrieved using either the <see cref="P:Gtk.SpinButton.Value" /> property or the <see cref="P:Gtk.SpinButton.ValueAsInt" /> property.</para>
      <para>The following demonstrates how to get an integer from a SpinButton:
    <example><code lang="C#">

// Creates a window with a spin button
public void CreateSpinButton() 
{
    Window window = new Window();
    window.BorderWidth = 5;
    // Create a spin button for percentage values.
    SpinButton spinner = new SpinButton(0f, 100f, 1f);
    spinner.ValueChanged += new EventHandler(OutputValue);
    window.Add(spinner);
    window.ShowAll();
}

// Handles ValueChanged events and writes to the console
private void OutputValue(object source, System.EventArgs args)
{
    SpinButton spinner = source as SpinButton;
    System.Console.WriteLine("Current value is: " + spinner.ValueAsInt);
}

    </code></example></para>
    </remarks>
  </Docs>
  <Base>
    <BaseTypeName>Gtk.Entry</BaseTypeName>
  </Base>
  <Interfaces>
  </Interfaces>
  <Members>
    <Member MemberName="Spin">
      <MemberSignature Language="C#" Value="public void Spin (Gtk.SpinType direction, double increment);" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters>
        <Parameter Name="direction" Type="Gtk.SpinType" />
        <Parameter Name="increment" Type="System.Double" />
      </Parameters>
      <Docs>
        <summary>Changes the value of the SpinButton by <paramref name="increment" />.</summary>
        <param name="direction">A direction that indicates if the SpinButton should be incremented or decremented.</param>
        <param name="increment">The amount to adjust the SpinButton by.</param>
        <remarks />
      </Docs>
    </Member>
    <Member MemberName="GetRange">
      <MemberSignature Language="C#" Value="public void GetRange (out double min, out double max);" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters>
        <Parameter Name="min" Type="System.Double&amp;" RefType="out" />
        <Parameter Name="max" Type="System.Double&amp;" RefType="out" />
      </Parameters>
      <Docs>
        <summary>Find out the minimum and maximum allowed input values.</summary>
        <param name="min">The minimum value that can be accepted.</param>
        <param name="max">The maximum value that can be accepted.</param>
        <remarks />
      </Docs>
    </Member>
    <Member MemberName="Configure">
      <MemberSignature Language="C#" Value="public void Configure (Gtk.Adjustment adjustment, double climb_rate, uint digits);" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters>
        <Parameter Name="adjustment" Type="Gtk.Adjustment" />
        <Parameter Name="climb_rate" Type="System.Double" />
        <Parameter Name="digits" Type="System.UInt32" />
      </Parameters>
      <Docs>
        <summary>Configures various properties of the SpinButton.</summary>
        <param name="adjustment">An optional <see cref="T:Gtk.Adjustment" /> to configure certain properties, null otherwise.</param>
        <param name="climb_rate">The value to adjust the SpinButton by when one of its arrows are clicked.</param>
        <param name="digits">The number of decimal places to display.</param>
        <remarks>
          <para>An <see cref="T:Gtk.Adjustment" /> is used to configure a variety of the properties for a SpinButton. See the documentation for the <see cref="T:Gtk.Adjustment" /> members for more information.</para>
        </remarks>
      </Docs>
    </Member>
    <Member MemberName="Update">
      <MemberSignature Language="C#" Value="public void Update ();" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>Forces the SpinButton to update its value</summary>
        <remarks />
      </Docs>
    </Member>
    <Member MemberName="SetIncrements">
      <MemberSignature Language="C#" Value="public void SetIncrements (double step, double page);" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters>
        <Parameter Name="step" Type="System.Double" />
        <Parameter Name="page" Type="System.Double" />
      </Parameters>
      <Docs>
        <summary>Sets the step and page increments.</summary>
        <param name="step">The amount to change the spin button by when the user clicks with button 1, (usually the left mouse button).</param>
        <param name="page">The amount to change the spin button by when the user clicks with button 2, (usually the middle mouse button).</param>
        <remarks>
          <para>Changing the values with this method alters how quickly the SpinButton's value changes when its arrows are activated.</para>
        </remarks>
      </Docs>
    </Member>
    <Member MemberName="SetRange">
      <MemberSignature Language="C#" Value="public void SetRange (double min, double max);" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters>
        <Parameter Name="min" Type="System.Double" />
        <Parameter Name="max" Type="System.Double" />
      </Parameters>
      <Docs>
        <summary>Alters the minimum and maximum allowable values.</summary>
        <param name="min">The minimum value that can be entered.</param>
        <param name="max">The maximum value that can be entered.</param>
        <remarks />
      </Docs>
    </Member>
    <Member MemberName="GetIncrements">
      <MemberSignature Language="C#" Value="public void GetIncrements (out double step, out double page);" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters>
        <Parameter Name="step" Type="System.Double&amp;" RefType="out" />
        <Parameter Name="page" Type="System.Double&amp;" RefType="out" />
      </Parameters>
      <Docs>
        <summary>Retrieve the current step and page increments.</summary>
        <param name="step">Outputs the value that a spin button is changed by when the user clicks with button 1, (usually the left mouse button).</param>
        <param name="page">Outputs the value that a spin button is changed by when the user clicks with button 2, (usually the middle mouse button).</param>
        <remarks />
      </Docs>
    </Member>
    <Member MemberName=".ctor">
      <MemberSignature Language="C#" Value="public SpinButton (IntPtr raw);" />
      <MemberType>Constructor</MemberType>
      <ReturnValue />
      <Parameters>
        <Parameter Name="raw" Type="System.IntPtr" />
      </Parameters>
      <Docs>
        <summary>Internal constructor</summary>
        <param name="raw">Pointer to the C object.</param>
        <remarks>
          <para>This is an internal constructor, and should not be used by user code.</para>
        </remarks>
      </Docs>
    </Member>
    <Member MemberName=".ctor">
      <MemberSignature Language="C#" Value="public SpinButton (Gtk.Adjustment adjustment, double climb_rate, uint digits);" />
      <MemberType>Constructor</MemberType>
      <ReturnValue />
      <Parameters>
        <Parameter Name="adjustment" Type="Gtk.Adjustment" />
        <Parameter Name="climb_rate" Type="System.Double" />
        <Parameter Name="digits" Type="System.UInt32" />
      </Parameters>
      <Docs>
        <summary>Creates a new SpinButton based on the specified <see cref="T:Gtk.Adjustment" />.</summary>
        <param name="adjustment">A <see cref="T:Gtk.Adjustment" /></param>
        <param name="climb_rate">A <see cref="T:System.Double" /></param>
        <param name="digits">A <see cref="T:uint" /></param>
        <remarks />
      </Docs>
    </Member>
    <Member MemberName=".ctor">
      <MemberSignature Language="C#" Value="public SpinButton (double min, double max, double step);" />
      <MemberType>Constructor</MemberType>
      <ReturnValue />
      <Parameters>
        <Parameter Name="min" Type="System.Double" />
        <Parameter Name="max" Type="System.Double" />
        <Parameter Name="step" Type="System.Double" />
      </Parameters>
      <Docs>
        <summary>Creates a SpinButton without the need for a manually created <see cref="T:Gtk.Adjustment" />.</summary>
        <param name="min">Minimum allowable value.</param>
        <param name="max">Maximum allowable value.</param>
        <param name="step">The value to alter the SpinButton by when a <see cref="M:Gtk.SpinButton.Spin" /> is carried out on it.</param>
        <remarks>
          <para>The default value of the new SpinButton is initially set to <paramref name="min" />.</para>
          <para>The default page increment is set to 10 * <paramref name="step" />.</para>
          <para>The visible precision of the spin button is equivalent to the precision of <paramref name="step" />.</para>
        </remarks>
      </Docs>
    </Member>
    <Member MemberName="ValueAsInt">
      <MemberSignature Language="C#" Value="public int ValueAsInt { get; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>System.Int32</ReturnType>
      </ReturnValue>
      <Docs>
        <summary>Retrieve the current value as an integer.</summary>
        <value>The value of the SpinButton with integer precision.</value>
        <remarks />
      </Docs>
    </Member>
    <Member MemberName="Numeric">
      <MemberSignature Language="C#" Value="public bool Numeric { set; get; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>System.Boolean</ReturnType>
      </ReturnValue>
      <Parameters>
      </Parameters>
      <Docs>
        <summary>Manage whether or not the SpinButton accepts non-numeric input.</summary>
        <value>Whether the SpinButton currently accepts only numeric input.</value>
        <remarks />
      </Docs>
      <Attributes>
        <Attribute>
          <AttributeName>GLib.Property("numeric")</AttributeName>
        </Attribute>
      </Attributes>
    </Member>
    <Member MemberName="ClimbRate">
      <MemberSignature Language="C#" Value="public double ClimbRate { set; get; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>System.Double</ReturnType>
      </ReturnValue>
      <Parameters>
      </Parameters>
      <Docs>
        <summary>The acceleration rate when user holds down a button.</summary>
        <value>A <see cref="T:System.Double" /></value>
        <remarks />
      </Docs>
      <Attributes>
        <Attribute>
          <AttributeName>GLib.Property("climb-rate")</AttributeName>
        </Attribute>
      </Attributes>
    </Member>
    <Member MemberName="Wrap">
      <MemberSignature Language="C#" Value="public bool Wrap { set; get; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>System.Boolean</ReturnType>
      </ReturnValue>
      <Parameters>
      </Parameters>
      <Docs>
        <summary>Manage whether a SpinButton's value wraps around to the opposite limit when the upper or lower limit of the range is exceeded.</summary>
        <value>Whether this SpinButton wraps its maximum/minimum values when spinning.</value>
        <remarks>
          <para>If this property is set to <see langword="true" />, then when the user tries to change the value in a SpinButton, (usually by clicking one of the arrows), the next value after the maximum will wrap to the minimum.</para>
          <para>Alternatively, if this property is set to <see langword="false" />, then trying to increase the value of the SpinButton when it is at the maximum value, will have no effect. Likewise when trying to decrement the value at its minimum.</para>
        </remarks>
      </Docs>
      <Attributes>
        <Attribute>
          <AttributeName>GLib.Property("wrap")</AttributeName>
        </Attribute>
      </Attributes>
    </Member>
    <Member MemberName="Value">
      <MemberSignature Language="C#" Value="public double Value { set; get; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>System.Double</ReturnType>
      </ReturnValue>
      <Parameters>
      </Parameters>
      <Docs>
        <summary>The current value of the SpinButton.</summary>
        <value>The current value of the SpinButton.</value>
        <remarks>
          <para>The value of the SpinButton is limited by the precision set with the <see cref="P:Gtk.SpinButton.Digits" /> property.</para>
        </remarks>
      </Docs>
      <Attributes>
        <Attribute>
          <AttributeName>GLib.Property("value")</AttributeName>
        </Attribute>
      </Attributes>
    </Member>
    <Member MemberName="Digits">
      <MemberSignature Language="C#" Value="public uint Digits { set; get; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>System.UInt32</ReturnType>
      </ReturnValue>
      <Parameters>
      </Parameters>
      <Docs>
        <summary>Manage the precision that this SpinButton's value is displayed with.</summary>
        <value>The maximum number of digits that the SpinButton will currently display.</value>
        <remarks>
          <para>Up to 20 digit precision is allowed.</para>
        </remarks>
      </Docs>
      <Attributes>
        <Attribute>
          <AttributeName>GLib.Property("digits")</AttributeName>
        </Attribute>
      </Attributes>
    </Member>
    <Member MemberName="SnapToTicks">
      <MemberSignature Language="C#" Value="public bool SnapToTicks { set; get; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>System.Boolean</ReturnType>
      </ReturnValue>
      <Parameters>
      </Parameters>
      <Docs>
        <summary>Manage whether values are corrected to the nearest step increment when a SpinButton is activated with an invalid value.</summary>
        <value>
          <see langword="true" /> if values are snapped to the nearest step, <see langword="false" /> otherwise.</value>
        <remarks />
      </Docs>
      <Attributes>
        <Attribute>
          <AttributeName>GLib.Property("snap-to-ticks")</AttributeName>
        </Attribute>
      </Attributes>
    </Member>
    <Member MemberName="UpdatePolicy">
      <MemberSignature Language="C#" Value="public Gtk.SpinButtonUpdatePolicy UpdatePolicy { set; get; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>Gtk.SpinButtonUpdatePolicy</ReturnType>
      </ReturnValue>
      <Parameters>
      </Parameters>
      <Docs>
        <summary>The policy for how to update this SpinButton when its value changes.</summary>
        <value>A <see cref="T:Gtk.SpinButtonUpdatePolicy" /></value>
        <remarks />
      </Docs>
      <Attributes>
        <Attribute>
          <AttributeName>GLib.Property("update-policy")</AttributeName>
        </Attribute>
      </Attributes>
    </Member>
    <Member MemberName="Adjustment">
      <MemberSignature Language="C#" Value="public Gtk.Adjustment Adjustment { set; get; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>Gtk.Adjustment</ReturnType>
      </ReturnValue>
      <Parameters>
      </Parameters>
      <Docs>
        <summary>The lower/upper/step range of this widget's values.</summary>
        <value>A <see cref="T:Gtk.Adjustment" /></value>
        <remarks />
      </Docs>
      <Attributes>
        <Attribute>
          <AttributeName>GLib.Property("adjustment")</AttributeName>
        </Attribute>
      </Attributes>
    </Member>
    <Member MemberName="Output">
      <MemberSignature Language="C#" Value="public event Gtk.OutputHandler Output;" />
      <MemberType>Event</MemberType>
      <ReturnValue>
        <ReturnType>Gtk.OutputHandler</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>Raised when this widget outputs its value.</summary>
        <remarks />
      </Docs>
      <Attributes>
        <Attribute>
          <AttributeName>GLib.Signal("output")</AttributeName>
        </Attribute>
      </Attributes>
    </Member>
    <Member MemberName="ValueChanged">
      <MemberSignature Language="C#" Value="public event EventHandler ValueChanged;" />
      <MemberType>Event</MemberType>
      <ReturnValue>
        <ReturnType>System.EventHandler</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>This event is raised after the SpinButton's value changes.</summary>
        <remarks />
      </Docs>
      <Attributes>
        <Attribute>
          <AttributeName>GLib.Signal("value_changed")</AttributeName>
        </Attribute>
      </Attributes>
    </Member>
    <Member MemberName="Input">
      <MemberSignature Language="C#" Value="public event Gtk.InputHandler Input;" />
      <MemberType>Event</MemberType>
      <ReturnValue>
        <ReturnType>Gtk.InputHandler</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>Raised when the user inputs a new value.</summary>
        <remarks />
      </Docs>
      <Attributes>
        <Attribute>
          <AttributeName>GLib.Signal("input")</AttributeName>
        </Attribute>
      </Attributes>
    </Member>
    <Member MemberName="ChangeValue">
      <MemberSignature Language="C#" Value="public event Gtk.ChangeValueHandler ChangeValue;" />
      <MemberType>Event</MemberType>
      <ReturnValue>
        <ReturnType>Gtk.ChangeValueHandler</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>Raised in order to change the button's value.</summary>
        <remarks />
      </Docs>
      <Attributes>
        <Attribute>
          <AttributeName>GLib.Signal("change_value")</AttributeName>
        </Attribute>
      </Attributes>
    </Member>
    <Member MemberName="GType">
      <MemberSignature Language="C#" Value="public static GLib.GType GType { get; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>GLib.GType</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>GType Property.</summary>
        <value>a <see cref="T:GLib.GType" /></value>
        <remarks>Returns the native <see cref="T:GLib.GType" /> value for <see cref="T:Gtk.SpinButton" />.</remarks>
      </Docs>
    </Member>
    <Member MemberName="OnChangeValue">
      <MemberSignature Language="C#" Value="protected virtual void OnChangeValue (Gtk.ScrollType scroll);" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters>
        <Parameter Name="scroll" Type="Gtk.ScrollType" />
      </Parameters>
      <Docs>
        <summary>Default handler for the <see cref="M:Gtk.SpinButton.ChangeValue" /> event.</summary>
        <param name="scroll">a <see cref="T:Gtk.ScrollType" /></param>
        <remarks>Override this method in a subclass to provide a default handler for the <see cref="M:Gtk.SpinButton.ChangeValue" /> event.</remarks>
      </Docs>
    </Member>
    <Member MemberName="OnInput">
      <MemberSignature Language="C#" Value="protected virtual int OnInput (out double new_value);" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.Int32</ReturnType>
      </ReturnValue>
      <Parameters>
        <Parameter Name="new_value" Type="System.Double&amp;" RefType="out" />
      </Parameters>
      <Docs>
        <summary>Default handler for the <see cref="M:Gtk.SpinButton.Input" /> event.</summary>
        <param name="new_value">a <see cref="T:System.Double&amp;" /></param>
        <returns>a <see cref="T:System.Int32" /></returns>
        <remarks>Override this method in a subclass to provide a default handler for the <see cref="M:Gtk.SpinButton.Input" /> event.</remarks>
      </Docs>
    </Member>
    <Member MemberName="OnValueChanged">
      <MemberSignature Language="C#" Value="protected virtual void OnValueChanged ();" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>Default handler for the <see cref="M:Gtk.SpinButton.ValueChanged" /> event.</summary>
        <remarks>Override this method in a subclass to provide a default handler for the <see cref="M:Gtk.SpinButton.ValueChanged" /> event.</remarks>
      </Docs>
    </Member>
    <Member MemberName="OnOutput">
      <MemberSignature Language="C#" Value="protected virtual int OnOutput ();" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.Int32</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>Default handler for the <see cref="M:Gtk.SpinButton.Output" /> event.</summary>
        <returns>a <see cref="T:System.Int32" /></returns>
        <remarks>Override this method in a subclass to provide a default handler for the <see cref="M:Gtk.SpinButton.Output" /> event.</remarks>
      </Docs>
    </Member>
    <Member MemberName=".ctor">
      <MemberSignature Language="C#" Value="protected SpinButton (GLib.GType gtype);" />
      <MemberType>Constructor</MemberType>
      <ReturnValue />
      <Parameters>
        <Parameter Name="gtype" Type="GLib.GType" />
      </Parameters>
      <Docs>
        <summary>Protected Constructor.</summary>
        <param name="gtype">a <see cref="T:GLib.GType" /></param>
        <remarks>Chain to this constructor if you have manually registered a native <see cref="T:GLib.GType" /> value for your subclass.</remarks>
      </Docs>
      <Attributes>
        <Attribute>
          <AttributeName>System.Obsolete</AttributeName>
        </Attribute>
      </Attributes>
    </Member>
    <Member MemberName="Wrapped">
      <MemberSignature Language="C#" Value="public event EventHandler Wrapped;" />
      <MemberType>Event</MemberType>
      <Attributes>
        <Attribute>
          <AttributeName>GLib.Signal("wrapped")</AttributeName>
        </Attribute>
      </Attributes>
      <ReturnValue>
        <ReturnType>System.EventHandler</ReturnType>
      </ReturnValue>
      <Docs>
        <summary>Raised when the value wraps from min to max, or max to min.</summary>
        <remarks />
        <since version="Gtk# 2.10" />
      </Docs>
    </Member>
    <Member MemberName="OnWrapped">
      <MemberSignature Language="C#" Value="protected virtual void OnWrapped ();" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>Default handler for <see cref="M:Gtk.SpinButton.Wrapped" /> event.</summary>
        <remarks />
        <since version="Gtk# 2.10" />
      </Docs>
    </Member>
  </Members>
</Type>