IconView
Deprecated since version 4.10: Use GridView
instead
Superclasses: Widget
, InitiallyUnowned
, Object
Implemented Interfaces: Accessible
, Buildable
, CellLayout
, ConstraintTarget
, Scrollable
GtkIconView
is a widget which displays data in a grid of icons.
GtkIconView
provides an alternative view on a GtkTreeModel
.
It displays the model as a grid of icons with labels. Like
TreeView
, it allows to select one or multiple items
(depending on the selection mode, see set_selection_mode
).
In addition to selection with the arrow keys, GtkIconView
supports
rubberband selection, which is controlled by dragging the pointer.
Note that if the tree model is backed by an actual tree store (as
opposed to a flat list where the mapping to icons is obvious),
GtkIconView
will only display the first level of the tree and
ignore the tree’s branches.
CSS nodes
iconview.view
╰── [rubberband]
GtkIconView
has a single CSS node with name iconview and style class .view.
For rubberband selection, a subnode with name rubberband is used.
Constructors
- class IconView
- classmethod new() Widget
Creates a new
GtkIconView
widgetDeprecated since version 4.10: Use
GridView
instead
Methods
- class IconView
- create_drag_icon(path: TreePath) Paintable | None
Creates a
GdkPaintable
representation of the item atpath
. This image is used for a drag icon.Deprecated since version 4.10: Use
GridView
instead- Parameters:
path – a
GtkTreePath
inicon_view
- enable_model_drag_dest(formats: ContentFormats, actions: DragAction) None
Turns
icon_view
into a drop destination for automatic DND. Calling this method setsGtkIconView
:reorderable toFalse
.Deprecated since version 4.10: Use
GridView
instead- Parameters:
formats – the formats that the drag will support
actions – the bitmask of possible actions for a drag to this widget
- enable_model_drag_source(start_button_mask: ModifierType, formats: ContentFormats, actions: DragAction) None
Turns
icon_view
into a drag source for automatic DND. Calling this method setsGtkIconView
:reorderable toFalse
.Deprecated since version 4.10: Use
GridView
instead- Parameters:
start_button_mask – Mask of allowed buttons to start drag
formats – the formats that the drag will support
actions – the bitmask of possible actions for a drag from this widget
- get_activate_on_single_click() bool
Gets the setting set by
set_activate_on_single_click()
.Deprecated since version 4.10: Use
GridView
instead
- get_cell_rect(path: TreePath, cell: CellRenderer | None = None) tuple[bool, Rectangle]
Fills the bounding rectangle in widget coordinates for the cell specified by
path
andcell
. Ifcell
isNone
the main cell area is used.This function is only valid if
icon_view
is realized.Deprecated since version 4.10: Use
GridView
instead- Parameters:
path – a
GtkTreePath
cell – a
GtkCellRenderer
- get_column_spacing() int
Returns the value of the ::column-spacing property.
Deprecated since version 4.10: Use
GridView
instead
- get_columns() int
Returns the value of the ::columns property.
Deprecated since version 4.10: Use
GridView
instead
- get_cursor() tuple[bool, TreePath, CellRenderer]
Fills in
path
andcell
with the current cursor path and cell. If the cursor isn’t currently set, then *path
will beNone
. If no cell currently has focus, then *cell
will beNone
.The returned
GtkTreePath
must be freed withfree()
.Deprecated since version 4.10: Use
GridView
instead
- get_dest_item_at_pos(drag_x: int, drag_y: int) tuple[bool, TreePath, IconViewDropPosition]
Determines the destination item for a given position.
Deprecated since version 4.10: Use
GridView
instead- Parameters:
drag_x – the position to determine the destination item for
drag_y – the position to determine the destination item for
- get_drag_dest_item() tuple[TreePath, IconViewDropPosition]
Gets information about the item that is highlighted for feedback.
Deprecated since version 4.10: Use
GridView
instead
- get_item_at_pos(x: int, y: int) tuple[bool, TreePath, CellRenderer]
Gets the path and cell for the icon at the given position.
Deprecated since version 4.10: Use
GridView
instead- Parameters:
x – The x position to be identified
y – The y position to be identified
- get_item_column(path: TreePath) int
Gets the column in which the item
path
is currently displayed. Column numbers start at 0.Deprecated since version 4.10: Use
GridView
instead- Parameters:
path – the
GtkTreePath
of the item
- get_item_orientation() Orientation
Returns the value of the ::item-orientation property which determines whether the labels are drawn beside the icons instead of below.
Deprecated since version 4.10: Use
GridView
instead
- get_item_padding() int
Returns the value of the ::item-padding property.
Deprecated since version 4.10: Use
GridView
instead
- get_item_row(path: TreePath) int
Gets the row in which the item
path
is currently displayed. Row numbers start at 0.Deprecated since version 4.10: Use
GridView
instead- Parameters:
path – the
GtkTreePath
of the item
- get_item_width() int
Returns the value of the ::item-width property.
Deprecated since version 4.10: Use
GridView
instead
- get_margin() int
Returns the value of the ::margin property.
Deprecated since version 4.10: Use
GridView
instead
- get_markup_column() int
Returns the column with markup text for
icon_view
.Deprecated since version 4.10: Use
GridView
instead
- get_model() TreeModel | None
Returns the model the
GtkIconView
is based on. ReturnsNone
if the model is unset.Deprecated since version 4.10: Use
GridView
instead
- get_path_at_pos(x: int, y: int) TreePath | None
Gets the path for the icon at the given position.
Deprecated since version 4.10: Use
GridView
instead- Parameters:
x – The x position to be identified
y – The y position to be identified
- get_pixbuf_column() int
Returns the column with pixbufs for
icon_view
.Deprecated since version 4.10: Use
GridView
instead
- get_reorderable() bool
Retrieves whether the user can reorder the list via drag-and-drop. See
set_reorderable()
.Deprecated since version 4.10: Use
GridView
instead
- get_row_spacing() int
Returns the value of the ::row-spacing property.
Deprecated since version 4.10: Use
GridView
instead
- get_selected_items() list[TreePath]
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
GtkTreeRowReferences
. To do this, you can usenew()
.To free the return value, use
g_list_free_full
:GtkWidget *icon_view = gtk_icon_view_new (); // Use icon_view GList *list = gtk_icon_view_get_selected_items (GTK_ICON_VIEW (icon_view)); // use list g_list_free_full (list, (GDestroyNotify) gtk_tree_path_free);
Deprecated since version 4.10: Use
GridView
instead
- get_selection_mode() SelectionMode
Gets the selection mode of the
icon_view
.Deprecated since version 4.10: Use
GridView
instead
- get_spacing() int
Returns the value of the ::spacing property.
Deprecated since version 4.10: Use
GridView
instead
- get_text_column() int
Returns the column with text for
icon_view
.Deprecated since version 4.10: Use
GridView
instead
- get_tooltip_column() int
Returns the column of
icon_view
’s model which is being used for displaying tooltips onicon_view
’s rows.Deprecated since version 4.10: Use
GridView
instead
- get_tooltip_context(x: int, y: int, keyboard_tip: bool) tuple[bool, TreeModel, TreePath, TreeIter]
This function is supposed to be used in a
GtkWidget::query-tooltip
signal handler forGtkIconView
. Thex
,y
andkeyboard_tip
values which are received in the signal handler, should be passed to this function without modification.The return value indicates whether there is an icon view item at the given coordinates (
True
) or not (False
) for mouse tooltips. For keyboard tooltips the item returned will be the cursor item. WhenTrue
, then any ofmodel
,path
anditer
which have been provided will be set to point to that row and the corresponding model.Deprecated since version 4.10: Use
GridView
instead- Parameters:
x – the x coordinate (relative to widget coordinates)
y – the y coordinate (relative to widget coordinates)
keyboard_tip – whether this is a keyboard tooltip or not
- get_visible_range() tuple[bool, TreePath, TreePath]
Sets
start_path
andend_path
to be the first and last visible path. Note that there may be invisible paths in between.Both paths should be freed with
free()
after use.Deprecated since version 4.10: Use
GridView
instead
- item_activated(path: TreePath) None
Activates the item determined by
path
.Deprecated since version 4.10: Use
GridView
instead- Parameters:
path – The
GtkTreePath
to be activated
- path_is_selected(path: TreePath) bool
Returns
True
if the icon pointed to bypath
is currently selected. Ifpath
does not point to a valid location,False
is returned.Deprecated since version 4.10: Use
GridView
instead- Parameters:
path – A
GtkTreePath
to check selection on.
- scroll_to_path(path: TreePath, use_align: bool, row_align: float, col_align: float) None
Moves the alignments of
icon_view
to the position specified bypath
.row_align
determines where the row is placed, andcol_align
determines wherecolumn
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
isFalse
, 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 theicon_view
is realized, the centered path will be modified to reflect this change.Deprecated since version 4.10: Use
GridView
instead- Parameters:
path – The path of the item to move to.
use_align – whether to use alignment arguments, or
False
.row_align – The vertical alignment of the item specified by
path
.col_align – The horizontal alignment of the item specified by
path
.
- select_all() None
Selects all the icons.
icon_view
must has its selection mode set toMULTIPLE
.Deprecated since version 4.10: Use
GridView
instead
- select_path(path: TreePath) None
Selects the row at
path
.Deprecated since version 4.10: Use
GridView
instead- Parameters:
path – The
GtkTreePath
to be selected.
- selected_foreach(func: Callable[[...], None], *data: Any) None
Calls a function for each selected icon. Note that the model or selection cannot be modified from within this function.
Deprecated since version 4.10: Use
GridView
instead- Parameters:
func – The function to call for each selected icon.
data – User data to pass to the function.
- set_activate_on_single_click(single: bool) None
Causes the
GtkIconView
::item-activated signal to be emitted on a single click instead of a double click.Deprecated since version 4.10: Use
GridView
instead- Parameters:
single –
True
to emit item-activated on a single click
- set_column_spacing(column_spacing: int) None
Sets the ::column-spacing property which specifies the space which is inserted between the columns of the icon view.
Deprecated since version 4.10: Use
GridView
instead- Parameters:
column_spacing – the column spacing
- set_columns(columns: int) None
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.
Deprecated since version 4.10: Use
GridView
instead- Parameters:
columns – the number of columns
- set_cursor(path: TreePath, cell: CellRenderer | None, start_editing: bool) None
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. Ifcell
is notNone
, then focus is given to the cell specified by it. Additionally, ifstart_editing
isTrue
, 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.Deprecated since version 4.10: Use
GridView
instead- Parameters:
path – A
GtkTreePath
cell – One of the cell renderers of
icon_view
start_editing –
True
if the specified cell should start being edited.
- set_drag_dest_item(path: TreePath | None, pos: IconViewDropPosition) None
Sets the item that is highlighted for feedback.
Deprecated since version 4.10: Use
GridView
instead- Parameters:
path – The path of the item to highlight
pos – Specifies where to drop, relative to the item
- set_item_orientation(orientation: Orientation) None
Sets the ::item-orientation property which determines whether the labels are drawn beside the icons instead of below.
Deprecated since version 4.10: Use
GridView
instead- Parameters:
orientation – the relative position of texts and icons
- set_item_padding(item_padding: int) None
Sets the
GtkIconView
:item-padding property which specifies the padding around each of the icon view’s items.Deprecated since version 4.10: Use
GridView
instead- Parameters:
item_padding – the item padding
- set_item_width(item_width: int) None
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.
Deprecated since version 4.10: Use
GridView
instead- Parameters:
item_width – the width for each item
- set_margin(margin: int) None
Sets the ::margin property which specifies the space which is inserted at the top, bottom, left and right of the icon view.
Deprecated since version 4.10: Use
GridView
instead- Parameters:
margin – the margin
- set_markup_column(column: int) None
Sets the column with markup information for
icon_view
to becolumn
. The markup column must be of typeG_TYPE_STRING
. If the markup column is set to something, it overrides the text column set byset_text_column()
.Deprecated since version 4.10: Use
GridView
instead- Parameters:
column – A column in the currently used model, or -1 to display no text
- set_model(model: TreeModel | None = None) None
Sets the model for a
GtkIconView
. If theicon_view
already has a model set, it will remove it before setting the new model. Ifmodel
isNone
, then it will unset the old model.Deprecated since version 4.10: Use
GridView
instead- Parameters:
model – The model.
- set_pixbuf_column(column: int) None
Sets the column with pixbufs for
icon_view
to becolumn
. The pixbuf column must be of typeGDK_TYPE_PIXBUF
Deprecated since version 4.10: Use
GridView
instead- Parameters:
column – A column in the currently used model, or -1 to disable
- set_reorderable(reorderable: bool) None
This function is a convenience function to allow you to reorder models that support the
GtkTreeDragSourceIface
and theGtkTreeDragDestIface
. BothGtkTreeStore
andGtkListStore
support these. Ifreorderable
isTrue
, 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. The reordering is implemented by setting up the icon view as a drag source and destination. Therefore, drag and drop can not be used in a reorderable view for any other purpose.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.
Deprecated since version 4.10: Use
GridView
instead- Parameters:
reorderable –
True
, if the list of items can be reordered.
- set_row_spacing(row_spacing: int) None
Sets the ::row-spacing property which specifies the space which is inserted between the rows of the icon view.
Deprecated since version 4.10: Use
GridView
instead- Parameters:
row_spacing – the row spacing
- set_selection_mode(mode: SelectionMode) None
Sets the selection mode of the
icon_view
.Deprecated since version 4.10: Use
GridView
instead- Parameters:
mode – The selection mode
- set_spacing(spacing: int) None
Sets the ::spacing property which specifies the space which is inserted between the cells (i.e. the icon and the text) of an item.
Deprecated since version 4.10: Use
GridView
instead- Parameters:
spacing – the spacing
- set_text_column(column: int) None
Sets the column with text for
icon_view
to becolumn
. The text column must be of typeG_TYPE_STRING
.Deprecated since version 4.10: Use
GridView
instead- Parameters:
column – A column in the currently used model, or -1 to display no text
- set_tooltip_cell(tooltip: Tooltip, path: TreePath, cell: CellRenderer | None = None) None
Sets the tip area of
tooltip
to the area whichcell
occupies in the item pointed to bypath
. See alsoset_tip_area()
.See also
set_tooltip_column()
for a simpler alternative.Deprecated since version 4.10: Use
GridView
instead- Parameters:
tooltip – a
GtkTooltip
path – a
GtkTreePath
cell – a
GtkCellRenderer
- set_tooltip_column(column: int) None
If you only plan to have simple (text-only) tooltips on full items, you can use this function to have
GtkIconView
handle these automatically for you.column
should be set to the column inicon_view
’s model containing the tooltip texts, or -1 to disable this feature.When enabled,
GtkWidget:has-tooltip
will be set toTrue
andicon_view
will connect aGtkWidget::query-tooltip
signal handler.Note that the signal handler sets the text with
set_markup()
, so &, <, etc have to be escaped in the text.Deprecated since version 4.10: Use
GridView
instead- Parameters:
column – an integer, which is a valid column number for
icon_view
’s model
- set_tooltip_item(tooltip: Tooltip, path: TreePath) None
Sets the tip area of
tooltip
to be the area covered by the item atpath
. See alsoset_tooltip_column()
for a simpler alternative. See alsoset_tip_area()
.Deprecated since version 4.10: Use
GridView
instead- Parameters:
tooltip – a
GtkTooltip
path – a
GtkTreePath
- unselect_path(path: TreePath) None
Unselects the row at
path
.Deprecated since version 4.10: Use
GridView
instead- Parameters:
path – The
GtkTreePath
to be unselected.
- unset_model_drag_dest() None
Undoes the effect of
enable_model_drag_dest()
. Calling this method setsGtkIconView
:reorderable toFalse
.Deprecated since version 4.10: Use
GridView
instead
- unset_model_drag_source() None
Undoes the effect of
enable_model_drag_source()
. Calling this method setsGtkIconView
:reorderable toFalse
.Deprecated since version 4.10: Use
GridView
instead
Properties
- class IconView
- props.activate_on_single_click: bool
The activate-on-single-click property specifies whether the “item-activated” signal will be emitted after a single click.
- props.cell_area: CellArea
The
GtkCellArea
used to layout cell renderers for this view.If no area is specified when creating the icon view with
new_with_area()
aGtkCellAreaBox
will be used.
- props.column_spacing: int
The column-spacing property specifies the space which is inserted between the columns of the icon view.
- props.columns: int
The columns property contains the number of the columns in which the items should be displayed. If it is -1, the number of columns will be chosen automatically to fill the available area.
- props.item_orientation: Orientation
The item-orientation property specifies how the cells (i.e. the icon and the text) of the item are positioned relative to each other.
- props.item_padding: int
The item-padding property specifies the padding around each of the icon view’s item.
- props.item_width: int
The item-width property specifies the width to use for each item. If it is set to -1, the icon view will automatically determine a suitable item size.
- props.margin: int
The margin property specifies the space which is inserted at the edges of the icon view.
- props.markup_column: int
The ::markup-column property contains the number of the model column containing markup information to be displayed. The markup column must be of type
G_TYPE_STRING
. If this property and the :text-column property are both set to column numbers, it overrides the text column. If both are set to -1, no texts are displayed.
- props.pixbuf_column: int
The ::pixbuf-column property contains the number of the model column containing the pixbufs which are displayed. The pixbuf column must be of type
GDK_TYPE_PIXBUF
. Setting this property to -1 turns off the display of pixbufs.
- props.row_spacing: int
The row-spacing property specifies the space which is inserted between the rows of the icon view.
- props.selection_mode: SelectionMode
The ::selection-mode property specifies the selection mode of icon view. If the mode is
MULTIPLE
, rubberband selection is enabled, for the other modes, only keyboard selection is possible.
- props.spacing: int
The spacing property specifies the space which is inserted between the cells (i.e. the icon and the text) of an item.
Signals
- class IconView.signals
- activate_cursor_item() bool
A [keybinding signal]:obj:
SignalAction
which gets emitted when the user activates the currently focused item.Applications should not connect to it, but may emit it with
signal_emit_by_name()
if they need to control activation programmatically.The default bindings for this signal are Space, Return and Enter.
- item_activated(path: TreePath) None
The ::item-activated signal is emitted when the method
item_activated()
is called, when the user double clicks an item with the “activate-on-single-click” property set toFalse
, or when the user single clicks an item when the “activate-on-single-click” property set toTrue
. It is also emitted when a non-editable item is selected and one of the keys: Space, Return or Enter is pressed.- Parameters:
path – the
GtkTreePath
for the activated item
- move_cursor(step: MovementStep, count: int, extend: bool, modify: bool) bool
The ::move-cursor signal is a [keybinding signal]:obj:
SignalAction
which gets emitted when the user initiates a cursor movement.Applications should not connect to it, but may emit it with
signal_emit_by_name()
if they need to control the cursor programmatically.The default bindings for this signal include
Arrow keys which move by individual steps
Home/End keys which move to the first/last item
PageUp/PageDown which move by “pages”
All of these will extend the selection when combined with the Shift modifier.
- Parameters:
step – the granularity of the move, as a
GtkMovementStep
count – the number of
step
units to moveextend – whether to extend the selection
modify – whether to modify the selection
- select_all() None
A [keybinding signal]:obj:
SignalAction
which gets emitted when the user selects all items.Applications should not connect to it, but may emit it with
signal_emit_by_name()
if they need to control selection programmatically.The default binding for this signal is Ctrl-a.
- select_cursor_item() None
A [keybinding signal]:obj:
SignalAction
which gets emitted when the user selects the item that is currently focused.Applications should not connect to it, but may emit it with
signal_emit_by_name()
if they need to control selection programmatically.There is no default binding for this signal.
- selection_changed() None
The ::selection-changed signal is emitted when the selection (i.e. the set of selected items) changes.
- toggle_cursor_item() None
A [keybinding signal]:obj:
SignalAction
which gets emitted when the user toggles whether the currently focused item is selected or not. The exact effect of this depend on the selection mode.Applications should not connect to it, but may emit it with
signal_emit_by_name()
if they need to control selection programmatically.There is no default binding for this signal is Ctrl-Space.
- unselect_all() None
A [keybinding signal]:obj:
SignalAction
which gets emitted when the user unselects all items.Applications should not connect to it, but may emit it with
signal_emit_by_name()
if they need to control selection programmatically.The default binding for this signal is Ctrl-Shift-a.