GtkSharp/doc/en/Gtk/Label.xml

<Type Name="Label" FullName="Gtk.Label">
  <TypeSignature Language="C#" Value="public class Label : Gtk.Misc, Implementor, IWrapper, IWrapper, IDisposable" Maintainer="Duncan Mak" />
  <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>A widget that displays a small to medium amount of text</summary>
    <remarks>
      <para>
        This widget displays a small to medium amount of text, it is
        the widget used by other widgets, such as <see cref="T:Gtk.Button" /> and <see cref="T:Gtk.MenuItem" /> for
        displaying text.
      </para>
      <para>
        Labels may contain mnemonics; mnemonics are underlined
        characters in the label, used for keyboard navigation. To
        provide the mnemonic, put an underscore before the mnemonic
        character, such as "_File".
      </para>
    </remarks>
  </Docs>
  <Base>
    <BaseTypeName>Gtk.Misc</BaseTypeName>
  </Base>
  <Interfaces>
    <Interface>
      <InterfaceName>Atk.Implementor</InterfaceName>
    </Interface>
    <Interface>
      <InterfaceName>GLib.IWrapper</InterfaceName>
    </Interface>
    <Interface>
      <InterfaceName>GLib.IWrapper</InterfaceName>
    </Interface>
    <Interface>
      <InterfaceName>System.IDisposable</InterfaceName>
    </Interface>
  </Interfaces>
  <Attributes />
  <Members>
    <Member MemberName="NewWithMnemonic">
      <MemberSignature Language="C#" Value="public static Gtk.Label NewWithMnemonic (string str);" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>Gtk.Label</ReturnType>
      </ReturnValue>
      <Parameters>
        <Parameter Name="str" Type="System.String" />
      </Parameters>
      <Docs>
        <summary>Creates a new label widget, containing the text in
        <paramref name="str" />.</summary>
        <param name="str">The text of the label, with an optional underscore to mark the mnemonic character</param>
        <returns>a new <see cref="T:Gtk.Label" /> widget</returns>
        <remarks>
          <para>
            If characters in str are preceded by an underscore, they
            are underlined. If you need a literal underscore character
            in a label, use '__' (two underscores). The first
            underlined character represents a keyboard accelerator
            called a mnemonic. The mnemonic key can be used to
            activate another widget, chosen automatically, or
            explicitly using <see cref="P:Gtk.Label.MnemonicWidget" />.
          </para>
          <para>
            If <see cref="P:Gtk.Label.MnemonicWidget" /> is not set, then the
            first activatable ancestor of the <see cref="T:Gtk.Label" /> will be chosen
            as the mnemonic widget. For instance, if the label is
            inside a button or menu item, the button or menu item will
            automatically become the mnemonic widget and be activated
            by the mnemonic.
          </para>
        </remarks>
      </Docs>
    </Member>
    <Member MemberName="GetSelectionBounds">
      <MemberSignature Language="C#" Value="public bool GetSelectionBounds (out int start, out int end);" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.Boolean</ReturnType>
      </ReturnValue>
      <Parameters>
        <Parameter Name="start" Type="System.Int32" RefType="out" />
        <Parameter Name="end" Type="System.Int32" RefType="out" />
      </Parameters>
      <Docs>
        <summary>Gets the selected range of characters in the label.</summary>
        <param name="start"> return location for start of selection, as a character offset</param>
        <param name="end"> return location for end of selection, as a character offset</param>
        <returns>returns <see langword="true" /> if there's a selection.</returns>
        <remarks></remarks>
      </Docs>
    </Member>
    <Member MemberName="SelectRegion">
      <MemberSignature Language="C#" Value="public void SelectRegion (int start_offset, int end_offset);" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters>
        <Parameter Name="start_offset" Type="System.Int32" />
        <Parameter Name="end_offset" Type="System.Int32" />
      </Parameters>
      <Docs>
        <summary>Selects a range of characters in the label, if the label is selectable.</summary>
        <param name="start_offset">start offset (in characters not bytes)</param>
        <param name="end_offset">end offset (in characters not bytes)</param>
        <remarks>
          <para>
            Selects a range of characters in the label, if the label
            is selectable. See <see cref="P:Gtk.Label.Selectable" />. If the
            label is not selectable, this function has no effect. If
            <paramref name="start_offset" /> or
            <paramref name="end_offset" /> are -1, then the end of the
            label will be substituted.
          </para>
        </remarks>
      </Docs>
    </Member>
    <Member MemberName="GetLayoutOffsets">
      <MemberSignature Language="C#" Value="public void GetLayoutOffsets (out int x, out int y);" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters>
        <Parameter Name="x" Type="System.Int32" RefType="out" />
        <Parameter Name="y" Type="System.Int32" RefType="out" />
      </Parameters>
      <Docs>
        <summary>
          Obtains the coordinates where the label will draw the <see cref="T:Pango.Layout" />
          representing the text in the label
        </summary>
        <param name="x">
          location to store X offset of layout, or <see langword="null" /></param>
        <param name="y">
          location to store Y offset of layout, or <see langword="null" /></param>
        <remarks>
          <para>
            Obtains the coordinates where the label will draw the
            <see cref="T:Pango.Layout" /> representing the text in the label; useful to
            convert mouse events into coordinates inside the
            <see cref="T:Pango.Layout" />, e.g. to take some action if some part of the
            label is clicked. Of course you will need to create a
            <see cref="T:Gtk.EventBox" /> to receive the events, and pack the label
            inside it, since labels are a <see cref="F:Gtk.WindowType.NoWindow" />
            widget. Remember when using the
            <see cref="T:Pango.Layout" />functions you
            need to convert to and from pixels using PANGO_PIXELS() or
            PANGO_SCALE.
          </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 Label (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 Label, 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 Label (string str);" />
      <MemberType>Constructor</MemberType>
      <ReturnValue />
      <Parameters>
        <Parameter Name="str" Type="System.String" />
      </Parameters>
      <Docs>
        <summary>
          Creates a new label with the given text inside it. You can
          pass <see langword="null" /> to get an empty label
          widget.
        </summary>
        <param name="str">The text of the label</param>
        <returns> the new label widget</returns>
        <remarks>
          <para>
            Creates a new label with the given text inside it. You can
            pass <see langword="null" /> to get an empty label
            widget.
          </para>
        </remarks>
      </Docs>
    </Member>
    <Member MemberName=".ctor">
      <MemberSignature Language="C#" Value="protected Label ();" />
      <MemberType>Constructor</MemberType>
      <ReturnValue />
      <Parameters />
      <Docs>
        <summary>Constructor used to extending this class</summary>
        <returns>the newly created <see cref="T:Gtk.Label" /></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.Label</summary>
        <returns>The GLib Type for the Gtk.Label class.</returns>
        <remarks />
      </Docs>
    </Member>
    <Member MemberName="TextWithMnemonic">
      <MemberSignature Language="C#" Value="public string TextWithMnemonic { set; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>System.String</ReturnType>
      </ReturnValue>
      <Parameters></Parameters>
      <Docs>
        <summary>Sets the label's text</summary>
        <param name="value">the text for this label</param>
        <remarks>
          <para>
            Sets the label's text. If characters in <paramref name="value" />
            are preceded by an underscore, they are
            underlined indicating that they represent a keyboard
            accelerator called a mnemonic. The mnemonic key can be
            used to activate another widget, chosen automatically, or
            explicitly using <see cref="M:Gtk.Label.MnemonicWidget" />.
          </para>
        </remarks>
      </Docs>
    </Member>
    <Member MemberName="Markup">
      <MemberSignature Language="C#" Value="public string Markup { set; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>System.String</ReturnType>
      </ReturnValue>
      <Parameters></Parameters>
      <Docs>
        <summary>Parses str which is marked up with the Pango text markup language</summary>
        <param name="value">a markup string (see Pango markup format)</param>
        <returns>a GtkLabel</returns>
        <remarks>
          <para>
            Parses <paramref name="value" /> which is marked up with the
            Pango text markup language, setting the label's text and
            attribute list based on the parse results.
          </para>
        </remarks>
      </Docs>
    </Member>
    <Member MemberName="LineWrap">
      <MemberSignature Language="C#" Value="public bool LineWrap { set; get; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>System.Boolean</ReturnType>
      </ReturnValue>
      <Parameters></Parameters>
      <Docs>
        <summary>Toggles line wrapping within the GtkLabel widget.</summary>
        <param name="value">
          <see langword="true" /> makes it
          break lines if text exceeds the widget's size. <see langoword="false" /> lets the text get cut off by the edge of the widget if it exceeds the widget size.
        </param>
        <returns>
          <see langword="true" /> if the lines of the label are automatically wrapped.</returns>
        <remarks />
      </Docs>
    </Member>
    <Member MemberName="Text">
      <MemberSignature Language="C#" Value="public string Text { set; get; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>System.String</ReturnType>
      </ReturnValue>
      <Parameters></Parameters>
      <Docs>
        <summary>The text within the GtkLabel widget.</summary>
        <param name="value">The text you want to set.</param>
        <returns>a GtkLabel</returns>
        <remarks>
          <para>
            When setting the text within the GtkLabel widget, it overwrites any text that was there before.
          </para>
        </remarks>
      </Docs>
    </Member>
    <Member MemberName="Layout">
      <MemberSignature Language="C#" Value="public Pango.Layout Layout { get; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>Pango.Layout</ReturnType>
      </ReturnValue>
      <Docs>
        <summary>Gets the <see cref="T:Pango.Layout" /> used to display the label.</summary>
        <returns> the <see cref="T:Pango.Layout" /> for this label</returns>
        <remarks>
          <para>
            Gets the <see cref="T:Pango.Layout" /> used to display the label. The layout
            is useful to e.g. convert text positions to pixel
            positions, in combination with <see cref="M:Gtk.Label.GetLayoutOffset" />. The returned layout
            is owned by the label so need not be freed by the caller.
          </para>
        </remarks>
      </Docs>
    </Member>
    <Member MemberName="MarkupWithMnemonic">
      <MemberSignature Language="C#" Value="public string MarkupWithMnemonic { set; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>System.String</ReturnType>
      </ReturnValue>
      <Parameters></Parameters>
      <Docs>
        <summary>
          Parses <paramref name="value" /> which is marked up with the
          Pango text markup language, setting the label's text and
          attribute list based on the parse results.
        </summary>
        <param name="value"> a markup string (see Pango markup format)</param>
        <returns>a new label widget</returns>
        <remarks>
          <para>
            Parses <paramref name="value" /> which is marked up with the
            Pango text markup language, setting the label's text and
            attribute list based on the parse results. If characters
            in str are preceded by an underscore, they are underlined
            indicating that they represent a keyboard accelerator
            called a mnemonic.
          </para>
          <para>
            The mnemonic key can be used to activate another widget,
            chosen automatically, or explicitly using <see cref="M:Gtk.Label.MnemonicWidget" />.
          </para>
        </remarks>
      </Docs>
    </Member>
    <Member MemberName="Selectable">
      <MemberSignature Language="C#" Value="public bool Selectable { set; get; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>System.Boolean</ReturnType>
      </ReturnValue>
      <Parameters></Parameters>
      <Docs>
        <summary>Toggle whether or not the label allow the user to select text from the label, for copy-and-paste.</summary>
        <param name="value">
          <see langword="true" /> to allow selecting text in the
        label, and <see langword="false" /> to disallow.
        </param>
        <returns>
          <see langword="true" /> if the label is selectable, and
        <see langword="false" /> if not.
        </returns>
        <remarks />
      </Docs>
    </Member>
    <Member MemberName="Justify">
      <MemberSignature Language="C#" Value="public Gtk.Justification Justify { set; get; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>Gtk.Justification</ReturnType>
      </ReturnValue>
      <Parameters></Parameters>
      <Docs>
        <summary>The alignment of the lines in the text of the label relative to each other</summary>
        <param name="value">a <see cref="T:Gtk.Justification" /></param>
        <returns>The justification of the label</returns>
        <remarks>
          <para>
            Sets the alignment of the lines in the text of the label
            relative to each other. <see cref="T:Gtk.Justification.Left" /> is the default value
            when the widget is first created with <see cref="C:Gtk.Label" />. If you instead want to set the
            alignment of the label as a whole, set <see cref="P:Gtk.Misc.Alignment" /> instead. This has no effect
            on labels containing only a single line.
          </para>
        </remarks>
      </Docs>
    </Member>
    <Member MemberName="CursorPosition">
      <MemberSignature Language="C#" Value="public int CursorPosition { get; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>System.Int32</ReturnType>
      </ReturnValue>
      <Docs>
        <summary>The current position of the insertion cursor in characters.</summary>
        <returns>The current position of the insertion cursor in characters</returns>
        <remarks></remarks>
      </Docs>
    </Member>
    <Member MemberName="SelectionBound">
      <MemberSignature Language="C#" Value="public int SelectionBound { get; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>System.Int32</ReturnType>
      </ReturnValue>
      <Docs>
        <summary>The position of the opposite end of the selection from the cursor in characters.</summary>
        <returns>The position of the opposite end of the selection from the cursor in characters.</returns>
        <remarks></remarks>
      </Docs>
    </Member>
    <Member MemberName="MnemonicWidget">
      <MemberSignature Language="C#" Value="public Gtk.Widget MnemonicWidget { set; get; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>Gtk.Widget</ReturnType>
      </ReturnValue>
      <Parameters></Parameters>
      <Docs>
        <summary>The widget to be activated when the label's mnemonic key is pressed.</summary>
        <param name="value">The widget to be activated when the label's mnemonic key is pressed.</param>
        <returns>The widget to be activated when the label's mnemonic key is pressed.</returns>
        <remarks></remarks>
      </Docs>
    </Member>
    <Member MemberName="LabelProp">
      <MemberSignature Language="C#" Value="public string LabelProp { set; get; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>System.String</ReturnType>
      </ReturnValue>
      <Parameters></Parameters>
      <Docs>
        <summary>Thee text from a label widget including any embedded underlines indicating mnemonics and Pango markup.</summary>
        <param name="value">The text of the label widget</param>
        <returns>The text of the label widget.</returns>
        <remarks></remarks>
      </Docs>
    </Member>
    <Member MemberName="Pattern">
      <MemberSignature Language="C#" Value="public string Pattern { set; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>System.String</ReturnType>
      </ReturnValue>
      <Parameters></Parameters>
      <Docs>
        <summary>A string with _ characters in positions correspond to characters in the text to underline.</summary>
        <param name="value">A string with _ characters in positions correspond to characters in the text to underline.</param>
        <remarks></remarks>
      </Docs>
    </Member>
    <Member MemberName="MnemonicKeyval">
      <MemberSignature Language="C#" Value="public uint MnemonicKeyval { get; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>System.UInt32</ReturnType>
      </ReturnValue>
      <Docs>
        <summary>The mnemonic accelerator key for this label.</summary>
        <returns>The mnemonic accelerator key for this label.</returns>
        <remarks></remarks>
      </Docs>
    </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>Whether lines should be wrapped if the text becomes too wide.</summary>
        <param name="value">
          <see langword="true" /> to wrap lines</param>
        <returns>whether lines should be wrapped</returns>
        <remarks></remarks>
      </Docs>
    </Member>
    <Member MemberName="UseUnderline">
      <MemberSignature Language="C#" Value="public bool UseUnderline { set; get; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>System.Boolean</ReturnType>
      </ReturnValue>
      <Parameters></Parameters>
      <Docs>
        <summary>
          Whether an underline in the text indicates the next
          character should be used for the mnemonic accelerator key.
        </summary>
        <param name="value">
          <see langword="true" /> to use underline</param>
        <returns>
          Whether an underline in the text indicates the next
          character should be used for the mnemonic accelerator key.
        </returns>
        <remarks></remarks>
      </Docs>
    </Member>
    <Member MemberName="UseMarkup">
      <MemberSignature Language="C#" Value="public bool UseMarkup { set; get; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>System.Boolean</ReturnType>
      </ReturnValue>
      <Parameters></Parameters>
      <Docs>
        <summary>Whether the label's text is interpreted as marked up with the Pango text markup language.</summary>
        <param name="value">
          <see langword="true" /> to parse the
        text as Pango markup, <see langword="false" /> as plain-text</param>
        <returns />
        <remarks />
      </Docs>
    </Member>
    <Member MemberName="Attributes">
      <MemberSignature Language="C#" Value="public Pango.AttrList Attributes { set; get; };" />
      <MemberType>Property</MemberType>
      <ReturnValue>
        <ReturnType>Pango.AttrList</ReturnType>
      </ReturnValue>
      <Parameters></Parameters>
      <Docs>
        <summary>The attribute list set on the label.</summary>
        <param name="value">a <see cref="T:Pango.AttrList" /></param>
        <returns>the attribute list set on the label</returns>
        <remarks>
          <para>
            This function does not reflect attributes that come from
            the labels markup (see <see cref="P:Gtk.Label.Markup" />). If you
            want to get the effective attributes for the label, use
            <see cref="T:Pango.Layout.Attribute" /> on the label's
            <see cref="P:Gtk.Label.Layout" /> property.
          </para>
          <para></para>
        </remarks>
      </Docs>
    </Member>
    <Member MemberName="MoveCursor">
      <MemberSignature Language="C#" Value="public event GtkSharp.MoveCursorHandler MoveCursor;" />
      <MemberType>Event</MemberType>
      <ReturnValue>
        <ReturnType>GtkSharp.MoveCursorHandler</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>Emitted when the cursor is moved.</summary>
        <remarks></remarks>
      </Docs>
    </Member>
    <Member MemberName="PopulatePopup">
      <MemberSignature Language="C#" Value="public event GtkSharp.PopulatePopupHandler PopulatePopup;" />
      <MemberType>Event</MemberType>
      <ReturnValue>
        <ReturnType>GtkSharp.PopulatePopupHandler</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>Emitted when a right-click pop-up menu is displayed</summary>
        <remarks></remarks>
      </Docs>
    </Member>
    <Member MemberName="CopyClipboard">
      <MemberSignature Language="C#" Value="public event EventHandler CopyClipboard;" />
      <MemberType>Event</MemberType>
      <ReturnValue>
        <ReturnType>System.EventHandler</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>Emitted when text is copied to the clipboard.</summary>
        <remarks></remarks>
      </Docs>
    </Member>
    <Member MemberName=".ctor">
      <MemberSignature Language="C#" Value="protected Label (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 Label, using the GLib-provided type</returns>
        <remarks>
          <para>This is a constructor used by derivative types of <see cref="T:Gtk.Label" /> that would have their own GLib type assigned to it.  This is not typically used by C# code.</para>
        </remarks>
      </Docs>
    </Member>
  </Members>
</Type>