Gnome User Interface Library Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# GnomeIconList

## Name

GnomeIconList -- A list of icons with captions, with optional caption editing.

## Synopsis

    #include <gnome.h>

    struct      GnomeIconList;
    #define     GNOME_ICON_LIST_IS_EDITABLE
    #define     GNOME_ICON_LIST_STATIC_TEXT
    enum        GnomeIconListMode;
    GtkWidget*  gnome_icon_list_new             (guint icon_width,
                                                 GtkAdjustment *adj,
                                                 int flags);
    GtkWidget*  gnome_icon_list_new_flags       (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_imlib    (GnomeIconList *gil,
                                                 int pos,
                                                 GdkImlibImage *im,
                                                 const char *text);
    int         gnome_icon_list_append          (GnomeIconList *gil,
                                                 const char *icon_filename,
                                                 const char *text);
    int         gnome_icon_list_append_imlib    (GnomeIconList *gil,
                                                 GdkImlibImage *im,
                                                 char *text);
    void        gnome_icon_list_clear           (GnomeIconList *gil);
    void        gnome_icon_list_remove          (GnomeIconList *gil,
                                                 int pos);
    void        gnome_icon_list_set_selection_mode
                                                (GnomeIconList *gil,
                                                 GtkSelectionMode mode);
    void        gnome_icon_list_select_icon     (GnomeIconList *gil,
                                                 int idx);
    void        gnome_icon_list_unselect_icon   (GnomeIconList *gil,
                                                 int pos);
    int         gnome_icon_list_unselect_all    (GnomeIconList *gil,
                                                 GdkEvent *event,
                                                 gpointer keep);
    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);
    void        gnome_icon_list_set_icon_data   (GnomeIconList *gil,
                                                 int pos,
                                                 gpointer data);
    void        gnome_icon_list_set_icon_data_full
                                                (GnomeIconList *gil,
                                                 int pos,
                                                 gpointer data,
                                                 GtkDestroyNotify 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);

## Object Hierarchy

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

## Description

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.

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

## Details

### struct GnomeIconList

    struct GnomeIconList;

All fields in the GnomeIconList structure are private, except for the `selection` field which you must query to get information about which icons are currently selected in the icon list.

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

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

    	for (l = gil->selection; l; l = l->next) {
    		i = GPOINTER_TO_INT (l->data)
    		printf ("Icon number %d is selected\n", i);
    	}
    }

### GNOME_ICON_LIST_IS_EDITABLE

    #define GNOME_ICON_LIST_IS_EDITABLE 1

This macro is a flag passed to the constructor functions. It is used to specify that the icon list should have editable text captions.

### GNOME_ICON_LIST_STATIC_TEXT

    #define GNOME_ICON_LIST_STATIC_TEXT 2

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.

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.

### enum GnomeIconListMode

    typedef enum {
    	GNOME_ICON_LIST_ICONS,
    	GNOME_ICON_LIST_TEXT_BELOW,
    	GNOME_ICON_LIST_TEXT_RIGHT
    } GnomeIconListMode;

The use of this enumeration is currently not implemented.

### gnome_icon_list_new ()

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

This function is kept for binary compatibility with old applications. It is similar in purpose to gnome_icon_list_new_flags(), but it will always turn on the `GNOME_ICON_LIST_IS_EDITABLE` flag.

`icon_width` : | Width for the icon columns.
`adj` : | Adjustment to be used for vertical scrolling.
`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_new_flags ()

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

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.

The adjustment is used to pass an existing adjustment to be used to control the icon list's vertical scrolling. Normally NULL can be passed here; if the icon list is inserted into a &GtkScrolledWindow, it will handle scrolling automatically.

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` : | Adjustment to be used for vertical scrolling.
`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);

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

`gil` : | An icon list.
`icon_width` : | Width for the icon columns.
`adj` : | Adjustment to be used for vertical scrolling.
`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);

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);

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` : |

### gnome_icon_list_freeze ()

    void        gnome_icon_list_freeze          (GnomeIconList *gil);

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);

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);

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_imlib ()

    void        gnome_icon_list_insert_imlib    (GnomeIconList *gil,
                                                 int pos,
                                                 GdkImlibImage *im,
                                                 const char *text);

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` : | Imlib image with the icon image.
`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);

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_imlib ()

    int         gnome_icon_list_append_imlib    (GnomeIconList *gil,
                                                 GdkImlibImage *im,
                                                 char *text);

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

`gil` : | An icon list.
`im` : | Imlib image with the icon image.
`text` : | Text to be used for the icon's caption.
Returns : |

### gnome_icon_list_clear ()

    void        gnome_icon_list_clear           (GnomeIconList *gil);

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);

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_set_selection_mode ()

    void        gnome_icon_list_set_selection_mode
                                                (GnomeIconList *gil,
                                                 GtkSelectionMode mode);

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 idx);

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

`gil` : | An icon list.
`idx` : |

### gnome_icon_list_unselect_icon ()

    void        gnome_icon_list_unselect_icon   (GnomeIconList *gil,
                                                 int pos);

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,
                                                 GdkEvent *event,
                                                 gpointer keep);

Unselects all the icons in the icon list. The `event` and `keep` parameters must be NULL, since they are used only internally.

`gil` : | An icon list.
`event` : | Unused, must be NULL.
`keep` : | For internal use only; must be NULL.
Returns : | the number of icons in the icon list

### gnome_icon_list_set_icon_width ()

    void        gnome_icon_list_set_icon_width  (GnomeIconList *gil,
                                                 int w);

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);

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);

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);

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);

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);

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_set_icon_data ()

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

`gil` : |
`pos` : |
`data` : |

### gnome_icon_list_set_icon_data_full ()

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

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);

`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);

`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);

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);

`gil` : |
`pos` : |
Returns : |

### gnome_icon_list_get_icon_at ()

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

`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);

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

<<< Previous Page | Home | Up | Next Page >>>
GnomeIconTextItem | GnomeIconSelection