Gnome User Interface Library Reference Manual
PrevNext

GnomeIconList

Name

GnomeIconList — An icon list of widgets, 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,
                                             gboolean is_editable);
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,
                                             void *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

Signal Prototypes


'select-icon'
            void        user_function      (GnomeIconList *iconlist,
                                            gint arg1,
                                            GdkEvent *event,
                                            gpointer user_data);
'unselect-icon'
            void        user_function      (GnomeIconList *iconlist,
                                            gint arg1,
                                            GdkEvent *event,
                                            gpointer user_data);
'text-changed'
            gboolean    user_function      (GnomeIconList *iconlist,
                                            gint arg1,
                                            gpointer arg2,
                                            gpointer user_data);

Description

The GNOME icon list widget can hold a number of icons with captions. You can make the icon captions in the icon list be editable (this is configured at the widget creation time).

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

Details

GnomeIconList

struct GnomeIconList;

GNOME_ICON_LIST_IS_EDITABLE

#define GNOME_ICON_LIST_IS_EDITABLE 1

GNOME_ICON_LIST_STATIC_TEXT

#define GNOME_ICON_LIST_STATIC_TEXT 2

GnomeIconListMode

typedef enum {
	GNOME_ICON_LIST_ICONS,
	GNOME_ICON_LIST_TEXT_BELOW,
	GNOME_ICON_LIST_TEXT_RIGHT
} GnomeIconListMode;

gnome_icon_list_new()

GtkWidget*  gnome_icon_list_new             (guint icon_width,
                                             GtkAdjustment *adj,
                                             gboolean is_editable);

icon_width : adj : is_editable : Returns : 

gnome_icon_list_new_flags()

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

Creates a new GnomeIconList widget. Icons will be assumed to be at most ICON_WIDTH pixels of width. Any text displayed for those icons will be wrapped at this width as well.

The adjustment is used to pass an existing adjustment to be used to control the icon list display. If ADJ is NULL, then a new adjustment will be created.

Applications can use this adjustment stored inside the GnomeIconList structure to construct scrollbars if they so desire.

if flags has the GNOME_ICON_LIST_IS_EDITABLE flag set, then the text on the icons will be permited to be edited. If the name changes the "text_changed" signal will be emitted.

if flags has the GNOME_ICON_LIST_STATIC_TEXT flags set, then the text

Please note that the GnomeIconList starts life in Frozen state. You are supposed to fall gnome_icon_list_thaw on it as soon as possible. */ GtkWidget * gnome_icon_list_new_flags (guint icon_width, GtkAdjustment *adj, int flags) { Gil *gil;

gtk_widget_push_visual (gdk_imlib_get_visual()); gtk_widget_push_colormap (gdk_imlib_get_colormap()); gil = GIL (gtk_type_new (gnome_icon_list_get_type())); gtk_widget_pop_visual(); gtk_widget_pop_colormap(); gnome_icon_list_construct (gil, icon_width, adj, flags);

return GTK_WIDGET (gil); }

GtkWidget * gnome_icon_list_new (guint icon_width, GtkAdjustment *adj, int flags) { return gnome_icon_list_new_flags (icon_width, adj, flags & GNOME_ICON_LIST_IS_EDITABLE); }

/** gnome_icon_list_freeze: gil: The GnomeIconList

Freezes any changes made to the GnomeIconList. This is useful to avoid expensive computations to be performed if you are making many changes to an existing icon list. For example, call this routine before inserting a bunch of icons.

You can call this routine multiple times, you will have to call gnome_icon_list_thaw an equivalent number of times to make any changes done to the icon list to take place.

icon_width : Icon width.adj : Scrolling adjustment.flags : flags that control the icon list creationReturns : 

gnome_icon_list_construct()

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

gil : icon_width : adj : flags : 

gnome_icon_list_set_hadjustment()

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

gil : hadj : 

gnome_icon_list_set_vadjustment()

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

gil : vadj : 

gnome_icon_list_freeze()

void        gnome_icon_list_freeze          (GnomeIconList *gil);

gil : 

gnome_icon_list_thaw()

void        gnome_icon_list_thaw            (GnomeIconList *gil);

If the freeze count reaches zero it will relayout any pending layout changes that might have been delayed due to the icon list be frozen by a call to gnome_icon_list_freeze.

gil : The GnomeIconList

gnome_icon_list_insert()

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

Inserts the at the POS index in the GIL icon list an icon which is contained on the file icon_filename and with the TEXT string as its label.

gil : the icon list.pos : index where the icon should be insertedicon_filename : filename containing the graphic image for the icon.text : text to display for the icon

gnome_icon_list_insert_imlib()

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

Inserts the at the POS index in the GIL icon list an icon which is on the IM imlib imageand with the TEXT string as its label.

gil : the icon list.pos : index where the icon should be insertedim : Imlib image containing the iconstext : text to display for the icon

gnome_icon_list_append()

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

Appends to the GIL icon list an icon which is contained on the file icon_filename and with the TEXT string as its label.

gil : the icon list.icon_filename : filename containing the graphic image for the icon.text : text to display for the icon

gnome_icon_list_append_imlib()

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

gil : im : text : 

gnome_icon_list_clear()

void        gnome_icon_list_clear           (GnomeIconList *gil);

Clears the contents for the icon list.

gil : the icon list to clear

gnome_icon_list_remove()

void        gnome_icon_list_remove          (GnomeIconList *gil,
                                             int pos);

Removes the icon at index position POS.

gil : the icon listpos : the index of the icon to remove

gnome_icon_list_set_selection_mode()

void        gnome_icon_list_set_selection_mode
                                            (GnomeIconList *gil,
                                             GtkSelectionMode mode);

Sets the GnomeIconList selection mode, it can be any of the modes defined in the GtkSelectionMode enumeration.

gil : The GnomeIconListmode : Selection mode

gnome_icon_list_select_icon()

void        gnome_icon_list_select_icon     (GnomeIconList *gil,
                                             int idx);

Selects the icon at index position POS.

gil : The icon list.idx : 

gnome_icon_list_unselect_icon()

void        gnome_icon_list_unselect_icon   (GnomeIconList *gil,
                                             int pos);

Removes the selection from the icon at the index position POS

gil : The icon list.pos : The index of the icon to unselect

gnome_icon_list_unselect_all()

int         gnome_icon_list_unselect_all    (GnomeIconList *gil,
                                             GdkEvent *event,
                                             void *keep);

Unselects all of the icons in the GIL icon list. EVENT is the event that triggered the unselect action (or NULL if the event is not available).

The keep parameter is only used internally in the Icon LIst code, it can be NULL.

gil : the icon listevent : event which triggered this action (might be NULL)keep : pointer to an icon to keep (might be NULL).

gnome_icon_list_set_icon_width()

void        gnome_icon_list_set_icon_width  (GnomeIconList *gil,
                                             int w);

Use this routine to change the icon width

gil : The icon listw : the new width for the icons

gnome_icon_list_set_row_spacing()

void        gnome_icon_list_set_row_spacing (GnomeIconList *gil,
                                             int pixels);

Sets the number of pixels for the inter-row spacing.

gil : The GnomeIconListpixels : number of pixels for the inter-row spacing

gnome_icon_list_set_col_spacing()

void        gnome_icon_list_set_col_spacing (GnomeIconList *gil,
                                             int pixels);

Sets the number of pixels for the inter-column spacing.

gil : The GnomeIconListpixels : number of pixels for the inter-column spacing.

gnome_icon_list_set_text_spacing()

void        gnome_icon_list_set_text_spacing
                                            (GnomeIconList *gil,
                                             int pixels);

Sets the number of pixels for the text spacing.

gil : The GnomeIconListpixels : number of pixels for the text spacing.

gnome_icon_list_set_icon_border()

void        gnome_icon_list_set_icon_border (GnomeIconList *gil,
                                             int pixels);

Sets the number of pixels for the icon borders

gil : The GnomeIconListpixels : number of pixels for the border.

gnome_icon_list_set_separators()

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

Sets the separator characters used to optimally split this string. See gnome-icon-text.h

gil : The GnomeIconListsep : A list of characters used to split the string

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

gil : pos : data : destroy : 

gnome_icon_list_find_icon_from_data()

int         gnome_icon_list_find_icon_from_data
                                            (GnomeIconList *gil,
                                             gpointer data);

gil : The GnomeIconListdata : data pointer.Returns :the index of the icon whose per-icon data has been set to DATA.

gnome_icon_list_get_icon_data()

gpointer    gnome_icon_list_get_icon_data   (GnomeIconList *gil,
                                             int pos);

gil : The GnomeIconListpos : icon index. Returns :the per-icon data associated with the icon at index position POS

gnome_icon_list_moveto()

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

Makes the icon whose index is POS visible on the screen, the YALIGN double controls the alignment of the icon inside the GnomeIconList 0.0 represents the top, while 1.0 represents the bottom.

gil : The GnomeIconListpos : Icon indexyalign : Desired alignement.

gnome_icon_list_icon_is_visible()

GtkVisibility gnome_icon_list_icon_is_visible
                                            (GnomeIconList *gil,
                                             int pos);

gil : pos : 

gnome_icon_list_get_icon_at()

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

gil : the icon listx : screen x position.y : screen y position.Returns :the icon index which is at x, y coordinates on the screen. If there is no icon at that location it will return -1.

gnome_icon_list_get_items_per_line()

int         gnome_icon_list_get_items_per_line
                                            (GnomeIconList *gil);

gil : the icon listReturns :the number of icons that fit in a line

Signals

The 'select-icon' signal

void        user_function                  (GnomeIconList *iconlist,
                                            gint arg1,
                                            GdkEvent *event,
                                            gpointer user_data);

This signal is emited when an icon becomes selected. If the event argument point to NULL the icon was selected programatically with the gnome_icon_list_select_icon() function. Otherwise it points to the GdkEvent that made this icon selected.

iconlist :the object which received the signal.arg1 : event : 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);

This signal is emited when an icon becomes unselected (this signal is only emited if the icon had been previously selected). If the event argument point to NULL the icon was selected programatically with the gnome_icon_list_unselect_icon() function. Otherwise it points to the GdkEvent that made this icon selected.

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,
                                            gpointer arg2,
                                            gpointer user_data);

The text_changed signal is emited on editable icon list widgets if the user has changed the caption of an icon

The return value indicates whether the name change is accepted (for example, if renaming a file succeeds or not). If the change is not accepted, the text is reset to its previous value.

iconlist :the object which received the signal.arg1 : arg2 :The text entered by the user.user_data :user data set when the signal handler was connected.Returns :Whether the change is accepted or not.

PrevHomeNext
GnomeIconTextItemUpGnomeIconSelection