<!-- ##### SECTION Title ##### -->
GnomeIconList

<!-- ##### SECTION Short_Description ##### -->
A list of icons with captions, with optional caption editing.

<!-- ##### SECTION Long_Description ##### -->
  <para>
    The GNOME icon list widget can hold a number of icons with
    captions.  The icons on the list can be selected (various
    selection methods are supported).  The programmer can enable
    caption-editing for the icons.  This parameters is configured when
    you create the icon list widget.
  </para>

  <para>
    You can control the type of selection mode you desire by using the
    gnome_icon_list_set_selection_mode() function.
  </para>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### STRUCT GnomeIconList ##### -->
  <para>
    All fields in the <structname>GnomeIconList</structname> structure
    are private, except for the <structfield>selection</structfield>
    field which you must query to get information about which icons
    are currently selected in the icon list.
  </para>

  <para>
    The <structfield>selection</structfield> field of the
    <structname>GnomeIconList</structname> structure is a linked list
    that holds the indices of the icons that are selected at any one
    time.  The <structfield>data</structfield> pointer in each link of
    the list can be casted to an integer, preferably using the
    <function>GPOINTER_TO_INT()</function> macro, to get the index of
    the icon represented by that link:

    <programlisting>
static void
print_selected_icons (GnomeIconList *gil)
{
	GList *l;
	int i;

	for (l = gil-&gt;selection; l; l = l-&gt;next) {
		i = GPOINTER_TO_INT (l->data)
		printf ("Icon number &percnt;d is selected\n", i);
	}
}
    </programlisting>
  </para>


<!-- ##### MACRO GNOME_ICON_LIST_IS_EDITABLE ##### -->
  <para>
    This macro is a flag passed to the constructor functions.  It is
    used to specify that the icon list should have editable text
    captions.
  </para>



<!-- ##### MACRO GNOME_ICON_LIST_STATIC_TEXT ##### -->
  <para>
    This macro is a flag passed to the constructor functions.  It is
    used to specify whether an icon list makes copies of the text in
    the icon captions or whether it just keeps pointers to the text
    strings supplied by the application.  If this flag is specified,
    then the icon list will just store pointers to the original text
    strings specified by the application, which must then guarantee
    that they will not be freed or changed until the icon list no
    longer needs them.  If it is not specified, then the icon list
    will make copies of the text strings specified by the application.
  </para>

  <para>
    Applications with very big icon lists can save memory by
    specifying this flag and being careful about when to free the text
    strings that are used for the icon captions.
  </para>



<!-- ##### ENUM GnomeIconListMode ##### -->
  <para>
    The use of this enumeration is currently not implemented.
  </para>


<!-- ##### FUNCTION gnome_icon_list_new ##### -->
<para>

</para>

@icon_width: 
@adj: 
@flags: 
@Returns: 


<!-- ##### FUNCTION gnome_icon_list_new_flags ##### -->
<para>

</para>

@icon_width: 
@adj: 
@flags: 
@Returns: 


<!-- ##### FUNCTION gnome_icon_list_construct ##### -->
<para>

</para>

@gil: 
@icon_width: 
@adj: 
@flags: 


<!-- ##### FUNCTION gnome_icon_list_set_hadjustment ##### -->
<para>

</para>

@gil: 
@hadj: 


<!-- ##### FUNCTION gnome_icon_list_set_vadjustment ##### -->
<para>

</para>

@gil: 
@vadj: 


<!-- ##### FUNCTION gnome_icon_list_freeze ##### -->
<para>

</para>

@gil: 


<!-- ##### FUNCTION gnome_icon_list_thaw ##### -->
<para>

</para>

@gil: 


<!-- ##### FUNCTION gnome_icon_list_insert ##### -->
<para>

</para>

@gil: 
@pos: 
@icon_filename: 
@text: 


<!-- ##### FUNCTION gnome_icon_list_insert_imlib ##### -->
<para>

</para>

@gil: 
@pos: 
@im: 
@text: 


<!-- ##### FUNCTION gnome_icon_list_append ##### -->
<para>

</para>

@gil: 
@icon_filename: 
@text: 
@Returns: 


<!-- ##### FUNCTION gnome_icon_list_append_imlib ##### -->
<para>

</para>

@gil: 
@im: 
@text: 
@Returns: 


<!-- ##### FUNCTION gnome_icon_list_clear ##### -->
<para>

</para>

@gil: 


<!-- ##### FUNCTION gnome_icon_list_remove ##### -->
<para>

</para>

@gil: 
@pos: 


<!-- ##### FUNCTION gnome_icon_list_set_selection_mode ##### -->
<para>

</para>

@gil: 
@mode: 


<!-- ##### FUNCTION gnome_icon_list_select_icon ##### -->
<para>

</para>

@gil: 
@idx: 


<!-- ##### FUNCTION gnome_icon_list_unselect_icon ##### -->
<para>

</para>

@gil: 
@pos: 


<!-- ##### FUNCTION gnome_icon_list_unselect_all ##### -->
<para>

</para>

@gil: 
@event: 
@keep: 
@Returns: 


<!-- ##### FUNCTION gnome_icon_list_set_icon_width ##### -->
<para>

</para>

@gil: 
@w: 


<!-- ##### FUNCTION gnome_icon_list_set_row_spacing ##### -->
<para>

</para>

@gil: 
@pixels: 


<!-- ##### FUNCTION gnome_icon_list_set_col_spacing ##### -->
<para>

</para>

@gil: 
@pixels: 


<!-- ##### FUNCTION gnome_icon_list_set_text_spacing ##### -->
<para>

</para>

@gil: 
@pixels: 


<!-- ##### FUNCTION gnome_icon_list_set_icon_border ##### -->
<para>

</para>

@gil: 
@pixels: 


<!-- ##### FUNCTION gnome_icon_list_set_separators ##### -->
<para>

</para>

@gil: 
@sep: 


<!-- ##### FUNCTION gnome_icon_list_set_icon_data ##### -->
<para>

</para>

@gil: 
@pos: 
@data: 


<!-- ##### FUNCTION gnome_icon_list_set_icon_data_full ##### -->
<para>

</para>

@gil: 
@pos: 
@data: 
@destroy: 


<!-- ##### FUNCTION gnome_icon_list_find_icon_from_data ##### -->
<para>

</para>

@gil: 
@data: 
@Returns: 


<!-- ##### FUNCTION gnome_icon_list_get_icon_data ##### -->
<para>

</para>

@gil: 
@pos: 
@Returns: 


<!-- ##### FUNCTION gnome_icon_list_moveto ##### -->
<para>

</para>

@gil: 
@pos: 
@yalign: 


<!-- ##### FUNCTION gnome_icon_list_icon_is_visible ##### -->
<para>

</para>

@gil: 
@pos: 
@Returns: 


<!-- ##### FUNCTION gnome_icon_list_get_icon_at ##### -->
<para>

</para>

@gil: 
@x: 
@y: 
@Returns: 


<!-- ##### FUNCTION gnome_icon_list_get_items_per_line ##### -->
<para>

</para>

@gil: 
@Returns: 


<!-- ##### SIGNAL GnomeIconList::select-icon ##### -->
  <para>
    This signal is emitted when an icon becomes selected.  If the
    <symbol>event</symbol> argument is NULL, then it means the icon
    became selected due to a range or rubberband selection.  If it is
    non-NULL, it means the icon became selected due to an
    user-initiated event such as a mouse button press.  The event can
    be examined to get this information.
  </para>

  <important>
    <para>
      You should not insert or delete icons, or otherwise change the
      selection in the icon list, from within a callback to this
      signal.
    </para>
  </important>

@iconlist: Icon list which emitted the signal.
@num: Index of the icon that became selected.
@event: Event that triggered the selection, or NULL if none.

<!-- ##### SIGNAL GnomeIconList::unselect-icon ##### -->
  <para>
    This signal is emitted when an icon becomes unselected.  The
    meaning of the <symbol>event</symbol> argument is the same as for
    the select-icon signal.
  </para>

  <important>
    <para>
      You should not insert or delete icons, or otherwise change the
      selection in the icon list, from within a callback to this
      signal.
    </para>
  </important>

@iconlist: Icon list which emitted the signal.
@num: Index of the icon that became unselected.
@event: Event that triggered the unselection, or NULL if none.

<!-- ##### SIGNAL GnomeIconList::text-changed ##### -->
  <para>
    This signal is emitted when the user has finished editing the text
    of an icon's caption.  Typically this happens when the user
    presses <keycap>Enter</keycap>.  The application must then decide
    whether the text is valid or not.
  </para>

  <para>
    The return value of this signal indicates whether the proposed
    text is accepted by the application.  For example, an application
    may need to check whether the user can rename a file to the
    proposed name or not.  If the proposed text is valid, then a
    signal handler should return <symbol>TRUE</symbol>, otherwise it
    should return <symbol>FALSE</symbol>.  If the change is not
    accepted, the text is automatically reset to its original state.
  </para>

@iconlist: Icon list which emitted the signal.
@num: Index of the icon whose text was edited.
@new_text: Text entered by the user, which must be validated.
@Returns: Whether the change is accepted by the application or not.

<!-- ##### ARG GnomeIconList:hadjustment ##### -->
  <para>
    This is a <structname>GtkHAdjustment</structname> that is used
    internally to support the
    <structname>GtkScrolledWindow</structname> scrolling interface.
  </para>

<!-- ##### ARG GnomeIconList:vadjustment ##### -->
  <para>
    This is a <structname>GtkVAdjustment</structname> that is used
    internally to support the
    <structname>GtkScrolledWindow</structname> scrolling interface.
  </para>

<!--
Local variables:
mode: sgml
sgml-parent-document: ("../gnomeui-docs.sgml" "book" "sect1" "")
End:
-->