List2

class vanilla.List2(posSize, items=[], columnDescriptions=[], allowsSelection=True, allowsMultipleSelection=True, allowsEmptySelection=True, allowsSorting=True, allowColumnReordering=True, enableDelete=False, enableTypingSensitivity=False, showColumnTitles=True, drawFocusRing=True, drawVerticalLines=False, drawHorizontalLines=False, alternatingRowColors=True, autohidesScrollers=False, selectionCallback=None, doubleClickCallback=None, editCallback=None, deleteCallback=None, menuCallback=None, allowsGroupRows=False, floatsGroupRows=False, groupRowCellClass=None, groupRowCellClassArguments={}, autosaveName=None, dragSettings=None, dropSettings=None)

A control that shows a list of items. These lists can contain one or more columns.

posSize Tuple of form (left, top, width, height) or “auto” representing the position and size of the list.

items The items to be displayed in the list. This can be a simple list of basic object types:

• str

• int

• float

• complex

• bool

• None

It may also be a list of dictionaries or other Python objects. The values will be retrieved and set with the provided value and getter and setter defined in the column description. If no getter or setter is given, the column identifier will be used to get and set the value in the item as if the item were a dictionary:

value = item[columnIdentifier]
item[columnIdentifier] = value

columnDescriptions An ordered list of dictionaries describing the columns. This is only necessary for multiple column lists.

“identifier”	The unique identifier for this column.
“title” (optional)	The title to appear in the column header.
“cellClass” (optional)	A cell class to be displayed in the column. If nothing is given, a text cell is used.
“cellClassArguments” (optional)	A dictionary of keyword arguments to be used when cellClass is instantiated.
“valueToCellConverter” (optional)	A function for converting the value for display in the cell.
“cellToValueConverter” (optional)	A function for converting the value displayed in the cell value for storage.
“editable” (optional)	Enable or disable editing in the column. If nothing is given, it will follow the editability of the rest of the list.
“width” (optional)	The width of the column.
“minWidth” (optional)	The minimum width of the column. The fallback is width.
“maxWidth” (optional)	The maximum width of the column. The fallback is width.
“sortable” (optional)	A boolean representing that this column allows the user to sort the table by clicking the column’s header. The fallback is True. If a List is set to disallow sorting the column level settings will be ignored.
property (optional)	A property name for getting and setting the item value.
getMethod (optional)	A method name for getting the item value.
setMethod (optional)	A method name for setting the item value.
getFunction (optional)	A function for getting the item value.
setFunction (optional)	A function for getting the item value.

showColumnTitles Boolean representing if the column titles should be shown or not. Column titles will not be shown in single column lists.

selectionCallback Callback to be called when the selection in the list changes.

doubleClickCallback Callback to be called when an item is double clicked.

editCallback Callback to be called after an item has been edited.

deleteCallback Callback to be called after the delete key has been pressed. The receiver may delete the selection or perform other operations as needed.

menuCallback Callback to be called when a contextual menu is requested.

enableDelete A boolean representing if items in the list can be deleted via the interface. This will be ignored if deleteCallback is given.

enableTypingSensitivity A boolean representing if typing in the list will jump to the closest match as the entered keystrokes.

allowsSelection A boolean representing if items in the list can be selected.

allowsMultipleSelection A boolean representing if the list allows more than one item to be selected.

allowsEmptySelection A boolean representing if the list allows zero items to be selected.

allowsSorting A boolean indicating if the list allows user sorting by clicking column headers.

allowsColumnReordering A boolean indicating if the list allows the user to reorder columns.

drawVerticalLines Boolean representing if vertical lines should be drawn in the list.

drawHorizontalLines Boolean representing if horizontal lines should be drawn in the list.

drawFocusRing Boolean representing if the standard focus ring should be drawn when the list is selected.

alternatingRowColors Boolean representing if alternating row colors should be used.

autohidesScrollers Boolean representing if scrollbars should automatically be hidden if possible.

Group Rows:

It is possible to have rows that act as headers for a group of rows. To do this, add an instance of List2GroupRow to your items.:

class Demo:

    def __init__(self):
        self.w = vanilla.Window((300, 150))
        items = [
            vanilla.List2GroupRow("Group 1"),
            "A",
            "B",
            "C",
            vanilla.List2GroupRow("Group 2"),
            "D",
            "E",
            "F"
        ]
        self.w.list = vanilla.List2(
            "auto",
            items=items,
            allowsGroupRows=True,
            floatsGroupRows=True,
            allowsSorting=False
        )
        rules = [
            "H:|[list]|",
            "V:|[list]|"
        ]
        self.w.addAutoPosSizeRules(rules)
        self.w.open()

allowsGroupRows Boolean representing if the list allows allows group rows.

floatsGroupRows Boolean representing if the list floats the group rows.

groupRowCellClass A cell class to be displayed in the column. If nothing is given, a text cell is used.

groupRowCellClassArguments A dictionary of keyword arguments to be used when groupRowCellClass is instantiated.

autosaveName A string representing a unique name for the list. If given, this name will be used to store the column states in the application preferences.

dropSettings A drop settings dictionary.

Differences from the standard vanilla drag and drop API:

Only these callbacks will be used:

• dropCandidateCallback

• performDropCallback

• dropCandidateEnteredCallback

• dropCandidateEndedCallback

• dropCandidateExitedCallback

dropCandidateCallback should return a boolean indicating if the drop is acceptable instead of a drop operation.

The dragging info dictionary will contain an index key that specifies where in the list the is proposed for insertion. If the list doesn’t allow dropping on or between rows, index will be None.

addAutoPosSizeRules(rules, metrics=None)

Add auto layout rules for controls/view in this view.

rules must be a list of rule definitions. Rule definitions may take two forms:

• strings that follow the Visual Format Language

• dictionaries with the following key/value pairs:

key	value
“view1”	The vanilla wrapped view for the left side of the rule.
“attribute1”	The attribute of the view for the left side of the rule. See below for options.
“relation” (optional)	The relationship between the left side of the rule and the right side of the rule. See below for options. The default value is “==”.
“view2”	The vanilla wrapped view for the right side of the rule.
“attribute2”	The attribute of the view for the right side of the rule. See below for options.
“multiplier” (optional)	The constant multiplied with the attribute on the right side of the rule as part of getting the modified attribute. The default value is 1.
“constant” (optional)	The constant added to the multiplied attribute value on the right side of the rule to yield the final modified attribute. The default value is 0.

The attribute1 and attribute2 options are:

value	AppKit equivalent
“left”	NSLayoutAttributeLeft
“right”	NSLayoutAttributeRight
“top”	NSLayoutAttributeTop
“bottom”	NSLayoutAttributeBottom
“leading”	NSLayoutAttributeLeading
“trailing”	NSLayoutAttributeTrailing
“width”	NSLayoutAttributeWidth
“height”	NSLayoutAttributeHeight
“centerX”	NSLayoutAttributeCenterX
“centerY”	NSLayoutAttributeCenterY
“baseline”	NSLayoutAttributeBaseline
“lastBaseline”	NSLayoutAttributeLastBaseline
“firstBaseline”	NSLayoutAttributeFirstBaseline

Refer to the NSLayoutAttribute documentation for the information about what each of these do.

The relation options are:

value	AppKit equivalent
“<=”	NSLayoutRelationLessThanOrEqual
“==”	NSLayoutRelationEqual
“>=”	NSLayoutRelationGreaterThanOrEqual

Refer to the NSLayoutRelation documentation for the information about what each of these do.

metrics may be either None or a dict containing key value pairs representing metrics keywords used in the rules defined with strings.

enable(onOff)

Enable or disable the object. onOff should be a boolean.

get()

Get the list of items in the list.

getArrangedIndexes()

Get the indexes of the items as they appear to the user in the list.

getArrangedItems()

Get the items as they appear to the user in the list.

getDropItemValues(items, pasteboardType=None)

Get Python objects from the given NSPasteboardItem objects for the given pasteboard type. If this view is registered for only one pasteboard type, None may be given as the pasteboard type.

getEditedIndex()

Return the index of the edited row.

getEditedItem()

Return the item of the edited row.

getNSScrollView()

Return the NSScrollView that this object wraps.

getNSTableView()

Return the NSTableView that this object wraps.

getPosSize()

The position and size of the object as a tuple of form (left, top, width, height).

getSelectedIndexes()

Get a list of indexes of selected items in the list.

getSelectedItems()

Get a list of selected items in the list.

isVisible()

Return a bool indicating if the object is visible or not.

move(x, y)

Move the object by x units and y units.

reloadData(indexes=None)

Reload the data on display. This is needed when the items have changed values and the presentation of the items in the list needs to be updated.

indexes may be provided to indicate that only specific items need to be reloaded.

removeSelection()

Remove selected items.

resize(width, height)

Change the size of the object to width and height.

scrollToIndex(row)

Scroll the row to visible.

scrollToSelection()

Scroll the selected rows to visible.

set(items)

Set the items in the list.

items should follow the same format as described in the constructor.

setBackgroundColor(color)

Set the background of the scrol view to color.

setPosSize(posSize, animate=False)

Set the position and size of the object.

posSize A tuple of form (left, top, width, height).

animate A boolean flag telling to animate the transition. Off by default.

setSelectedIndexes(indexes)

Set the selected indexes in the list.

indexes should be a list of indexes.

setSelectedItems(items)

Set the selected items in the list.

Note

setSelectedIndexes is the recommended method for setting selection. setSelectedItems is a convenience method that relies on iteration and comparing object ids to find the item indexes, which are then sent to setSelectedIndexes. If the list contains a large number of items this iteration can create a performance problem.

setShowFocusRing(value)

Set if the focus ring is visible.

setToolTip(toolTipMessage)

Add tool tip message to the object when hover over it with the cursor.

show(onOff)

Show or hide the object.

onOff A boolean value representing if the object should be shown or not.

List2 Item Cells

vanilla.EditTextList2Cell(alignment='natural', verticalAlignment='center', editable=False, truncationMode='tail', callback=None)

An object that displays text in a List2 column.

alignment The alignment of the text within the row. Options:

• “left”

• “right”

• “center”

• “justified”

• “natural”

verticalAlignment The vertical alignment of the text within the row. Options:

• “top”

• “center”

• “bottom”

truncationMode How text should be truncated. Options:

• “clipping”

• “head”

• “tail”

• “middle”

• A specific NSLineBreakMode.

Note

This class should only be used in the columnDescriptions cellClass argument during the construction of a List. This is never constructed directly.

vanilla.CheckBoxList2Cell(title=None, editable=False, callback=None)

An object that displays a check box in a List2 column.

title The title to be set in all items in the List column.

Note

This class should only be used in the columnDescriptions cellClass argument during the construction of a List. This is never constructed directly.

vanilla.SliderList2Cell(minValue=0, maxValue=100, value=50, tickMarkCount=0, stopOnTickMarks=False, editable=False, callback=None)

An object that displays a slider in a List2 column.

minValue The minimum value for the slider.

maxValue The maximum value for the slider.

tickMarkCount The number of tick marks to be displayed on the slider. If None is given, no tick marks will be displayed.

stopOnTickMarks Boolean representing if the slider knob should only stop on the tick marks.

Note

This class should only be used in the columnDescriptions cellClass argument during the construction of a List. This is never constructed directly.

vanilla.PopUpButtonList2Cell(items=[], editable=False, callback=None, bordered=False)

An object that displays a pop up list in a List2 column.

items The items that should appear in the pop up list.

Note

This class should only be used in the columnDescriptions cellClass argument during the construction of a List. This is never constructed directly.

vanilla.ImageList2Cell(horizontalAlignment='center', verticalAlignment='center', scale='proportional', editable=False, callback=None)

An object that displays an image in a List2 column.

horizontalAlignment A string representing the desired horizontal alignment of the image in the view. The options are:

“left”	Image is aligned left.
“right”	Image is aligned right.
“center”	Image is centered.

verticalAlignment A string representing the desired vertical alignment of the image in the view. The options are:

“top”	Image is aligned top.
“bottom”	Image is aligned bottom.
“center”	Image is centered.

scale A string representing the desired scale style of the image in the view. The options are:

“proportional”	Proportionally scale the image to fit in the view if it is larger than the view.
“fit”	Distort the proportions of the image until it fits exactly in the view.
“none”	Do not scale the image.

Note

This class should only be used in the columnDescriptions cellClass argument during the construction of a List. This is never constructed directly.

vanilla.SegmentedButtonList2Cell(segmentDescriptions=[], selectionStyle='one', editable=False, callback=None)

An object that displays a segmented button in a List2 column.

segmentDescriptions An ordered list of dictionaries describing the segments.

minValue The minimum value for the slider.

maxValue The maximum value for the slider.

imagePath (optional)	A file path to an image to display in the segment.
imageNamed (optional)	The name of an image already loaded as a NSImage by the application to display in the segment.
imageObject (optional)	A NSImage object to display in the segment.

Note

This class should only be used in the columnDescriptions cellClass argument during the construction of a List. This is never constructed directly.

vanilla.ColorWellList2Cell(editable=False, callback=None, colorWellStyle=None)

An object that displays a color well in a List2 column.

title The title to be set in all items in the List column.

Note

This class should only be used in the columnDescriptions cellClass argument during the construction of a List. This is never constructed directly.