## GnomeIconList

GnomeIconList

## Synopsis

    #include <libgnomeui/libgnomeui.h>

    enum                GnomeIconListMode;
                        GnomeIconList;
    GtkWidget *         gnome_icon_list_new                 (guint icon_width,
                                                             GtkAdjustment *adj,
                                                             int flags);
    void                gnome_icon_list_construct           (GnomeIconList *gil,
                                                             guint icon_width,
                                                             GtkAdjustment *adj,
                                                             int flags);
    void                gnome_icon_list_set_hadjustment     (GnomeIconList *gil,
                                                             GtkAdjustment *hadj);
    void                gnome_icon_list_set_vadjustment     (GnomeIconList *gil,
                                                             GtkAdjustment *vadj);
    void                gnome_icon_list_freeze              (GnomeIconList *gil);
    void                gnome_icon_list_thaw                (GnomeIconList *gil);
    void                gnome_icon_list_insert              (GnomeIconList *gil,
                                                             int pos,
                                                             const char *icon_filename,
                                                             const char *text);
    void                gnome_icon_list_insert_pixbuf       (GnomeIconList *gil,
                                                             int pos,
                                                             GdkPixbuf *im,
                                                             const char *icon_filename,
                                                             const char *text);
    int                 gnome_icon_list_append              (GnomeIconList *gil,
                                                             const char *icon_filename,
                                                             const char *text);
    int                 gnome_icon_list_append_pixbuf       (GnomeIconList *gil,
                                                             GdkPixbuf *im,
                                                             const char *icon_filename,
                                                             const char *text);
    void                gnome_icon_list_clear               (GnomeIconList *gil);
    void                gnome_icon_list_remove              (GnomeIconList *gil,
                                                             int pos);
    guint               gnome_icon_list_get_num_icons       (GnomeIconList *gil);
    GtkSelectionMode    gnome_icon_list_get_selection_mode  (GnomeIconList *gil);
    void                gnome_icon_list_set_selection_mode  (GnomeIconList *gil,
                                                             GtkSelectionMode mode);
    void                gnome_icon_list_select_icon         (GnomeIconList *gil,
                                                             int pos);
    void                gnome_icon_list_select_all          (GnomeIconList *gil);
    void                gnome_icon_list_unselect_icon       (GnomeIconList *gil,
                                                             int pos);
    int                 gnome_icon_list_unselect_all        (GnomeIconList *gil);
    GList *             gnome_icon_list_get_selection       (GnomeIconList *gil);
    void                gnome_icon_list_focus_icon          (GnomeIconList *gil,
                                                             gint idx);
    void                gnome_icon_list_set_icon_width      (GnomeIconList *gil,
                                                             int w);
    void                gnome_icon_list_set_row_spacing     (GnomeIconList *gil,
                                                             int pixels);
    void                gnome_icon_list_set_col_spacing     (GnomeIconList *gil,
                                                             int pixels);
    void                gnome_icon_list_set_text_spacing    (GnomeIconList *gil,
                                                             int pixels);
    void                gnome_icon_list_set_icon_border     (GnomeIconList *gil,
                                                             int pixels);
    void                gnome_icon_list_set_separators      (GnomeIconList *gil,
                                                             const char *sep);
    gchar *             gnome_icon_list_get_icon_filename   (GnomeIconList *gil,
                                                             int idx);
    int                 gnome_icon_list_find_icon_from_filename
                                                            (GnomeIconList *gil,
                                                             const char *filename);
    void                gnome_icon_list_set_icon_data       (GnomeIconList *gil,
                                                             int idx,
                                                             gpointer data);
    void                gnome_icon_list_set_icon_data_full  (GnomeIconList *gil,
                                                             int pos,
                                                             gpointer data,
                                                             GDestroyNotify destroy);
    int                 gnome_icon_list_find_icon_from_data (GnomeIconList *gil,
                                                             gpointer data);
    gpointer            gnome_icon_list_get_icon_data       (GnomeIconList *gil,
                                                             int pos);
    void                gnome_icon_list_moveto              (GnomeIconList *gil,
                                                             int pos,
                                                             double yalign);
    GtkVisibility       gnome_icon_list_icon_is_visible     (GnomeIconList *gil,
                                                             int pos);
    int                 gnome_icon_list_get_icon_at         (GnomeIconList *gil,
                                                             int x,
                                                             int y);
    int                 gnome_icon_list_get_items_per_line  (GnomeIconList *gil);
    GnomeIconTextItem * gnome_icon_list_get_icon_text_item  (GnomeIconList *gil,
                                                             int idx);
    GnomeCanvasPixbuf * gnome_icon_list_get_icon_pixbuf_item
                                                            (GnomeIconList *gil,
                                                             int idx);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkObject
                   +----GtkWidget
                         +----GtkContainer
                               +----GtkLayout
                                     +----GnomeCanvas
                                           +----GnomeIconList

## Implemented Interfaces

GnomeIconList implements GtkBuildable and AtkImplementorIface.

## Signals

      "focus-icon"                                     : Run First
      "move-cursor"                                    : Run Last / Action
      "select-icon"                                    : Run First
      "text-changed"                                   : Run Last
      "toggle-cursor-selection"                        : Run Last / Action
      "unselect-icon"                                  : Run First

## Description

## Details

### enum GnomeIconListMode

    typedef enum {
    	GNOME_ICON_LIST_ICONS,
    	GNOME_ICON_LIST_TEXT_BELOW,
    	GNOME_ICON_LIST_TEXT_RIGHT
    } GnomeIconListMode;

### Warning

`GnomeIconListMode` is deprecated and should not be used in newly-written code.

### GnomeIconList

    typedef struct _GnomeIconList GnomeIconList;

### Warning

`GnomeIconList` is deprecated and should not be used in newly-written code.

### gnome_icon_list_new ()

    GtkWidget *         gnome_icon_list_new                 (guint icon_width,
                                                             GtkAdjustment *adj,
                                                             int flags);

### Warning

`gnome_icon_list_new` is deprecated and should not be used in newly-written code.

Creates a new icon list widget. The icon columns are allocated a width of `icon_width` pixels. Icon captions will be word-wrapped to this width as well.

If `flags` has the `GNOME_ICON_LIST_IS_EDITABLE` flag set, then the user will be able to edit the text in the icon captions, and the "text_changed" signal will be emitted when an icon's text is changed.

If `flags` has the `GNOME_ICON_LIST_STATIC_TEXT` flags set, then the text for the icon captions will not be copied inside the icon list; it will only store the pointers to the original text strings specified by the application. This is intended to save memory. If this flag is not set, then the text strings will be copied and managed internally.

`icon_width` : | Width for the icon columns.
`adj` : |
`flags` : | A combination of `GNOME_ICON_LIST_IS_EDITABLE` and `GNOME_ICON_LIST_STATIC_TEXT`.
Returns : | a newly-created icon list widget

### gnome_icon_list_construct ()

    void                gnome_icon_list_construct           (GnomeIconList *gil,
                                                             guint icon_width,
                                                             GtkAdjustment *adj,
                                                             int flags);

### Warning

`gnome_icon_list_construct` is deprecated and should not be used in newly-written code.

Constructor for the icon list, to be used by derived classes.

`gil` : | An icon list.
`icon_width` : | Width for the icon columns.
`adj` : |
`flags` : | A combination of `GNOME_ICON_LIST_IS_EDITABLE` and `GNOME_ICON_LIST_STATIC_TEXT`.

### gnome_icon_list_set_hadjustment ()

    void                gnome_icon_list_set_hadjustment     (GnomeIconList *gil,
                                                             GtkAdjustment *hadj);

### Warning

`gnome_icon_list_set_hadjustment` is deprecated and should not be used in newly-written code.

Sets the adjustment to be used for horizontal scrolling. This is normally not required, as the icon list can be simply inserted in a &GtkScrolledWindow and scrolling will be handled automatically.

`gil` : | An icon list.
`hadj` : | Adjustment to be used for horizontal scrolling.

### gnome_icon_list_set_vadjustment ()

    void                gnome_icon_list_set_vadjustment     (GnomeIconList *gil,
                                                             GtkAdjustment *vadj);

### Warning

`gnome_icon_list_set_vadjustment` is deprecated and should not be used in newly-written code.

Sets the adjustment to be used for vertical scrolling. This is normally not required, as the icon list can be simply inserted in a &GtkScrolledWindow and scrolling will be handled automatically.

`gil` : | An icon list.
`vadj` : | Adjustment to be used for horizontal scrolling.

### gnome_icon_list_freeze ()

    void                gnome_icon_list_freeze              (GnomeIconList *gil);

### Warning

`gnome_icon_list_freeze` is deprecated and should not be used in newly-written code.

Freezes an icon list so that any changes made to it will not be reflected on the screen until it is thawed with `gnome_icon_list_thaw()`. It is recommended to freeze the icon list before inserting or deleting many icons, for example, so that the layout process will only be executed once, when the icon list is finally thawed.

You can call this function multiple times, but it must be balanced with the same number of calls to `gnome_icon_list_thaw()` before the changes will take effect.

`gil` : | An icon list.

### gnome_icon_list_thaw ()

    void                gnome_icon_list_thaw                (GnomeIconList *gil);

### Warning

`gnome_icon_list_thaw` is deprecated and should not be used in newly-written code.

Thaws the icon list and performs any pending layout operations. This is to be used in conjunction with `gnome_icon_list_freeze()`.

`gil` : | An icon list.

### gnome_icon_list_insert ()

    void                gnome_icon_list_insert              (GnomeIconList *gil,
                                                             int pos,
                                                             const char *icon_filename,
                                                             const char *text);

### Warning

`gnome_icon_list_insert` is deprecated and should not be used in newly-written code.

Inserts an icon in the specified icon list. The icon's image is loaded from the specified file, and it is inserted at the `pos` index.

`gil` : | An icon list.
`pos` : | Position at which the new icon should be inserted.
`icon_filename` : | Name of the file that holds the icon's image.
`text` : | Text to be used for the icon's caption.

### gnome_icon_list_insert_pixbuf ()

    void                gnome_icon_list_insert_pixbuf       (GnomeIconList *gil,
                                                             int pos,
                                                             GdkPixbuf *im,
                                                             const char *icon_filename,
                                                             const char *text);

### Warning

`gnome_icon_list_insert_pixbuf` is deprecated and should not be used in newly-written code.

Inserts an icon in the specified icon list. The icon is created from the specified Imlib image, and it is inserted at the `pos` index.

`gil` : | An icon list.
`pos` : | Position at which the new icon should be inserted.
`im` : | Pixbuf image with the icon image.
`icon_filename` : | Filename of the image file.
`text` : | Text to be used for the icon's caption.

### gnome_icon_list_append ()

    int                 gnome_icon_list_append              (GnomeIconList *gil,
                                                             const char *icon_filename,
                                                             const char *text);

### Warning

`gnome_icon_list_append` is deprecated and should not be used in newly-written code.

Appends an icon to the specified icon list. The icon's image is loaded from the specified file, and it is inserted at the `pos` index.

`gil` : | An icon list.
`icon_filename` : | Name of the file that holds the icon's image.
`text` : | Text to be used for the icon's caption.
Returns : |

### gnome_icon_list_append_pixbuf ()

    int                 gnome_icon_list_append_pixbuf       (GnomeIconList *gil,
                                                             GdkPixbuf *im,
                                                             const char *icon_filename,
                                                             const char *text);

### Warning

`gnome_icon_list_append_pixbuf` is deprecated and should not be used in newly-written code.

Appends an icon to the specified icon list. The icon is created from the specified Imlib image.

`gil` : | An icon list.
`im` : | Pixbuf image with the icon image.
`icon_filename` : | Filename of the image file.
`text` : | Text to be used for the icon's caption.
Returns : |

### gnome_icon_list_clear ()

    void                gnome_icon_list_clear               (GnomeIconList *gil);

### Warning

`gnome_icon_list_clear` is deprecated and should not be used in newly-written code.

Clears the contents for the icon list by removing all the icons. If destroy handlers were specified for any of the icons, they will be called with the appropriate data.

`gil` : | An icon list.

### gnome_icon_list_remove ()

    void                gnome_icon_list_remove              (GnomeIconList *gil,
                                                             int pos);

### Warning

`gnome_icon_list_remove` is deprecated and should not be used in newly-written code.

Removes the icon at index position `pos`. If a destroy handler was specified for that icon, it will be called with the appropriate data.

`gil` : | An icon list.
`pos` : | Index of the icon that should be removed.

### gnome_icon_list_get_num_icons ()

    guint               gnome_icon_list_get_num_icons       (GnomeIconList *gil);

### Warning

`gnome_icon_list_get_num_icons` is deprecated and should not be used in newly-written code.

`gil` : | An icon list.
Returns : | The number of icons in the icon list.

### gnome_icon_list_get_selection_mode ()

    GtkSelectionMode    gnome_icon_list_get_selection_mode  (GnomeIconList *gil);

### Warning

`gnome_icon_list_get_selection_mode` is deprecated and should not be used in newly-written code.

`gil` : | An icon list.
Returns : | The current selection mode for an icon list.

### gnome_icon_list_set_selection_mode ()

    void                gnome_icon_list_set_selection_mode  (GnomeIconList *gil,
                                                             GtkSelectionMode mode);

### Warning

`gnome_icon_list_set_selection_mode` is deprecated and should not be used in newly-written code.

Sets the selection mode for an icon list. The `GTK_SELECTION_MULTIPLE` and `GTK_SELECTION_EXTENDED` modes are considered equivalent.

`gil` : | An icon list.
`mode` : | New selection mode.

### gnome_icon_list_select_icon ()

    void                gnome_icon_list_select_icon         (GnomeIconList *gil,
                                                             int pos);

### Warning

`gnome_icon_list_select_icon` is deprecated and should not be used in newly-written code.

Selects the icon at the index specified by `pos`.

`gil` : | An icon list.
`pos` : | Index of the icon to be selected.

### gnome_icon_list_select_all ()

    void                gnome_icon_list_select_all          (GnomeIconList *gil);

### Warning

`gnome_icon_list_select_all` is deprecated and should not be used in newly-written code.

`gil` : | An icon list.

### gnome_icon_list_unselect_icon ()

    void                gnome_icon_list_unselect_icon       (GnomeIconList *gil,
                                                             int pos);

### Warning

`gnome_icon_list_unselect_icon` is deprecated and should not be used in newly-written code.

Unselects the icon at the index specified by `pos`.

`gil` : | An icon list.
`pos` : | Index of the icon to be unselected.

### gnome_icon_list_unselect_all ()

    int                 gnome_icon_list_unselect_all        (GnomeIconList *gil);

### Warning

`gnome_icon_list_unselect_all` is deprecated and should not be used in newly-written code.

`gil` : | An icon list.
Returns : | The number of icons in the icon list

### gnome_icon_list_get_selection ()

    GList *             gnome_icon_list_get_selection       (GnomeIconList *gil);

### Warning

`gnome_icon_list_get_selection` is deprecated and should not be used in newly-written code.

`gil` : | An icon list.
Returns : | A list of integers with the indices of the currently selected icons.

### gnome_icon_list_focus_icon ()

    void                gnome_icon_list_focus_icon          (GnomeIconList *gil,
                                                             gint idx);

### Warning

`gnome_icon_list_focus_icon` is deprecated and should not be used in newly-written code.

`gil` : |
`idx` : |

### gnome_icon_list_set_icon_width ()

    void                gnome_icon_list_set_icon_width      (GnomeIconList *gil,
                                                             int w);

### Warning

`gnome_icon_list_set_icon_width` is deprecated and should not be used in newly-written code.

Sets the amount of horizontal space allocated to the icons, i.e. the column width of the icon list.

`gil` : | An icon list.
`w` : | New width for the icon columns.

### gnome_icon_list_set_row_spacing ()

    void                gnome_icon_list_set_row_spacing     (GnomeIconList *gil,
                                                             int pixels);

### Warning

`gnome_icon_list_set_row_spacing` is deprecated and should not be used in newly-written code.

Sets the spacing to be used between rows of icons.

`gil` : | An icon list.
`pixels` : | Number of pixels for inter-row spacing.

### gnome_icon_list_set_col_spacing ()

    void                gnome_icon_list_set_col_spacing     (GnomeIconList *gil,
                                                             int pixels);

### Warning

`gnome_icon_list_set_col_spacing` is deprecated and should not be used in newly-written code.

Sets the spacing to be used between columns of icons.

`gil` : | An icon list.
`pixels` : | Number of pixels for inter-column spacing.

### gnome_icon_list_set_text_spacing ()

    void                gnome_icon_list_set_text_spacing    (GnomeIconList *gil,
                                                             int pixels);

### Warning

`gnome_icon_list_set_text_spacing` is deprecated and should not be used in newly-written code.

Sets the spacing to be used between an icon's image and its text caption.

`gil` : | An icon list.
`pixels` : | Number of pixels between an icon's image and its caption.

### gnome_icon_list_set_icon_border ()

    void                gnome_icon_list_set_icon_border     (GnomeIconList *gil,
                                                             int pixels);

### Warning

`gnome_icon_list_set_icon_border` is deprecated and should not be used in newly-written code.

Sets the width of the border to be displayed around an icon's image. This is currently not implemented.

`gil` : | An icon list.
`pixels` : | Number of border pixels to be used around an icon's image.

### gnome_icon_list_set_separators ()

    void                gnome_icon_list_set_separators      (GnomeIconList *gil,
                                                             const char *sep);

### Warning

`gnome_icon_list_set_separators` is deprecated and should not be used in newly-written code.

Sets the characters that can be used as word separators when doing word-wrapping in the icon text captions.

`gil` : | An icon list.
`sep` : | String with characters to be used as word separators.

### gnome_icon_list_get_icon_filename ()

    gchar *             gnome_icon_list_get_icon_filename   (GnomeIconList *gil,
                                                             int idx);

### Warning

`gnome_icon_list_get_icon_filename` is deprecated and should not be used in newly-written code.

`gil` : | An icon list.
`idx` : | Index of an `icon`.
Returns : | The filename of the icon with index `idx`.

### gnome_icon_list_find_icon_from_filename ()

    int                 gnome_icon_list_find_icon_from_filename
                                                            (GnomeIconList *gil,
                                                             const char *filename);

### Warning

`gnome_icon_list_find_icon_from_filename` is deprecated and should not be used in newly-written code.

`gil` : | An icon list.
`filename` : | Filename of an icon.
Returns : | The index of the icon whose filename is `filename` or -1 if there is no icon with this filename.

### gnome_icon_list_set_icon_data ()

    void                gnome_icon_list_set_icon_data       (GnomeIconList *gil,
                                                             int idx,
                                                             gpointer data);

### Warning

`gnome_icon_list_set_icon_data` is deprecated and should not be used in newly-written code.

`gil` : |
`idx` : |
`data` : |

### gnome_icon_list_set_icon_data_full ()

    void                gnome_icon_list_set_icon_data_full  (GnomeIconList *gil,
                                                             int pos,
                                                             gpointer data,
                                                             GDestroyNotify destroy);

### Warning

`gnome_icon_list_set_icon_data_full` is deprecated and should not be used in newly-written code.

Associates the `data` pointer to the icon at the index specified by `pos`. The `destroy` argument points to a function that will be called when the icon is destroyed, or NULL if no function is to be called when this happens.

`gil` : | An icon list.
`pos` : | Index of an icon.
`data` : | User data to set on the icon.
`destroy` : | Destroy notification handler for the icon.

### gnome_icon_list_find_icon_from_data ()

    int                 gnome_icon_list_find_icon_from_data (GnomeIconList *gil,
                                                             gpointer data);

### Warning

`gnome_icon_list_find_icon_from_data` is deprecated and should not be used in newly-written code.

`gil` : | An icon list.
`data` : | Data pointer associated to an icon.
Returns : | The index of the icon whose user data has been set to `data`, or -1 if no icon has this data associated to it.

### gnome_icon_list_get_icon_data ()

    gpointer            gnome_icon_list_get_icon_data       (GnomeIconList *gil,
                                                             int pos);

### Warning

`gnome_icon_list_get_icon_data` is deprecated and should not be used in newly-written code.

`gil` : | An icon list.
`pos` : | Index of an icon.
Returns : | The user data pointer associated to the icon at the index specified by `pos`.

### gnome_icon_list_moveto ()

    void                gnome_icon_list_moveto              (GnomeIconList *gil,
                                                             int pos,
                                                             double yalign);

### Warning

`gnome_icon_list_moveto` is deprecated and should not be used in newly-written code.

Makes the icon whose index is `pos` be visible on the screen. The icon list gets scrolled so that the icon is visible. An alignment of 0.0 represents the top of the visible part of the icon list, and 1.0 represents the bottom. An icon can be centered on the icon list.

`gil` : | An icon list.
`pos` : | Index of an icon.
`yalign` : | Vertical alignment of the icon.

### gnome_icon_list_icon_is_visible ()

    GtkVisibility       gnome_icon_list_icon_is_visible     (GnomeIconList *gil,
                                                             int pos);

### Warning

`gnome_icon_list_icon_is_visible` is deprecated and should not be used in newly-written code.

`gil` : | An icon list.
`pos` : | Index of an icon.
Returns : | Whether the icon at the index specified by `pos` is visible. This will be `GTK_VISIBILITY_NONE` if the icon is not visible at all, `GTK_VISIBILITY_PARTIAL` if the icon is at least partially shown, and `GTK_VISIBILITY_FULL` if the icon is fully visible.

### gnome_icon_list_get_icon_at ()

    int                 gnome_icon_list_get_icon_at         (GnomeIconList *gil,
                                                             int x,
                                                             int y);

### Warning

`gnome_icon_list_get_icon_at` is deprecated and should not be used in newly-written code.

`gil` : | An icon list.
`x` : | X position in the icon list window.
`y` : | Y position in the icon list window.
Returns : | The index of the icon that is under the specified coordinates, which are relative to the icon list's window. If there is no icon in that position, -1 is returned.

### gnome_icon_list_get_items_per_line ()

    int                 gnome_icon_list_get_items_per_line  (GnomeIconList *gil);

### Warning

`gnome_icon_list_get_items_per_line` is deprecated and should not be used in newly-written code.

`gil` : | An icon list.
Returns : | The number of icons that fit in a line or row.

### gnome_icon_list_get_icon_text_item ()

    GnomeIconTextItem * gnome_icon_list_get_icon_text_item  (GnomeIconList *gil,
                                                             int idx);

### Warning

`gnome_icon_list_get_icon_text_item` is deprecated and should not be used in newly-written code.

`gil` : |
`idx` : |
Returns : |

### gnome_icon_list_get_icon_pixbuf_item ()

    GnomeCanvasPixbuf * gnome_icon_list_get_icon_pixbuf_item
                                                            (GnomeIconList *gil,
                                                             int idx);

### Warning

`gnome_icon_list_get_icon_pixbuf_item` is deprecated and should not be used in newly-written code.

`gil` : |
`idx` : |
Returns : |

## Signal Details

### The `"focus-icon"` signal

    void                user_function                      (GnomeIconList *iconlist,
                                                            gint           arg1,
                                                            gpointer       user_data)      : Run First

`iconlist` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The `"move-cursor"` signal

    void                user_function                      (GnomeIconList   *iconlist,
                                                            GtkDirectionType arg1,
                                                            gboolean         arg2,
                                                            gpointer         user_data)      : Run Last / Action

`iconlist` : | the object which received the signal.
`arg1` : |
`arg2` : |
`user_data` : | user data set when the signal handler was connected.

### The `"select-icon"` signal

    void                user_function                      (GnomeIconList *iconlist,
                                                            gint           arg1,
                                                            GdkEvent      *event,
                                                            gpointer       user_data)      : Run First

`iconlist` : | the object which received the signal.
`arg1` : |
`event` : |
`user_data` : | user data set when the signal handler was connected.

### The `"text-changed"` signal

    gboolean            user_function                      (GnomeIconList *iconlist,
                                                            gint           arg1,
                                                            gchar         *arg2,
                                                            gpointer       user_data)      : Run Last

`iconlist` : | the object which received the signal.
`arg1` : |
`arg2` : |
`user_data` : | user data set when the signal handler was connected.
Returns : |

### The `"toggle-cursor-selection"` signal

    void                user_function                      (GnomeIconList *iconlist,
                                                            gpointer       user_data)      : Run Last / Action

`iconlist` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"unselect-icon"` signal

    void                user_function                      (GnomeIconList *iconlist,
                                                            gint           arg1,
                                                            GdkEvent      *event,
                                                            gpointer       user_data)      : Run First

`iconlist` : | the object which received the signal.
`arg1` : |
`event` : |
`user_data` : | user data set when the signal handler was connected.