[Gtk-sharp-list] Gtk.Adjustment docs

Lee Mallabone gnome@fonicmonkey.net
21 Mar 2003 18:47:23 +0000
Previous message: [Gtk-sharp-list] Gdk.Color ctr
Next message: [Gtk-sharp-list] calendar sample
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
--=-z+YTBk1dZzTh0WET1SSH
Content-Type: text/plain
Content-Transfer-Encoding: 7bit

Hi all,

I've prepared a first draft of docs for Gtk.Adjustment, based on the C
docs and my knowledge. (The prose needs improving, but it's attached).

However, I'm having a bit of trouble with the ClampPage() function.

The C docs explain roughly what the code does. However, even after
staring at the code directly, I'm still none the wiser as to what the
method would be used for by an application programmer.

In short, I don't think the C docs for this function are much good, but
I can't figure out what to write that's better.

Can anyone provide any insight into this method?

Cheers,

Lee.


--=-z+YTBk1dZzTh0WET1SSH
Content-Disposition: attachment; filename=Adjustment.xml
Content-Type: text/xml; name=Adjustment.xml; charset=ANSI_X3.4-1968
Content-Transfer-Encoding: 7bit

<Type Name="Adjustment" FullName="Gtk.Adjustment">
  <TypeSignature Language="C#" Value="public class Adjustment : Gtk.Object, IWrapper, IDisposable" Maintainer="Lee Mallabone" />
  <AssemblyInfo>
    <AssemblyName>gtk-sharp</AssemblyName>
    <AssemblyVersion>0.0.0.0</AssemblyVersion>
    <Attributes />
  </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>Encapsulates an adjustable bounded value.</summary>
    <remarks><para>The Adjustment object represents a value with an associated <see cref="P:Gtk.Adjustment.Lower"/> and <see cref="P:Gtk.Adjustment.Upper"/> bound, together with a <see cref="P:Gtk.Adjustment.StepIncrement"/>, <see cref="P:Gtk.Adjustment.PageIncrement"/>, and a <see cref="P:Gtk.Adjustment.PageSize"/>.</para>
    <para>The Adjustment object does not update the value itself. Instead it is left up to the owner of the Adjustment to control the value. The owner of the Adjustment typically calls the <see cref="M:Gtk.Adjustment.ValueChanged"/> and <see cref="M:Gtk.Adjustment.Changed"/> methods after changing the value or its bounds, respectively. This results in the emission of the <see cref="F:Gtk.Adjustment.ValueChanged"/> or <see cref="F:Gtk.Adjustment.Changed"/> events respectively.</para>
     <para>An Adjustment is used within several widgets, including <see cref="T:Gtk.SpinButton"/>, <see cref="T:Gtk.Viewport"/>, and <see cref="T:Gtk.Range"/> (which is a base class for <see cref="T:Gtk.HScrollbar"/>, <see cref="T:Gtk.VScrollbar"/>, <see cref="T:Gtk.HScale"/>, and <see cref="T:Gtk.VScale"/>).</para>
</remarks>
  </Docs>
  <Base>
    <BaseTypeName>Gtk.Object</BaseTypeName>
  </Base>
  <Interfaces>
    <Interface>
      <InterfaceName>GLib.IWrapper</InterfaceName>
    </Interface>
    <Interface>
      <InterfaceName>System.IDisposable</InterfaceName>
    </Interface>
  </Interfaces>
  <Attributes />
  <Members>
    <Member MemberName="SetBounds">
      <MemberSignature Language="C#" Value="public void SetBounds (double lower, double upper, double step_increment, double page_increment, double page_size);" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters>
        <Parameter Name="lower" Type="System.Double" />
        <Parameter Name="upper" Type="System.Double" />
        <Parameter Name="step_increment" Type="System.Double" />
        <Parameter Name="page_increment" Type="System.Double" />
        <Parameter Name="page_size" Type="System.Double" />
      </Parameters>
      <Docs>
        <summary>Sets all the properties of the Adjustment at the same time.</summary>
        <param name="lower">The minimum value.</param>
        <param name="upper">The maximum value.</param>
        <param name="step_increment">The increment to use to make minor changes to the value.</param>
        <param name="page_increment">The increment to use to make major changes to the value.</param>
        <param name="page_size">The page size. In a <see cref="T:Gtk.Scrollbar"/> this is the size of the area that is currently visible.</param>
        <remarks><para>When updating the values and properties of an Adjustment, remember to call the <see cref="M:Gtk.Adjustment.Changed"/> and/or <see cref="M:Gtk.Adjustment.ValueChanged"/> methods to ensure the correct events are fired.</para></remarks>
      </Docs>
    </Member>
    <Member MemberName="ChangeValue">
      <MemberSignature Language="C#" Value="public void ChangeValue ();" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>Fires the <see cref="F:Gtk.Adjustment.ValueChanged"/> event.</summary>
        <remarks><para>This method should be called manually after changing properties to notify all listening objects that the Adjustment's <see cref="P:Gtk.Adjustment.Value"/> has changed.</para></remarks>
      </Docs>
    </Member>
    <Member MemberName="Change">
      <MemberSignature Language="C#" Value="public void Change ();" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>Fires the <see cref="F:Gtk.Adjustment.Changed"/> event.</summary>
        <remarks><para>This method should be called manually after changing properties to notify all listening objects that one or more of the Adjustment's bounds have changed.</para></remarks>
      </Docs>
    </Member>
    <Member MemberName="ClampPage">
      <MemberSignature Language="C#" Value="public void ClampPage (double lower, double upper);" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters>
        <Parameter Name="lower" Type="System.Double" />
        <Parameter Name="upper" Type="System.Double" />
      </Parameters>
      <Docs>
        <summary>Updates the <see cref="P:Gtk.Adjustment.Value"/> to ensure that the range between lower and upper is in the current page (i.e. between value and value + page_size).</summary>
        <param name="lower">To be added: an object of type 'double'</param>
        <param name="upper">To be added: an object of type 'double'</param>
        <remarks><para>To be added: The docs for this function are very confusing, and not 100% in sync with the code of gtk+ 2.0.5.</para><para>If the range is larger than the page size, then only the start of it will be in the current page. The <see cref="F:Gtk.Adjustment.ValueChanged"/> event will be fired if the value changes as a result of this method.</para></remarks>
      </Docs>
    </Member>
    <Member MemberName="Finalize">
      <MemberSignature Language="C#" Value="protected virtual void Finalize ();" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>Disposes the resources associated with the object.</summary>
        <remarks />
      </Docs>
    </Member>
    <Member MemberName=".ctor">
      <MemberSignature Language="C#" Value="public Adjustment (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>
        <returns>An instance of Adjustment, wrapping the C object.</returns>
        <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 Adjustment (double value, double lower, double upper, double step_increment, double page_increment, double page_size);" />
      <MemberType>Constructor</MemberType>
      <ReturnValue />
      <Parameters>
        <Parameter Name="value" Type="System.Double" />
        <Parameter Name="lower" Type="System.Double" />
        <Parameter Name="upper" Type="System.Double" />
        <Parameter Name="step_increment" Type="System.Double" />
        <Parameter Name="page_increment" Type="System.Double" />
        <Parameter Name="page_size" Type="System.Double" />
      </Parameters>
      <Docs>
        <summary>Creates an Adjustment with the specified value and bounds.</summary>
        <param name="value">The initial value.</param>
        <param name="lower">The minimum value.</param>
        <param name="upper">The maximum value.</param>
        <param name="step_increment">The increment to use to make minor changes to the value.</param>
        <param name="page_increment">The increment to use to make major changes to the value.</param>
        <param name="page_size">The page size. In a <see cref="T:Gtk.Scrollbar"/> this is the size of the area that is currently visible.</param>
        <returns>A new Adjustment</returns>
        <remarks></remarks>
      </Docs>
    </Member>
    <Member MemberName=".ctor">
      <MemberSignature Language="C#" Value="protected Adjustment ();" />
      <MemberType>Constructor</MemberType>
      <ReturnValue />
      <Parameters />
      <Docs>
        <summary>Internal constructor</summary>
        <returns></returns>
        <remarks></remarks>
      </Docs>
    </Member>
    <Member MemberName="GType">
      <MemberSignature Language="C#" Value="public static uint GType { get; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>System.UInt32</ReturnType>
      </ReturnValue>
      <Docs>
        <summary>The GLib Type for Gtk.Adjustment</summary>
        <returns>The GLib Type for the Gtk.Adjustment class.</returns>
        <remarks />
      </Docs>
    </Member>
    <Member MemberName="PageSize">
      <MemberSignature Language="C#" Value="public double PageSize { set; get; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>System.Double</ReturnType>
      </ReturnValue>
      <Parameters>
        <Parameter Name="value" Type="System.Double" />
      </Parameters>
      <Docs>
        <summary>Manage the size of a 'page'.</summary>
        <param name="value">The new page size.</param>
        <returns>The current size of pages in this Adjustment.</returns>
        <remarks><para>In a <see cref="T:Gtk.Scrollbar"/> this is the size of the area which is currently visible.</para></remarks>
      </Docs>
    </Member>
    <Member MemberName="PageIncrement">
      <MemberSignature Language="C#" Value="public double PageIncrement { set; get; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>System.Double</ReturnType>
      </ReturnValue>
      <Parameters>
        <Parameter Name="value" Type="System.Double" />
      </Parameters>
      <Docs>
        <summary>Manage the increment used to make major changes to the value.</summary>
        <param name="value">A new value for the PageIncrement</param>
        <returns>The current PageIncrement.</returns>
        <remarks><para>The usefulness of this value is entirely dependent upon the context in whic hthe Adjustment is used.</para></remarks>
      </Docs>
    </Member>
    <Member MemberName="StepIncrement">
      <MemberSignature Language="C#" Value="public double StepIncrement { get; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>System.Double</ReturnType>
      </ReturnValue>
      <Docs>
        <summary>The increment to use to make minor changes to the value.</summary>
        <returns>The current value used for step increments.</returns>
        <remarks><para>In a <see cref="T:Gtk.Scrollbar"/> this increment is used when the mouse is clicked on the arrows at the top and bottom of the <see cref="T:Gtk.Scrollbar"/>, to scroll by a small amount.</para></remarks>
      </Docs>
    </Member>
    <Member MemberName="Upper">
      <MemberSignature Language="C#" Value="public double Upper { get; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>System.Double</ReturnType>
      </ReturnValue>
      <Docs>
        <summary>Retrieve the upper bound of this Adjustment.</summary>
        <returns>The maximum possible value that is currently allowed.</returns>
        <remarks></remarks>
      </Docs>
    </Member>
    <Member MemberName="Lower">
      <MemberSignature Language="C#" Value="public double Lower { get; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>System.Double</ReturnType>
      </ReturnValue>
      <Docs>
        <summary>Retrieve the lower bound of this Adjustment.</summary>
        <returns>The minimum possible value that is currently allowed.</returns>
        <remarks></remarks>
      </Docs>
    </Member>
    <Member MemberName="Value">
      <MemberSignature Language="C#" Value="public double Value { set; get; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>System.Double</ReturnType>
      </ReturnValue>
      <Parameters>
        <Parameter Name="value" Type="System.Double" />
      </Parameters>
      <Docs>
        <summary>Manage the current <paramref name="value"/>.</summary>
        <param name="value">A new value for this Adjustment.</param>
        <returns>The current value of this adjustment.</returns>
        <remarks><para>If you set this property, you should manually call <see cref="M:Gtk.Adjustment.ChangeValue"/> so that all listening objects are notified of the change.</para></remarks>
      </Docs>
    </Member>
    <Member MemberName="ValueChanged">
      <MemberSignature Language="C#" Value="public event EventHandler ValueChanged;" />
      <MemberType>Event</MemberType>
      <ReturnValue />
      <Parameters />
      <Docs>
        <summary>This event is fired when <see cref="M:Gtk.Adjustment.ChangeValue"/> is called.</summary>
        <remarks><para>This event can be handled to be notified of changes to the Adjustment's value. However, this relies on all objects that change the <see cref="P:Gtk.Adjustment.Value"/> calling <see cref="M:Gtk.Adjustment.ChangeValue"/>.</para></remarks>
      </Docs>
    </Member>
    <Member MemberName="Changed">
      <MemberSignature Language="C#" Value="public event EventHandler Changed;" />
      <MemberType>Event</MemberType>
      <ReturnValue />
      <Parameters />
      <Docs>
        <summary>This event is fired when <see cref="M:Gtk.Adjustment.Change"/> is called.</summary>
        <remarks><para>If the Adjustment's properties change, (such as <see cref="P:Gtk.Adjustment.Upper"/>, <see cref="P:Gtk.Adjustment.Lower"/> etc.), it is up to whichever class changes the values to call <see cref="M:Gtk.Adjustment.Change"/> to ensure this event is fired.</para></remarks>
      </Docs>
    </Member>
    <Member MemberName=".ctor">
      <MemberSignature Language="C#" Value="protected Adjustment (GLib.Type gtype);" />
      <MemberType>Constructor</MemberType>
      <ReturnValue />
      <Parameters>
        <Parameter Name="gtype" Type="GLib.Type" />
      </Parameters>
      <Docs>
        <summary>Internal constructor</summary>
        <param name="gtype">GLib type for the type</param>
        <returns>Creates a new instance of Adjustment, using the GLib-provided type</returns>
        <remarks>
          <para>This is a constructor used by derivative types of <see cref="T:Gtk.Adjustment" /> that would have their own GLib type assigned to it.  This is not typically used by C# code.</para>
        </remarks>
      </Docs>
    </Member>
  </Members>
</Type>
--=-z+YTBk1dZzTh0WET1SSH--
Previous message: [Gtk-sharp-list] Gdk.Color ctr
Next message: [Gtk-sharp-list] calendar sample
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]