/
iconview.txt
262 lines (134 loc) · 12.6 KB
/
iconview.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
IconView
========
A :class:`Gtk.IconView` is a widget that displays a collection of icons in a grid view. It supports features such as drag and drop, multiple selections and item reordering.
Similarly to :class:`Gtk.TreeView`, :class:`Gtk.IconView` uses a :class:`Gtk.ListStore` for its model. Instead of using :ref:`cell renderers <cellrenderers>`, :class:`Gtk.IconView` requires that one of the columns in its :class:`Gtk.ListStore` contains :class:`GdkPixbuf.Pixbuf` objects.
:class:`Gtk.IconView` supports numerous selection modes to allow for either selecting multiple icons at a time, restricting selections to just one item or disallowing selecting items completely. To specify a selection mode, the :meth:`Gtk.IconView.set_selection_mode` method is used with one of the :class:`Gtk.SelectionMode` selection modes.
IconView objects
________________
.. class:: Gtk.IconView
.. staticmethod:: new_with_area(area)
Creates a new :class:`Gtk.IconView` widget using the specified *area* to layout cells inside the icons.
.. staticmethod:: new_with_model(model)
Creates a new :class:`Gtk.IconView` widget with the model *model*.
.. method:: set_model(model)
Sets the model for a :class:`Gtk.IconView`. If the :class:`Gtk.IconView` already has a model set, it will remove it before setting the new model. If *model* is ``None``, then it will unset the old model.
.. method:: get_model()
Returns the model the :class:`Gtk.IconView` is based on. Returns ``None`` if the model is unset.
.. method:: set_text_column(column)
Sets the column with text to be *column*. The text column must be of type ``str``.
.. method:: get_text_column()
Return the column with text, or -1 if it's unset.
.. method:: set_markup_column(column)
Sets the column with markup information for the :class:`Gtk.IconView` to be *column*. The markup column must be of type ``str``. If the markup column is set to something, it overrides the text column set by :meth:`set_text_column`.
.. method:: get_markup_column()
Returns the column with markup text, or -1 if it's unset.
.. method:: set_pixbuf_column(column)
Sets the column with pixbufs to be *column*. The pixbuf column must be of type :class:`GdkPixbuf.Pixbuf`
.. method:: get_pixbuf_column()
Returns the column with pixbufs, or -1 if it's unset.
.. method:: get_item_at_pos(x, y)
Finds the path at the point(*x*, *y*), relative to bin_window coordinates. In contrast to :meth:`get_path_at_pos`, this method also obtains the cell at the specified position. See :meth:`convert_widget_to_bin_window_coords` for converting widget coordinates to bin_window coordinates.
.. method:: convert_widget_to_bin_coords(x, y)
Converts widget coordinates to coordinates for the bin_window, as expected by e.g. :meth:`get_path_at_pos`
.. method:: set_cursor(path, cell, start_editing)
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 ``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 :meth:`grab_focus` in order to give keyboard focus to the widget. Please note that editing can only happen when the widget is realized.
.. method:: get_cursor()
Returns 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``.
.. method:: selected_foreach(func, data)
Calls a function for each selected icon. Note that the model or selection cannot be modified from within this method.
.. method:: set_selection_mode(mode)
Sets the :class:`Gtk.SelectionMode` of the :class:`Gtk.IconView`.
.. method:: get_selection_mode()
Gets the :class:`Gtk.SelectionMode` of the :class:`Gtk.IconView`.
.. method:: set_item_orientation(orientation)
Sets the "item-orientation" property which determines whether the labels are drawn beside the icons instead of below.
.. method:: get_item_orientation()
Returns the :class:`Gtk.Orientation` of the "item-orientation" property which determines whether the labels are drawn beside the icons instead of below.
.. method:: set_columns(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.
.. method:: get_columns()
Returns the value of the "columns" property.
.. method:: set_item_width(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.
.. method:: get_item_width()
Returns the value of the "item-width" property.
.. method:: set_spacing(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.
.. method:: set_row_spacing(row_spacing)
Sets the "row-spacing" property which specifies the space which is inserted between the rows of the icon view.
.. method:: get_row_spacing()
Returns the value of the "row-spacing" property.
.. method:: set_column_spacing(column_spacing)
Sets the "column-spacing" property which specifies the space which is inserted between the columns of the icon view.
.. method:: get_column_spacing()
Returns the value of the "column-spacing" property.
.. method:: set_margin(margin)
Sets the "margin" property which specifies the space which is inserted at the top, bottom, left and right of the icon view.
.. method:: get_margin()
Returns the value of the "margin" property.
.. method:: set_item_padding(item_padding)
Sets the "item-padding" property which specifies the padding around each of the icon view's items.
.. method:: get_item_padding()
Returns the value of the "item-padding property.
.. method:: select_path(path)
Selects the row at *path*.
.. method:: unselect_path(path)
Unselects the row at *path*.
.. method:: path_is_selected(path)
Returns ``True`` if the icon pointed to by *path* is currently selected. If *path* does not point to a valid location, ``False`` is returned.
.. 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 :class:`Gtk.TreeRowReference <Gtk.TreeRowReference>`.
.. method:: select_all()
Selects all the icons. The :class:`Gtk.IconView` must has its selection mode set to :attr:`Gtk.SelectionMode.MULTIPLE`
.. method:: unselect_all()
Unselects all the icons.
.. method:: scroll_to_path(path, use_align, row_align, col_align)
Moves the alignments of :class:`Gtk.IconView` to the position specified by *path*. *row_align* determines where the row is placed, the *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``, the 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 :class:`Gtk.IconView` is realized, the centered path will be modified to reflect this change.
.. method:: get_visible_range()
Returns the first and last visible :class:`Gtk.TreePath`. Note that there may be invisible paths in between.
.. method:: set_tooltip_item(tooltip, path)
Sets the tip area of *tooltip* to be the area covered by the item at *path*. See also :meth:`set_tooltip_column` for a simpler alternative. See also :meth:`Gtk.Tooltip.set_tip_area`.
.. method:: set_tooltip_cell(tooltip, path, cell)
Sets the tip area of *tooltip* to the area which *cell* occupies in the item pointed to by *path*. See also :meth:`Gtk.Tooltip.set_tip_area`
See also :meth:`set_tooltip_column` for a simpler alternative.
.. method:: get_tooltip_context(x, y, keyboard_tip)
This function is supposed to be used in a "query-tooltip" signal handler for :class:`Gtk.IconView`. The *x*, *y* and *keyboard_tip* values which are received in the signal handler, should be passed to this method 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. When ``True``, then all of the items which have been returned will be set to point to that row and corresponding model. *x* and *y* will always be converted to be relative to the :class:`Gtk.IconView`'s bin_window if *keyboard_tooltip* is ``False``.
.. method:: set_tooltip_column(column)
If you only plan to have simple (text-only) tooltips on full items, you can use this function to have :class:`Gtk.IconView` handle these automatically for you. *column* should be set to the column in the :class:`Gtk.IconView`'s model containing the tooltip texts, or -1 to disable this feature.
When enabled, "has-tooltip" will be set to ``True`` and :class:`Gtk.IconView` will connect a "query-tooltip" signal handler.
Note that the signal handler sets the text with :meth:`Gtk.Tooltip.set_markup`, so &, <, etc have to be escaped in the text.
.. method:: get_tooltip_column()
Returns the column of :class:`Gtk.IconView`'s model which is being used for displaying tooltips on :class:`Gtk.IconView`'s rows, or -1 if this is disabled.
.. method:: get_item_row(path)
Gets the row in which the item *path* is currently displayed. Row numbers start at 0.
.. method:: get_item_column(path)
Gets the column in which the item *path* is currently displayed. Column numbers start at 0.
.. method:: enable_model_drag_source(start_button_mask, targets, n_targets, actions)
Turns :class:`Gtk.IconView` into a drag source for automatic DND. Calling this method sets "reorderable" to ``False``.
.. method:: enable_model_drag_dest(targets, n_targets, actions)
Turns :class:`Gtk.IconView` into a drop destination for automatic DND. Calling this method sets "reorderable" to ``False``.
.. method:: unset_model_drag_source()
Undoes the effect of :meth:`enable_model_drag_source`. Calling this method sets "reorderable" to ``False``.
.. method:: unset_model_drag_dest()
Undoes the effect of :meth:`enable_model_drag_dest`. Calling this method sets "reorderable" to ``False``.
.. method:: set_reorderable(reorderable)
This method is a convenience method to allow you to reorder models that support the :class:`Gtk.TreeDragSource` and the :class:`Gtk.TreeDragDest` interfaces. Both :class:`Gtk.TreeStore` and :class:`Gtk.ListStore` support these. If *reorderable* is ``True``, then the user can reorder the model by dragging and dropping rows. The developer can listen to these changes by connecting the model's "row_inserted" and "row_deleted" signals. The reordering is implemented by setting up the icon view as 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.
.. method:: get_reorderable()
Retrieves whether the user can reorder the list via drag-and-drop. See :meth:`set_reorderable`.
.. method:: set_drag_dest_item(path, pos)
Sets the item that is highlighted for feedback.
.. method:: get_drag_dest_item()
Gets information about the item that is highlighted for feedback.
.. method:: get_dest_item_at_pos(drag_x, drag_y)
Determines the destination item for a given position.
.. method:: create_drag_icon(path)
Creates a :class:`Cairo.Surface` representation of the item at *path*. This image is used for a drag icon.
Example
_______
.. literalinclude:: ../examples/iconview_example.py
:linenos: