# Class k.u.o.ObjectList(PropertyObject, gtk.ScrolledWindow):

Part of kiwi.ui.objectlist View In Hierarchy

Known subclasses: kiwi.ui.objectlist.ObjectTree, kiwi.ui.search.SearchResults, kiwi.ui.widgets.list.List

An enhanced version of GtkTreeView, which provides pythonic wrappers for accessing rows, and optional facilities for column sorting (with types) and column selection.

Items in an ObjectList is stored in objects. Each row represents an object and each column represents an attribute in the object. The column description object must be a subclass of `Column`. Simple example

    >>> class Fruit:
    >>>    pass

    >>> apple = Fruit()
    >>> apple.name = 'Apple'
    >>> apple.description = 'Worm house'

    >>> banana = Fruit()
    >>> banana.name = 'Banana'
    >>> banana.description = 'Monkey food'

    >>> fruits = ObjectList([Column('name'),
    >>>                      Column('description')])
    >>> fruits.append(apple)
    >>> fruits.append(banana)

# Signals

- row-activated (list, object):
  - Emitted when a row is "activated", eg double clicked or pressing enter. See the GtkTreeView documentation for more information
- selection-changed (list, object):
  - Emitted when the selection changes for the ObjectList enter. See the documentation on GtkTreeSelection::changed for more information
- double-click (list, object):
  - Emitted when a row is double-clicked, mostly you want to use the row-activated signal instead to be able catch keyboard events.
- right-click (list, object):
  - Emitted when a row is clicked with the right mouse button.
- cell-edited (list, object, attribute):
  - Emitted when a cell is edited.
- has-rows (list, bool):
  - Emitted when the objectlist goes from an empty to a non-empty state or vice verse.

# Properties

- selection-mode: gtk.SelectionMode gtk.SELECTION_BROWSE
  - Represents the selection-mode of a GtkTreeSelection of a GtkTreeView.

Method | __init__ | Create a new ObjectList object.
Method | __len__ | len(list)
Method | __nonzero__ | if list
Method | __contains__ | item in list
Method | __iter__ | for item in list
Method | __getitem__ | list[n]
Method | __setitem__ | list[n] = m
Method | extend | Extend list by appending elements from the iterable
Method | index | Return first index of value
Method | count | L.count(item) -> integer -- return number of occurrences of value
Method | insert | Inserts an instance to the list
Method | pop | Remove and return item at index (default last)
Method | reverse | L.reverse() -- reverse *IN PLACE*
Method | sort | L.sort(cmp=None, key=None, reverse=False) -- stable sort *IN PLACE*;
Method | sort_by_attribute | Sort by an attribute in the object model.
Method | set_context_menu | Sets a context-menu (eg, when you right click) for the list.
Method | prop_set_selection_mode | Undocumented
Method | prop_get_selection_mode | Undocumented
Method | _load | Undocumented
Method | _setup_columns | Undocumented
Method | _attach_column | Undocumented
Method | _select_and_focus_row | Undocumented
Method | _on_model__row_inserted | Undocumented
Method | _on_model__row_deleted | Undocumented
Method | _model_sort_func | This method is used to sort the GtkTreeModel
Method | _on_selection__changed | This method is used to proxy selection::changed to selection-changed
Method | _on_scrolled_window__realize | Undocumented
Method | _on_scrolled_window__size_allocate | Resize the Vertical Scrollbar to make it smaller and let space
Method | _treeview_search_equal_func | for searching inside the treeview, case-insensitive by default
Method | _on_treeview_header__button_release_event | Undocumented
Method | _after_treeview__row_activated | After activated (double clicked or pressed enter) on a row
Method | _get_selection_or_selected_rows | Undocumented
Method | _emit_button_press_signal | Undocumented
Method | _on_treeview__button_press_event | Generic button-press-event handler to be able to catch double clicks
Method | _on_treeview__source_drag_data_get | Undocumented
Method | _get_column_button | Return the button widget of a particular TreeViewColumn.
Method | _setup_popup_button | Put a button on top of the vertical scrollbar to show the popup
Method | _find_vertical_scrollbar | This method is called from a .forall() method in the ScrolledWindow.
Method | _get_header_height | Undocumented
Method | get_model | Return treemodel of the current list
Method | get_treeview | Return treeview of the current list
Method | get_columns | Undocumented
Method | get_column_by_name | Returns the name of a column
Method | get_treeview_column | Get the treeview column given an objectlist column
Method | set_spinbutton_digits | Set the number of precision digits used by the spinbutton in
Method | grab_focus | Grabs the focus of the ObjectList
Method | _clear_columns | Undocumented
Method | set_columns | Set columns.
Method | append | Adds an instance to the list.
Method | _remove | Undocumented
Method | remove | Remove an instance from the list.
Method | update | Undocumented
Method | refresh | Reloads the values from all objects.
Method | set_column_visibility | Undocumented
Method | get_selection_mode | Undocumented
Method | set_selection_mode | Undocumented
Method | unselect_all | Undocumented
Method | select_paths | Selects a number of rows corresponding to paths
Method | select | Undocumented
Method | get_selected | Returns the currently selected object
Method | get_selected_rows | Returns a list of currently selected objects
Method | add_list | Allows a list to be loaded, by default clearing it first.
Method | clear | Removes all the instances of the list
Method | get_next | Returns the item after instance in the list.
Method | get_previous | Returns the item before instance in the list.
Method | get_selected_row_number | Get the selected row number or None if no rows were selected
Method | double_click | Same as double clicking on the row rowno
Method | set_headers_visible | Show or hide the headers.
Method | set_visible_rows | Sets the number of visible rows of the treeview. This is useful to use
Method | enable_dnd | Enables Drag and Drop from this object list
Method | get_dnd_targets | Get a list of dnd targets ObjectList supports

Inherited from PropertyObject:

Class Method | __class_init__ | Undocumented
Method | __post_init__ | A hook which is called after the constructor is called.
Method | _set | Undocumented
Method | _get | Undocumented
Method | get_attribute_names | Undocumented
Method | is_default_value | Undocumented
Method | do_set_property | Undocumented
Method | do_get_property | Undocumented

def __init__(self, columns=None, objects=None, mode=gtk.SELECTION_BROWSE, sortable=False, model=None):
overrides kiwi.utils.PropertyObject.__init__
overridden in kiwi.ui.objectlist.ObjectTree, kiwi.ui.search.SearchResults, kiwi.ui.widgets.list.List
Create a new ObjectList object.

Parameters | columns | a list of `Column`s
| objects | a list of objects to be inserted or None
| mode | selection mode
| sortable | whether the user can sort the list
| model | gtk.TreeModel to use or None to create one

def __len__(self):
len(list)

def __nonzero__(self):
if list

def __contains__(self, instance):
item in list

def __iter__(self):
for item in list

def __getitem__(self, arg):
list[n]

def __setitem__(self, arg, item):
list[n] = m

def extend(self, iterable):
Extend list by appending elements from the iterable

Parameters | iterable |

def index(self, item, start=None, stop=None):
Return first index of value

Parameters | item |
| start | @param stop

def count(self, item):
L.count(item) -> integer -- return number of occurrences of value

def insert(self, index, instance, select=False):
Inserts an instance to the list

Parameters | index | position to insert the instance at
| instance | the instance to be added (according to the columns spec)
| select | whether or not the new item should appear selected.

def pop(self, index):
Remove and return item at index (default last)

Parameters | index |

def reverse(self, pos, item):
L.reverse() -- reverse *IN PLACE*

def sort(self, pos, item):
L.sort(cmp=None, key=None, reverse=False) -- stable sort *IN PLACE*; cmp(x, y) -> -1, 0, 1

def sort_by_attribute(self, attribute, order=gtk.SORT_ASCENDING):
Sort by an attribute in the object model.

Parameters | attribute | attribute to sort on (type: string )
| order | one of gtk.SORT_ASCENDING, gtk.SORT_DESCENDING (type: gtk.SortType )

def set_context_menu(self, menu):
Sets a context-menu (eg, when you right click) for the list.

Parameters | menu | context menu (type: ContextMenu )

def prop_set_selection_mode(self, mode):
Undocumented
def prop_get_selection_mode(self):
Undocumented
def _load(self, instances, clear):
Undocumented
def _setup_columns(self, columns):
Undocumented
def _attach_column(self, column):
Undocumented
def _select_and_focus_row(self, row_iter):
Undocumented
def _on_model__row_inserted(self, model, path, iter):
Undocumented
def _on_model__row_deleted(self, model, path):
Undocumented
def _model_sort_func(self, model, iter1, iter2, (column, attr)):
This method is used to sort the GtkTreeModel

def _on_selection__changed(self, selection):
This method is used to proxy selection::changed to selection-changed

def _on_scrolled_window__realize(self, widget):
Undocumented
def _on_scrolled_window__size_allocate(self, widget, allocation):
Resize the Vertical Scrollbar to make it smaller and let space for the popup button. Also put that button there.

def _treeview_search_equal_func(self, model, tree_column, key, treeiter, column):
for searching inside the treeview, case-insensitive by default

def _on_treeview_header__button_release_event(self, button, event):
Undocumented
def _after_treeview__row_activated(self, treeview, path, view_column):
After activated (double clicked or pressed enter) on a row

def _get_selection_or_selected_rows(self):
Undocumented
def _emit_button_press_signal(self, signal_name, event):
Undocumented
def _on_treeview__button_press_event(self, treeview, event):
Generic button-press-event handler to be able to catch double clicks

def _on_treeview__source_drag_data_get(self, treeview, context, selection, info, timestamp):
Undocumented
def _get_column_button(self, column):

Return the button widget of a particular TreeViewColumn.

This hack is needed since that widget is private of the TreeView but we need access to them for Tooltips, right click menus, ...

Use this function at your own risk

def _setup_popup_button(self):
Put a button on top of the vertical scrollbar to show the popup menu. Internally it uses a POPUP window so you can tell how *Evil* is this.

def _find_vertical_scrollbar(self, widget):
This method is called from a .forall() method in the ScrolledWindow. It just save a reference to the vertical scrollbar for doing evil things later.

def _get_header_height(self):
Undocumented
def get_model(self):
Return treemodel of the current list

def get_treeview(self):
Return treeview of the current list

def get_columns(self):
Undocumented
def get_column_by_name(self, name):
Returns the name of a column

def get_treeview_column(self, column):
Get the treeview column given an objectlist column

Parameters | column | a @Column

def set_spinbutton_digits(self, column_name, digits):
Set the number of precision digits used by the spinbutton in a column.

Parameters | column_name | the column name which has the spinbutton (type: str )
| digits | a number specifying the precision digits (type: int )

def grab_focus(self):
Grabs the focus of the ObjectList

def _clear_columns(self):
Undocumented
def set_columns(self, columns):
Set columns.

Parameters | columns | a sequence of `Column` objects.

def append(self, instance, select=False):
overridden in kiwi.ui.objectlist.ObjectTree
Adds an instance to the list.

Parameters | instance | the instance to be added (according to the columns spec)
| select | whether or not the new item should appear selected.

def _remove(self, objid):
Undocumented
def remove(self, instance, select=False):
Remove an instance from the list. If the instance is not in the list it returns False. Otherwise it returns True.

Parameters | instance |
| select | if true, the previous item will be selected if there is one.

def update(self, instance):
Undocumented
def refresh(self, view_only=False):
Reloads the values from all objects.

Parameters | view_only | if True, only force a refresh of the visible part of this objectlist's Treeview.

def set_column_visibility(self, column_index, visibility):
Undocumented
def get_selection_mode(self):
Undocumented
def set_selection_mode(self, mode):
Undocumented
def unselect_all(self):
Undocumented
def select_paths(self, paths):
Selects a number of rows corresponding to paths

Parameters | paths | rows to be selected

def select(self, instance, scroll=True):
Undocumented
def get_selected(self):
Returns the currently selected object If an object is not selected, None is returned

def get_selected_rows(self):
Returns a list of currently selected objects If no objects are selected an empty list is returned

def add_list(self, instances, clear=True):
Allows a list to be loaded, by default clearing it first. freeze() and thaw() are called internally to avoid flashing.

Parameters | instances | a list to be added
| clear | a boolean that specifies whether or not to clear the list

def clear(self):
Removes all the instances of the list

def get_next(self, instance):
Returns the item after instance in the list. Note that the instance must be inserted before this can be called If there are no instances after, the first item will be returned.

Parameters | instance | the instance

def get_previous(self, instance):
Returns the item before instance in the list. Note that the instance must be inserted before this can be called If there are no instances before, the last item will be returned.

Parameters | instance | the instance

def get_selected_row_number(self):
Get the selected row number or None if no rows were selected

def double_click(self, rowno):
Same as double clicking on the row rowno

Parameters | rowno | integer

def set_headers_visible(self, value):
Show or hide the headers.

Parameters | value | if true, shows the headers, if false hide then

def set_visible_rows(self, rows):
Sets the number of visible rows of the treeview. This is useful to use instead of set_size_request() directly, since you can avoid using raw pixel sizes.

Parameters | rows | number of rows to show

def enable_dnd(self):
Enables Drag and Drop from this object list

def get_dnd_targets(self):
Get a list of dnd targets ObjectList supports