Gtk.IconView


Gtk.IconView — A widget which displays a list of icons in a grid

Object Hierarchy:

    GObject
    ╰── GInitiallyUnowned
        ╰── Gtk.Widget
            ╰── Gtk.Container
                ╰── Gtk.IconView

Functions:


Signals:

  • “activate-cursor-item” (iconview, user_data)
  • “item-activated” (iconview, path, user_data)
  • “move-cursor” (iconview, step, count, user_data)
  • “select-all” (iconview, user_data)
  • “select-cursor-item” (iconview, user_data)
  • “selection-changed” (iconview, user_data)
  • “toggle-cursor-item” (iconview, user_data)
  • “unselect-all” (iconview, user_data)

Description:

GtkIconView provides an alternative view on a Gtk.TreeModel.

It displays the model as a grid of icons with labels. Like Gtk.TreeView, it allows to select one or multiple items (depending on the selection mode, see Gtk.IconView::set_selection_mode()).

In addition to selection with the arrow keys, Gtk.IconView 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), Gtk.IconView will only display the first level of the tree and ignore the tree’s branches.


Function Details:

new()

new () -> Gtk.Widget

Creates a new Gtk.IconView widget

  • Returns: A newly created Gtk.IconView widget

  • Since: 2.6


new_with_area()

new_with_area (area:Gtk.CellArea) -> Gtk.Widget

Creates a new Gtk.IconView widget using thespecified area to layout cells inside the icons.

  • Returns: A newly created Gtk.IconView widget

  • Since: 3.0


new_with_model()

new_with_model (model:Gtk.TreeModel) -> Gtk.Widget

Creates a new Gtk.IconView widget with the model model.

  • Returns: A newly created Gtk.IconView widget.

  • Since: 2.6


set_model()

set_model (self, model:Gtk.TreeModel=None)

Sets the model for a Gtk.IconView.If the icon_view already has a model set, it will removeit before setting the new model. If model is None, thenit will unset the old model.

  • Since: 2.6

get_model()

get_model (self) -> Gtk.TreeModel

Returns the model the Gtk.IconView is based on. Returns None if themodel is unset.

  • Returns: A Gtk.TreeModel, or None if none iscurrently being used.

  • Since: 2.6


set_text_column()

set_text_column (self, column:int)

Sets the column with text for icon_view to be column. The textcolumn must be of type G_TYPE_STRING.

  • Since: 2.6

get_text_column()

get_text_column (self) -> int

Returns the column with text for icon_view.

  • Returns: the text column, or -1 if it’s unset.

  • Since: 2.6


set_markup_column()

set_markup_column (self, column:int)

Sets the column with markup information for icon_view to becolumn. The markup column must be of type G_TYPE_STRING.If the markup column is set to something, it overridesthe text column set by Gtk.IconView:set_text_column().

  • Since: 2.6

get_markup_column()

get_markup_column (self) -> int

Returns the column with markup text for icon_view.

  • Returns: the markup column, or -1 if it’s unset.

  • Since: 2.6


set_pixbuf_column()

set_pixbuf_column (self, column:int)

Sets the column with pixbufs for icon_view to be column. The pixbufcolumn must be of type GDK_TYPE_PIXBUF

  • Since: 2.6

get_pixbuf_column()

get_pixbuf_column (self) -> int

Returns the column with pixbufs for icon_view.

  • Returns: the pixbuf column, or -1 if it’s unset.

  • Since: 2.6


get_path_at_pos()

get_path_at_pos (self, x:int, y:int) -> Gtk.TreePath

Finds the path at the point (x, y), relative to bin_window coordinates.See Gtk.IconView:get_item_at_pos(), if you are also interested inthe cell at the specified position. See Gtk.IconView:convert_widget_to_bin_window_coords() for convertingwidget coordinates to bin_window coordinates.

  • Returns: The Gtk.TreePath corresponding to the icon or Noneif no icon exists at that position.

  • Since: 2.6


convert_widget_to_bin_window_coords()

convert_widget_to_bin_window_coords (self, wx:int, wy:int) -> bx:int, by:int

Converts widget coordinates to coordinates for the bin_window,as expected by e.g. Gtk.IconView:get_path_at_pos().

  • Since: 2.12

set_cursor()

set_cursor (self, path:Gtk.TreePath, cell:Gtk.CellRenderer=None, start_editing:bool)

Sets the current keyboard focus to be at path, and selects it. This isuseful when you want to focus the user’s attention on a particular item.If cell is not None, then focus is given to the cell specified by it. Additionally, if start_editing is True, 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.

  • Since: 2.8

get_cursor()

get_cursor (self) -> bool, path:Gtk.TreePath, cell:Gtk.CellRenderer

Fills in path and cell with the current cursor path and cell. If the cursor isn’t currently set, then path will be None. If no cell currently has focus, then cell will be None. The returned Gtk.TreePath must be freed with `Gtk.TreePath:free()`.

  • Returns: True if the cursor is set.

  • Since: 2.8


selected_foreach()

selected_foreach (self, func:Gtk.IconViewForeachFunc, data=None)

Calls a function for each selected icon. Note that the model orselection cannot be modified from within this function.

  • Since: 2.6

set_selection_mode()

set_selection_mode (self, mode:Gtk.SelectionMode)

Sets the selection mode of the icon_view.

  • Since: 2.6

get_selection_mode()

get_selection_mode (self) -> Gtk.SelectionMode

Gets the selection mode of the icon_view.

  • Returns: the current selection mode

  • Since: 2.6


set_item_orientation()

set_item_orientation (self, orientation:Gtk.Orientation)

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

  • Since: 2.6

get_item_orientation()

get_item_orientation (self) -> Gtk.Orientation

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

  • Returns: the relative position of texts and icons

  • Since: 2.6


set_columns()

set_columns (self, columns:int)

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

  • Since: 2.6

get_columns()

get_columns (self) -> int

Returns the value of the ::columns property.

  • Returns: the number of columns, or -1

  • Since: 2.6


set_item_width()

set_item_width (self, item_width:int)

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.

  • Since: 2.6

get_item_width()

get_item_width (self) -> int

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

  • Returns: the width of a single item, or -1

  • Since: 2.6


set_spacing()

set_spacing (self, spacing:int)

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

  • Since: 2.6

get_spacing()

get_spacing (self) -> int

Returns the value of the ::spacing property.

  • Returns: the space between cells

  • Since: 2.6


set_row_spacing()

set_row_spacing (self, row_spacing:int)

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

  • Since: 2.6

get_row_spacing()

get_row_spacing (self) -> int

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

  • Returns: the space between rows

  • Since: 2.6


set_column_spacing()

set_column_spacing (self, column_spacing:int)

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

  • Since: 2.6

get_column_spacing()

get_column_spacing (self) -> int

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

  • Returns: the space between columns

  • Since: 2.6


set_margin()

set_margin (self, margin:int)

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

  • Since: 2.6

get_margin()

get_margin (self) -> int

Returns the value of the ::margin property.

  • Returns: the space at the borders

  • Since: 2.6


set_item_padding()

set_item_padding (self, item_padding:int)

Sets the “item-padding” property which specifies the paddingaround each of the icon view’s items.

  • Since: 2.18

get_item_padding()

get_item_padding (self) -> int

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

  • Returns: the padding around items

  • Since: 2.18


set_activate_on_single_click()

set_activate_on_single_click (self, single:bool)

Causes the “item-activated” signal to be emitted ona single click instead of a double click.

  • Since: 3.8

get_activate_on_single_click()

get_activate_on_single_click (self) -> bool

Gets the setting set by Gtk.IconView:set_activate_on_single_click().

  • Returns: True if item-activated will be emitted on a single click

  • Since: 3.8


get_cell_rect()

get_cell_rect (self, path:Gtk.TreePath, cell:Gtk.CellRenderer=None) -> bool, rect:Gdk.Rectangle

Fills the bounding rectangle in widget coordinates for the cell specified bypath and cell. If cell is None the main cell area is used. This function is only valid if icon_view is realized.

  • Returns: FALSE if there is no such item, True otherwise

  • Since: 3.6


select_path()

select_path (self, path:Gtk.TreePath)

Selects the row at path.

  • Since: 2.6

unselect_path()

unselect_path (self, path:Gtk.TreePath)

Unselects the row at path.

  • Since: 2.6

path_is_selected()

path_is_selected (self, path:Gtk.TreePath) -> bool

Returns True if the icon pointed to by path is currentlyselected. If path does not point to a valid location, FALSE is returned.

  • Returns: True if pathis selected.

  • Since: 2.6


get_selected_items()

get_selected_items (self) -> list

Creates a list of paths of all selected items. Additionally, if you areplanning on modifying the model after calling this function, you maywant to convert the returned list into a list of Gtk.TreeRowReferences.To do this, you can use `Gtk.TreeRowReference:new(). To free the return value, use: g_list_free_full (list, (GDestroyNotify)Gtk.TreePath:free);`

  • Returns: A GList containing a Gtk.TreePath for each selected row.

  • Since: 2.6


select_all()

select_all (self)

Selects all the icons. icon_view must has its selection mode setto GTK_SELECTION_MULTIPLE.

  • Since: 2.6

unselect_all()

unselect_all (self)

Unselects all the icons.

  • Since: 2.6

item_activated()

item_activated (self, path:Gtk.TreePath)

Activates the item determined by path.

  • Since: 2.6

scroll_to_path()

scroll_to_path (self, path:Gtk.TreePath, use_align:bool, row_align:float, col_align:float)

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 FALSE, then the alignment arguments are ignored, and thetree 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 currentposition. 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.

  • Since: 2.8

set_tooltip_item()

set_tooltip_item (self, tooltip:Gtk.Tooltip, path:Gtk.TreePath)

Sets the tip area of tooltip to be the area covered by the item at path.See also Gtk.IconView:set_tooltip_column() for a simpler alternative.See also `Gtk.Tooltip:set_tip_area()`.

  • Since: 2.12

set_tooltip_cell()

set_tooltip_cell (self, tooltip:Gtk.Tooltip, path:Gtk.TreePath, cell:Gtk.CellRenderer=None)

Sets the tip area of tooltip to the area which cell occupies inthe item pointed to by path. See also `Gtk.Tooltip:set_tip_area(). See alsoGtk.IconView:set_tooltip_column()` for a simpler alternative.

  • Since: 2.12

get_tooltip_context()

get_tooltip_context (self, x:int, y:int, keyboard_tip:bool) -> bool, x:int, y:int, model:Gtk.TreeModel, path:Gtk.TreePath, iter:Gtk.TreeIter

This function is supposed to be used in a “query-tooltip”signal handler for Gtk.IconView. The x, y and keyboard_tip valueswhich are received in the signal handler, should be passed to thisfunction without modification. The return value indicates whether there is an icon view item at the givencoordinates (True) or not (FALSE) for mouse tooltips. For keyboardtooltips the item returned will be the cursor item. When True, then any ofmodel, path and iter which have been provided will be set to point tothat row and the corresponding model. x and y will always be convertedto be relative to icon_view’s bin_window if keyboard_tooltip is FALSE.

  • Returns: whether or not the given tooltip context points to a item

  • Since: 2.12


set_tooltip_column()

set_tooltip_column (self, column:int)

If you only plan to have simple (text-only) tooltips on full items, youcan use this function to have Gtk.IconView handle these automaticallyfor you. column should be set to the column in icon_view’s modelcontaining the tooltip texts, or -1 to disable this feature. When enabled, “has-tooltip” will be set to True andicon_view will connect a “query-tooltip” signal handler. Note that the signal handler sets the text with `Gtk.Tooltip:set_markup()`,so &, <, etc have to be escaped in the text.

  • Since: 2.12

get_tooltip_column()

get_tooltip_column (self) -> int

Returns the column of icon_view’s model which is being used fordisplaying tooltips on icon_view’s rows.

  • Returns: the index of the tooltip column that is currently beingused, or -1 if this is disabled.

  • Since: 2.12


get_item_row()

get_item_row (self, path:Gtk.TreePath) -> int

Gets the row in which the item path is currentlydisplayed. Row numbers start at 0.

  • Returns: The row in which the item is displayed

  • Since: 2.22


get_item_column()

get_item_column (self, path:Gtk.TreePath) -> int

Gets the column in which the item path is currentlydisplayed. Column numbers start at 0.

  • Returns: The column in which the item is displayed

  • Since: 2.22


enable_model_drag_source()

enable_model_drag_source (self, start_button_mask:Gdk.ModifierType, targets:list, actions:Gdk.DragAction)

Turns icon_view into a drag source for automatic DND. Calling thismethod sets “reorderable” to FALSE.

  • Since: 2.8

enable_model_drag_dest()

enable_model_drag_dest (self, targets:list, actions:Gdk.DragAction)

Turns icon_view into a drop destination for automatic DND. Calling thismethod sets “reorderable” to FALSE.

  • Since: 2.8

unset_model_drag_source()

unset_model_drag_source (self)

Undoes the effect of Gtk.IconView:enable_model_drag_source(). Calling thismethod sets “reorderable” to FALSE.

  • Since: 2.8

unset_model_drag_dest()

unset_model_drag_dest (self)

Undoes the effect of Gtk.IconView:enable_model_drag_dest(). Calling thismethod sets “reorderable” to FALSE.

  • Since: 2.8

set_reorderable()

set_reorderable (self, reorderable:bool)

This function is a convenience function to allow you to reorder models thatsupport the Gtk.TreeDragSourceIface and the Gtk.TreeDragDestIface. BothGtk.TreeStore and Gtk.ListStore support these. If reorderable is True, thenthe user can reorder the model by dragging and dropping rows. Thedeveloper can listen to these changes by connecting to the model'srow_inserted and row_deleted signals. The reordering is implemented by setting upthe icon view as a drag source and destination. Therefore, drag anddrop 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 -- anyreordering is allowed. If more control is needed, you should probablyhandle drag and drop manually.

  • Since: 2.8

get_reorderable()

get_reorderable (self) -> bool

Retrieves whether the user can reorder the list via drag-and-drop. See Gtk.IconView:set_reorderable().

  • Returns: True if the list can be reordered.

  • Since: 2.8


set_drag_dest_item()

set_drag_dest_item (self, path:Gtk.TreePath=None, pos:Gtk.IconViewDropPosition)

Sets the item that is highlighted for feedback.

  • Since: 2.8

get_drag_dest_item()

get_drag_dest_item (self) -> path:Gtk.TreePath, pos:Gtk.IconViewDropPosition

Gets information about the item that is highlighted for feedback.

  • Since: 2.8

create_drag_icon()

create_drag_icon (self, path:Gtk.TreePath) -> cairo.Surface

Creates a cairo_surface_t representation of the item at path. This image is used for a drag icon.

  • Returns: a newly-allocated surface of the drag icon.

  • Since: 2.8


Example:

import gi
gi.require_version('Gtk', '3.0')
from gi.repository import Gtk
from gi.repository import GdkPixbuf

distributions = ["fedora", "mandriva", "zenwalk", "knoppix", "debian"]

class IconView(Gtk.Window):
    def __init__(self):
        Gtk.Window.__init__(self)
        self.set_title("IconView")
        self.connect("destroy", Gtk.main_quit)

        self.liststore = Gtk.ListStore(str, GdkPixbuf.Pixbuf, str)

        iconview = Gtk.IconView()
        iconview.set_model(self.liststore)
        iconview.set_text_column(0)
        iconview.set_pixbuf_column(1)
        iconview.set_tooltip_column(2)
        iconview.connect("item-activated", self.on_iconview_activated)
        self.add(iconview)

        image = Gtk.Image()

        for item in distributions:
            path = "../_resources/%s.ico" % (item)
            image.set_from_file(path)
            pixbuf = image.get_pixbuf()

            name = item.capitalize()
            tooltip = "%s tooltip example" % (name)

            self.liststore.append([name, pixbuf, tooltip])

    def on_iconview_activated(self, iconview, treepath):
        print("Selected item: %s" % (self.liststore[treepath][0]))

window = IconView()
window.show_all()

Gtk.main()

results matching ""

    No results matching ""