<refentry id="GnomeIconTextItem">
<refmeta>
<refentrytitle>GnomeIconTextItem</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GNOMEUI Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>GnomeIconTextItem</refname><refpurpose>Canvas item for editable text captions in icon lists.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;gnome.h&gt;


struct      <link linkend="GnomeIconTextItem-struct">GnomeIconTextItem</link>;
void        <link linkend="gnome-icon-text-item-configure">gnome_icon_text_item_configure</link>  (<link linkend="GnomeIconTextItem">GnomeIconTextItem</link> *iti,
                                             int x,
                                             int y,
                                             int width,
                                             const char *fontname,
                                             const char *text,
                                             <link linkend="gboolean">gboolean</link> is_editable,
                                             <link linkend="gboolean">gboolean</link> is_static);
void        <link linkend="gnome-icon-text-item-setxy">gnome_icon_text_item_setxy</link>      (<link linkend="GnomeIconTextItem">GnomeIconTextItem</link> *iti,
                                             int x,
                                             int y);
void        <link linkend="gnome-icon-text-item-select">gnome_icon_text_item_select</link>     (<link linkend="GnomeIconTextItem">GnomeIconTextItem</link> *iti,
                                             int sel);
char*       <link linkend="gnome-icon-text-item-get-text">gnome_icon_text_item_get_text</link>   (<link linkend="GnomeIconTextItem">GnomeIconTextItem</link> *iti);
void        <link linkend="gnome-icon-text-item-stop-editing">gnome_icon_text_item_stop_editing</link>
                                            (<link linkend="GnomeIconTextItem">GnomeIconTextItem</link> *iti,
                                             <link linkend="gboolean">gboolean</link> accept);

</synopsis>
</refsynopsisdiv>

<refsect1>
<title>Object Hierarchy</title>
<synopsis>

  <link linkend="GtkObject">GtkObject</link>
   +----<link linkend="GnomeCanvasItem">GnomeCanvasItem</link>
         +----GnomeIconTextItem
</synopsis>

</refsect1>




<refsect1>
<title>Description</title>
  <para>
    The <structname>GnomeIconTextItem</structname> canvas item
    provides a specialized, editable text item to be used for the text
    captions of icons.  This item is used by the
    <structname>GnomeIconList</structname> widget and by the GNOME
    file manager.
  </para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GnomeIconTextItem-struct">struct GnomeIconTextItem</title>
<programlisting>struct GnomeIconTextItem;</programlisting>
  <para>
    All the fields in the <structname>GnomeIconTextItem</structname>
    structure should be considered private.  When the application
    needs to know the size and bounds of an icon text item, it should
    use the <function><link linkend="gnome-canvas-item-get-bounds">gnome_canvas_item_get_bounds</link>()</function>
    function.
  </para></refsect2>
<refsect2>
<title><anchor id="gnome-icon-text-item-configure">gnome_icon_text_item_configure ()</title>
<programlisting>void        gnome_icon_text_item_configure  (<link linkend="GnomeIconTextItem">GnomeIconTextItem</link> *iti,
                                             int x,
                                             int y,
                                             int width,
                                             const char *fontname,
                                             const char *text,
                                             <link linkend="gboolean">gboolean</link> is_editable,
                                             <link linkend="gboolean">gboolean</link> is_static);</programlisting>
<para>
This routine is used to configure a &amp;GnomeIconTextItem.
</para>
<para>
<parameter>x</parameter> and <parameter>y</parameter> specify the cordinates where the item is placed inside the canvas.
The <parameter>x</parameter> coordinate should be the leftmost position that the icon text item can
assume at any one time, that is, the left margin of the column in which the
icon is to be placed.  The <parameter>y</parameter> coordinate specifies the top of the icon text
item.
</para>
<para>
<parameter>width</parameter> is the maximum width allowed for this icon text item.  The coordinates
define the upper-left corner of an icon text item with maximum width; this may
actually be outside the bounding box of the item if the text is narrower than
the maximum width.
</para>
<para>
If <parameter>is_static</parameter> is true, it means that there is no need for the item to
allocate memory for the string (it is a guarantee that the text is allocated
by the caller and it will not be deallocated during the lifetime of this
item).  This is an optimization to reduce memory usage for large icon sets.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>iti</parameter>&nbsp;:</entry>
<entry> An icon text item.
</entry></row>
<row><entry align="right"><parameter>x</parameter>&nbsp;:</entry>
<entry> X position in which to place the item.
</entry></row>
<row><entry align="right"><parameter>y</parameter>&nbsp;:</entry>
<entry> Y position in which to place the item.
</entry></row>
<row><entry align="right"><parameter>width</parameter>&nbsp;:</entry>
<entry> Maximum width allowed for this item, to be used for word wrapping.
</entry></row>
<row><entry align="right"><parameter>fontname</parameter>&nbsp;:</entry>
<entry> Name of the fontset that should be used to display the text.
</entry></row>
<row><entry align="right"><parameter>text</parameter>&nbsp;:</entry>
<entry> Text that is going to be displayed.
</entry></row>
<row><entry align="right"><parameter>is_editable</parameter>&nbsp;:</entry>
<entry> Deprecated.
</entry></row>
<row><entry align="right"><parameter>is_static</parameter>&nbsp;:</entry>
<entry> Whether <parameter>text</parameter> points to a static string or not.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-icon-text-item-setxy">gnome_icon_text_item_setxy ()</title>
<programlisting>void        gnome_icon_text_item_setxy      (<link linkend="GnomeIconTextItem">GnomeIconTextItem</link> *iti,
                                             int x,
                                             int y);</programlisting>
<para>
Sets the coordinates at which the icon text item should be placed.
</para>
<para>
See also: <link linkend="gnome-icon-text-item-configure">gnome_icon_text_item_configure</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>iti</parameter>&nbsp;:</entry>
<entry>  An icon text item.
</entry></row>
<row><entry align="right"><parameter>x</parameter>&nbsp;:</entry>
<entry> X position.
</entry></row>
<row><entry align="right"><parameter>y</parameter>&nbsp;:</entry>
<entry> Y position.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-icon-text-item-select">gnome_icon_text_item_select ()</title>
<programlisting>void        gnome_icon_text_item_select     (<link linkend="GnomeIconTextItem">GnomeIconTextItem</link> *iti,
                                             int sel);</programlisting>
<para>
This function is used to control whether an icon text item is displayed as
selected or not.  Mouse events are ignored by the item when it is unselected;
when the user clicks on a selected icon text item, it will start the text
editing process.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>iti</parameter>&nbsp;:</entry>
<entry> An icon text item
</entry></row>
<row><entry align="right"><parameter>sel</parameter>&nbsp;:</entry>
<entry> Whether the icon text item should be displayed as selected.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-icon-text-item-get-text">gnome_icon_text_item_get_text ()</title>
<programlisting>char*       gnome_icon_text_item_get_text   (<link linkend="GnomeIconTextItem">GnomeIconTextItem</link> *iti);</programlisting>
<para>
</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>iti</parameter>&nbsp;:</entry>
<entry> An icon text item.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the current text string in an icon text item.  The client should not
free this string, as it is internal to the icon text item.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-icon-text-item-stop-editing">gnome_icon_text_item_stop_editing ()</title>
<programlisting>void        gnome_icon_text_item_stop_editing
                                            (<link linkend="GnomeIconTextItem">GnomeIconTextItem</link> *iti,
                                             <link linkend="gboolean">gboolean</link> accept);</programlisting>
<para>
Terminates the editing state of an icon text item.  The <parameter>accept</parameter> argument
controls whether the item's current text should be accepted or discarded.  If
it is discarded, then the icon's original text will be restored.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>iti</parameter>&nbsp;:</entry>
<entry> An icon text item.
</entry></row>
<row><entry align="right"><parameter>accept</parameter>&nbsp;:</entry>
<entry> Whether to accept the current text or to discard it.
</entry></row>
</tbody></tgroup></informaltable></refsect2>

</refsect1>



<refsect1>
<title>See Also</title>
  <para>
    <link linkend="GnomeIconList">GnomeIconList</link>, <link linkend="GnomeCanvas">GnomeCanvas</link>. <link linkend="GnomeIconTextInfo">GnomeIconTextInfo</link>.
  </para>
</refsect1>

</refentry>