Next: , Previous: GtkCellView, Up: Top


38 GtkIconView

A widget which displays a list of icons in a grid

38.1 Overview

<gtk-icon-view> provides an alternative view on a list model. It displays the model as a grid of icons with labels. Like <gtk-tree-view>, it allows to select one or multiple items (depending on the selection mode, see gtk-icon-view-set-selection-mode). In addition to selection with the arrow keys, <gtk-icon-view> supports rubberband selection, which is controlled by dragging the pointer.

38.2 Usage

— Class: <gtk-icon-view>

Derives from <gtk-cell-layout>, <gtk-container>.

This class defines the following slots:

pixbuf-column
Model column used to retrieve the icon pixbuf from
text-column
Model column used to retrieve the text from
markup-column
Model column used to retrieve the text if using Pango markup
selection-mode
The selection mode
orientation
How the text and icon of each item are positioned relative to each other
model
The model for the icon view
columns
Number of columns to display
item-width
The width used for each item
spacing
Space which is inserted between cells of an item
row-spacing
Space which is inserted between grid rows
column-spacing
Space which is inserted between grid columns
margin
Space which is inserted at the edges of the icon view
reorderable
View is reorderable
tooltip-column
The column in the model containing the tooltip texts for the items
— Signal on <gtk-icon-view>: move-cursor (arg0 <gtk-movement-step>) (arg1 <gint>) ⇒ <gboolean>
— Signal on <gtk-icon-view>: selection-changed
— Signal on <gtk-icon-view>: set-scroll-adjustments (arg0 <gtk-adjustment>) (arg1 <gtk-adjustment>)
— Signal on <gtk-icon-view>: item-activated (arg0 <gtk-tree-path>)
— Signal on <gtk-icon-view>: select-all
— Signal on <gtk-icon-view>: unselect-all
— Signal on <gtk-icon-view>: select-cursor-item
— Signal on <gtk-icon-view>: toggle-cursor-item
— Signal on <gtk-icon-view>: activate-cursor-item ⇒ <gboolean>
— Function: gtk-icon-view-new ⇒  (ret <gtk-widget>)

Creates a new <gtk-icon-view> widget

ret
A newly created <gtk-icon-view> widget

Since 2.6

— Function: gtk-icon-view-new-with-model (model <gtk-tree-model>) ⇒  (ret <gtk-widget>)

Creates a new <gtk-icon-view> widget with the model model.

model
The model.
ret
A newly created <gtk-icon-view> widget.

Since 2.6

— Function: gtk-icon-view-set-model (self <gtk-icon-view>) (model <gtk-tree-model>)
— Method: set-model

Sets the model for a <gtk-icon-view>. If the icon-view already has a model set, it will remove it before setting the new model. If model is ‘#f’, then it will unset the old model.

icon-view
A <gtk-icon-view>.
model
The model.

Since 2.6

— Function: gtk-icon-view-get-model (self <gtk-icon-view>) ⇒  (ret <gtk-tree-model>)
— Method: get-model

Returns the model the <gtk-icon-view> is based on. Returns ‘#f’ if the model is unset.

icon-view
a <gtk-icon-view>
ret
A <gtk-tree-model>, or ‘#f’ if none is currently being used.

Since 2.6

— Function: gtk-icon-view-set-text-column (self <gtk-icon-view>) (column int)
— Method: set-text-column

Sets the column with text for icon-view to be column. The text column must be of type <g-type-string>.

icon-view
A <gtk-icon-view>.
column
A column in the currently used model.

Since 2.6

— Function: gtk-icon-view-get-text-column (self <gtk-icon-view>) ⇒  (ret int)
— Method: get-text-column

Returns the column with text for icon-view.

icon-view
A <gtk-icon-view>.
ret
the text column, or -1 if it's unset.

Since 2.6

— Function: gtk-icon-view-set-markup-column (self <gtk-icon-view>) (column int)
— Method: set-markup-column

Sets the column with markup information for icon-view to be column. The markup column must be of type <g-type-string>. If the markup column is set to something, it overrides the text column set by gtk-icon-view-set-text-column.

icon-view
A <gtk-icon-view>.
column
A column in the currently used model.

Since 2.6

— Function: gtk-icon-view-get-markup-column (self <gtk-icon-view>) ⇒  (ret int)
— Method: get-markup-column

Returns the column with markup text for icon-view.

icon-view
A <gtk-icon-view>.
ret
the markup column, or -1 if it's unset.

Since 2.6

— Function: gtk-icon-view-set-pixbuf-column (self <gtk-icon-view>) (column int)
— Method: set-pixbuf-column

Sets the column with pixbufs for icon-view to be column. The pixbuf column must be of type <gdk-type-pixbuf>

icon-view
A <gtk-icon-view>.
column
A column in the currently used model.

Since 2.6

— Function: gtk-icon-view-get-pixbuf-column (self <gtk-icon-view>) ⇒  (ret int)
— Method: get-pixbuf-column

Returns the column with pixbufs for icon-view.

icon-view
A <gtk-icon-view>.
ret
the pixbuf column, or -1 if it's unset.

Since 2.6

— Function: gtk-icon-view-get-path-at-pos (self <gtk-icon-view>) (int) (int) ⇒  (ret <gtk-tree-path>)
— Method: get-path-at-pos

Finds the path at the point (x, y), relative to widget coordinates. See gtk-icon-view-get-item-at-pos, if you are also interested in the cell at the specified position.

icon-view
A <gtk-icon-view>.
x
The x position to be identified
y
The y position to be identified
ret
The <gtk-tree-path> corresponding to the icon or ‘#f’ if no icon exists at that position.

Since 2.6

— Function: gtk-icon-view-set-cursor (self <gtk-icon-view>) (path <gtk-tree-path>) (cell <gtk-cell-renderer>) (start_editing bool)
— Method: set-cursor

Sets the current keyboard focus to be at path, and selects it. This is useful when you want to focus the user's attention on a particular item. If cell is not ‘#f’, then focus is given to the cell specified by it. Additionally, if start-editing is ‘#t’, then editing should be started in the specified cell.

This function is often followed by ‘gtk_widget_grab_focus (icon_view)’ in order to give keyboard focus to the widget. Please note that editing can only happen when the widget is realized.

icon-view
A <gtk-icon-view>
path
A <gtk-tree-path>
cell
One of the cell renderers of icon-view, or ‘#f
start-editing
#t’ if the specified cell should start being edited.

Since 2.8

— Function: gtk-icon-view-set-selection-mode (self <gtk-icon-view>) (mode <gtk-selection-mode>)
— Method: set-selection-mode

Sets the selection mode of the icon-view.

icon-view
A <gtk-icon-view>.
mode
The selection mode

Since 2.6

— Function: gtk-icon-view-get-selection-mode (self <gtk-icon-view>) ⇒  (ret <gtk-selection-mode>)
— Method: get-selection-mode

Gets the selection mode of the icon-view.

icon-view
A <gtk-icon-view>.
ret
the current selection mode

Since 2.6

— Function: gtk-icon-view-set-orientation (self <gtk-icon-view>) (orientation <gtk-orientation>)
— Method: set-orientation

Sets the ::orientation property which determines whether the labels are drawn beside the icons instead of below.

icon-view
a <gtk-icon-view>
orientation
the relative position of texts and icons

Since 2.6

— Function: gtk-icon-view-get-orientation (self <gtk-icon-view>) ⇒  (ret <gtk-orientation>)
— Method: get-orientation

Returns the value of the ::orientation property which determines whether the labels are drawn beside the icons instead of below.

icon-view
a <gtk-icon-view>
ret
the relative position of texts and icons

Since 2.6

— Function: gtk-icon-view-set-columns (self <gtk-icon-view>) (columns int)
— Method: set-columns

Sets the ::columns property which determines in how many columns the icons are arranged. If columns is -1, the number of columns will be chosen automatically to fill the available area.

icon-view
a <gtk-icon-view>
columns
the number of columns

Since 2.6

— Function: gtk-icon-view-get-columns (self <gtk-icon-view>) ⇒  (ret int)
— Method: get-columns

Returns the value of the ::columns property.

icon-view
a <gtk-icon-view>
ret
the number of columns, or -1

Since 2.6

— Function: gtk-icon-view-set-item-width (self <gtk-icon-view>) (item_width int)
— Method: set-item-width

Sets the ::item-width property which specifies the width to use for each item. If it is set to -1, the icon view will automatically determine a suitable item size.

icon-view
a <gtk-icon-view>
item-width
the width for each item

Since 2.6

— Function: gtk-icon-view-get-item-width (self <gtk-icon-view>) ⇒  (ret int)
— Method: get-item-width

Returns the value of the ::item-width property.

icon-view
a <gtk-icon-view>
ret
the width of a single item, or -1

Since 2.6

— Function: gtk-icon-view-set-spacing (self <gtk-icon-view>) (spacing int)
— Method: set-spacing

Sets the ::spacing property which specifies the space which is inserted between the cells (i.e. the icon and the text) of an item.

icon-view
a <gtk-icon-view>
spacing
the spacing

Since 2.6

— Function: gtk-icon-view-get-spacing (self <gtk-icon-view>) ⇒  (ret int)
— Method: get-spacing

Returns the value of the ::spacing property.

icon-view
a <gtk-icon-view>
ret
the space between cells

Since 2.6

— Function: gtk-icon-view-set-row-spacing (self <gtk-icon-view>) (row_spacing int)
— Method: set-row-spacing

Sets the ::row-spacing property which specifies the space which is inserted between the rows of the icon view.

icon-view
a <gtk-icon-view>
row-spacing
the row spacing

Since 2.6

— Function: gtk-icon-view-get-row-spacing (self <gtk-icon-view>) ⇒  (ret int)
— Method: get-row-spacing

Returns the value of the ::row-spacing property.

icon-view
a <gtk-icon-view>
ret
the space between rows

Since 2.6

— Function: gtk-icon-view-set-column-spacing (self <gtk-icon-view>) (column_spacing int)
— Method: set-column-spacing

Sets the ::column-spacing property which specifies the space which is inserted between the columns of the icon view.

icon-view
a <gtk-icon-view>
column-spacing
the column spacing

Since 2.6

— Function: gtk-icon-view-get-column-spacing (self <gtk-icon-view>) ⇒  (ret int)
— Method: get-column-spacing

Returns the value of the ::column-spacing property.

icon-view
a <gtk-icon-view>
ret
the space between columns

Since 2.6

— Function: gtk-icon-view-set-margin (self <gtk-icon-view>) (margin int)
— Method: set-margin

Sets the ::margin property which specifies the space which is inserted at the top, bottom, left and right of the icon view.

icon-view
a <gtk-icon-view>
margin
the margin

Since 2.6

— Function: gtk-icon-view-get-margin (self <gtk-icon-view>) ⇒  (ret int)
— Method: get-margin

Returns the value of the ::margin property.

icon-view
a <gtk-icon-view>
ret
the space at the borders

Since 2.6

— Function: gtk-icon-view-select-path (self <gtk-icon-view>) (path <gtk-tree-path>)
— Method: select-path

Selects the row at path.

icon-view
A <gtk-icon-view>.
path
The <gtk-tree-path> to be selected.

Since 2.6

— Function: gtk-icon-view-unselect-path (self <gtk-icon-view>) (path <gtk-tree-path>)
— Method: unselect-path

Unselects the row at path.

icon-view
A <gtk-icon-view>.
path
The <gtk-tree-path> to be unselected.

Since 2.6

— Function: gtk-icon-view-path-is-selected (self <gtk-icon-view>) (path <gtk-tree-path>) ⇒  (ret bool)
— Method: path-is-selected

Returns ‘#t’ if the icon pointed to by path is currently selected. If icon does not point to a valid location, ‘#f’ is returned.

icon-view
A <gtk-icon-view>.
path
A <gtk-tree-path> to check selection on.
ret
#t’ if path is selected.

Since 2.6

— Function: gtk-icon-view-get-selected-items (self <gtk-icon-view>) ⇒  (ret glist-of)
— Method: get-selected-items

Creates a list of paths of all selected items. Additionally, if you are planning on modifying the model after calling this function, you may want to convert the returned list into a list of <gtk-tree-row-reference>s. To do this, you can use gtk-tree-row-reference-new.

To free the return value, use:

          
          g_list_foreach (list, gtk_tree_path_free, NULL);
          g_list_free (list);
icon-view
A <gtk-icon-view>.
ret
A <g-list> containing a <gtk-tree-path> for each selected row.

Since 2.6

— Function: gtk-icon-view-select-all (self <gtk-icon-view>)
— Method: select-all

Selects all the icons. icon-view must has its selection mode set to <gtk-selection-multiple>.

icon-view
A <gtk-icon-view>.

Since 2.6

— Function: gtk-icon-view-unselect-all (self <gtk-icon-view>)
— Method: unselect-all

Unselects all the icons.

icon-view
A <gtk-icon-view>.

Since 2.6

— Function: gtk-icon-view-item-activated (self <gtk-icon-view>) (path <gtk-tree-path>)
— Method: item-activated

Activates the item determined by path.

icon-view
A <gtk-icon-view>
path
The <gtk-tree-path> to be activated

Since 2.6

— Function: gtk-icon-view-scroll-to-path (self <gtk-icon-view>) (path <gtk-tree-path>) (use_align bool) (row_align float) (col_align float)
— Method: scroll-to-path

Moves the alignments of icon-view to the position specified by path. row-align determines where the row is placed, and col-align determines where column is placed. Both are expected to be between 0.0 and 1.0. 0.0 means left/top alignment, 1.0 means right/bottom alignment, 0.5 means center.

If use-align is ‘#f’, then the alignment arguments are ignored, and the tree does the minimum amount of work to scroll the item onto the screen. This means that the item will be scrolled to the edge closest to its current position. If the item is currently visible on the screen, nothing is done.

This function only works if the model is set, and path is a valid row on the model. If the model changes before the icon-view is realized, the centered path will be modified to reflect this change.

icon-view
A <gtk-icon-view>.
path
The path of the item to move to.
use-align
whether to use alignment arguments, or ‘#f’.
row-align
The vertical alignment of the item specified by path.
col-align
The horizontal alignment of the item specified by path.

Since 2.8

— Function: gtk-icon-view-unset-model-drag-dest (self <gtk-icon-view>)
— Method: unset-model-drag-dest

Undoes the effect of gtk-icon-view-enable-model-drag-dest.

icon-view
a <gtk-icon-view>

Since 2.8

— Function: gtk-icon-view-set-reorderable (self <gtk-icon-view>) (reorderable bool)
— Method: set-reorderable

This function is a convenience function to allow you to reorder models that support the <gtk-tree-drag-source-iface> and the <gtk-tree-drag-dest-iface>. Both <gtk-tree-store> and <gtk-list-store> support these. If reorderable is ‘#t’, then the user can reorder the model by dragging and dropping rows. The developer can listen to these changes by connecting to the model's row_inserted and row_deleted signals.

This function does not give you any degree of control over the order – any reordering is allowed. If more control is needed, you should probably handle drag and drop manually.

icon-view
A <gtk-icon-view>.
reorderable
#t’, if the list of items can be reordered.

Since 2.8

— Function: gtk-icon-view-get-reorderable (self <gtk-icon-view>) ⇒  (ret bool)
— Method: get-reorderable

Retrieves whether the user can reorder the list via drag-and-drop. See gtk-icon-view-set-reorderable.

icon-view
a <gtk-icon-view>
ret
#t’ if the list can be reordered.

Since 2.8

— Function: gtk-icon-view-set-drag-dest-item (self <gtk-icon-view>) (path <gtk-tree-path>) (pos <gtk-icon-view-drop-position>)
— Method: set-drag-dest-item

Sets the item that is highlighted for feedback.

icon-view
a <gtk-icon-view>
path
The path of the item to highlight, or ‘#f’.
pos
Specifies where to drop, relative to the item

Since 2.8

— Function: gtk-icon-view-create-drag-icon (self <gtk-icon-view>) (path <gtk-tree-path>) ⇒  (ret <gdk-pixmap>)
— Method: create-drag-icon

Creates a <gdk-pixmap> representation of the item at path. This image is used for a drag icon.

icon-view
a <gtk-icon-view>
path
a <gtk-tree-path> in icon-view
ret
a newly-allocated pixmap of the drag icon.

Since 2.8