traitsui.item module¶

Defines the Item class, which is used to represent a single item within a Traits-based user interface.

class traitsui.item.Custom(value=None, **traits)[source]¶

Bases: Item

An Item using a ‘custom’ style.

class traitsui.item.Heading(label, **traits)[source]¶

Bases: Label

An item that is a fancy label.

style = Constant("custom")¶: Override the ‘style’ trait to default to the fancy ‘custom’ style:

class traitsui.item.Item(value=None, **traits)[source]¶

Bases: ViewSubElement

An element in a Traits-based user interface.

Magic:

Items are rendered as layout elements if name is set to special values:
- name='', the item is rendered as a static label
- name='_', the item is rendered as a separator
- name=' ', the item is rendered as a 5 pixel spacer
- name='23' (any number), the item is rendered as a spacer of the size specified (number of pixels)

defined_when = Str()¶: Pre-condition for including the item in the display. If the expression evaluates to False, the item is not defined in the display. Conditions for defined_when are evaluated only once, when the display is first constructed. Use this attribute for conditions based on attributes that vary from object to object, but that do not change over time. For example, displaying a ‘maiden_name’ item only for female employees in a company database.

dock = ContainerDelegate¶: Docking style for the item:

editor = ItemEditor¶: Editor to use for the item:

editor_args = Dict()¶: Additional editor traits to be set if default traits editor to be used:

emphasized = Bool(False)¶: Should the item’s label use emphasized text? If the label is not shown, this attribute is ignored.

enabled_when = Str()¶: Pre-condition for enabling the item. If the expression evaluates to False, the widget is disabled, that is, it does not accept input. All enabled_when conditions are checked each time that any trait value on an object in the UI’s context is changed. Therefore, you can use enabled_when conditions to enable or disable widgets in response to user input. Be aware that this only applies to traits in the UI’s context. As a result, changes to nested traits that don’t also change a trait on some object in the context may not trigger the expression to be checked. Additionally, the expression needs to be a valid python expression given the context. i.e. eval(enabled_when, globals=globals(), locals=context) should succeed.

export = ContainerDelegate¶: Category of elements dragged from view:

format_func = Callable()¶: A Callable to use for formatting the contents of the item. This function or method is called to create the string representation of the trait value to be edited. If the widget does not use a string representation, this attribute is ignored.

format_str = Str()¶: Python format string to use for formatting the contents of the item. The format string is applied to the string representation of the trait value before it is displayed in the widget. This attribute is ignored if the widget does not use a string representation, or if the format_func is set.

get_help(ui)[source]¶: Gets the help text associated with the Item in a specified UI.

get_id()[source]¶: Returns an ID used to identify the item.

get_label(ui)[source]¶

Gets the label to use for a specified Item.

If not specified, the label is set as the name of the corresponding trait, replacing ‘_’ with ‘ ‘, and capitalizing the first letter (see user_name_for()). This is called the user name.

Magic:

if attr:item.label is specified, and it begins with ‘…’, the final label is the user name followed by the item label
if attr:item.label is specified, and it ends with ‘…’, the final label is the item label followed by the user name

has_focus = Bool(False)¶: Should the item receive focus initially?

height = Float(-1.0)¶

Requested height of the editor (in pixels or fraction of available height). For pixel values (i.e. values not in the range from 0.0 to 1.0), the actual displayed height is at least the maximum of height and the optimal height of the widget as calculated by the GUI toolkit. Specify a negative value to ignore the toolkit’s optimal height. For example, use -50 to force a height of 50 pixels. The default value of -1 ensures that the toolkit’s optimal height is used.

A value in the range from 0.0 to 1.0 specifies the fraction of the available height to assign to the editor. Note that the value is not an absolute value, but is relative to other item’s whose height is also in the 0.0 to 1.0 range. For example, if you have two item’s with a height of 0.1, and one item with a height of 0.2, the first two items will each receive 25% of the available height, while the third item will receive 50% of the available height. The available height is the total height of the view minus the height of any item’s with fixed pixel sizes (i.e. height values not in the 0.0 to 1.0 range).

help = Str()¶: Help text describing the purpose of the item. The built-in help handler displays this text in a pop-up window if the user clicks the widget’s label. View-level help displays the help text for all items in a view. If this attribute is not set, the built-in help handler generates a description based on the trait definition.

id = Str()¶: A unique identifier for the item. If not set, it defaults to the value of name.

image = ContainerDelegate¶: Image to display on notebook tabs:

invalid = Str()¶: The extended trait name of the trait containing the item’s invalid state status (passed through to the item’s editor):

is_includable()[source]¶: Returns a Boolean indicating whether the object is replaceable by an Include object.

is_spacer()[source]¶: Returns True if the item represents a spacer or separator.

label = Str()¶: User interface label for the item in the GUI. If this attribute is not set, the label is the value of name with slight modifications: underscores are replaced by spaces, and the first letter is capitalized. If an item’s name is not specified, its label is displayed as static text, without any editor widget.

name = Str()¶: Name of the trait the item is editing:

object = ContainerDelegate¶: The HasTraits object whose trait attribute the item is editing:

padding = Padding¶: Amount of extra space, in pixels, to add around the item. Values must be integers between -15 and 15. Use negative values to subtract from the default spacing.

resizable = Bool(Undefined)¶: Should the item use extra space along its Group’s non-layout axis? If set to True, the widget expands to fill any extra space that is available in the display. If set to True for more than one item in the same View, any extra space is divided between them. If set to False, the widget uses only whatever space it is explicitly (or implicitly) assigned. The default value of Undefined means that the use (or non-use) of extra space will be determined by the editor associated with the item.

show_label = Delegate("container", "show_labels")¶: Should a label be displayed for the item?

springy = Bool(False)¶: Should the item use extra space along its Group’s layout axis? For example, it a vertical group, should an item expand vertically to use any extra space available in the group?

style = ContainerDelegate¶: Presentation style for the item:

style_sheet = Str()¶: Style-sheet to apply to item / group (Qt only)

tooltip = Str()¶: Tooltip to display over the item, when the mouse pointer is left idle over the widget. Make this text as concise as possible; use the help attribute to provide more detailed information.

visible_when = Str()¶: Pre-condition for showing the item. If the expression evaluates to False, the widget is not visible (and disappears if it was previously visible). If the value evaluates to True, the widget becomes visible. All visible_when conditions are checked each time that any trait value on an object in the UI’s context is changed. Therefore, you can use visible_when conditions to hide or show widgets in response to user input. Be aware that this only applies to traits in the UI’s context. As a result, changes to nested traits that don’t also change a trait on some object in the context may not trigger the expression to be checked. Additionally, the expression needs to be a valid python expression given the context. i.e. eval(visible_when, globals=globals(), locals=context) should succeed.

width = Float(-1.0)¶

Requested width of the editor (in pixels or fraction of available width). For pixel values (i.e. values not in the range from 0.0 to 1.0), the actual displayed width is at least the maximum of width and the optimal width of the widget as calculated by the GUI toolkit. Specify a negative value to ignore the toolkit’s optimal width. For example, use -50 to force a width of 50 pixels. The default value of -1 ensures that the toolkit’s optimal width is used.

A value in the range from 0.0 to 1.0 specifies the fraction of the available width to assign to the editor. Note that the value is not an absolute value, but is relative to other item’s whose width is also in the 0.0 to 1.0 range. For example, if you have two item’s with a width of 0.1, and one item with a width of 0.2, the first two items will each receive 25% of the available width, while the third item will receive 50% of the available width. The available width is the total width of the view minus the width of any item’s with fixed pixel sizes (i.e. width values not in the 0.0 to 1.0 range).

class traitsui.item.Label(label, **traits)[source]¶

Bases: Item

An item that is a label.

class traitsui.item.Readonly(value=None, **traits)[source]¶

Bases: Item

An Item using a ‘readonly’ style.

class traitsui.item.Spring(value=None, **traits)[source]¶

Bases: Item

An item that is a layout “spring”.

editor = Instance("traitsui.api.NullEditor", ())¶: Editor to use for the item

name = "trait_modified"¶: Name of the trait the item is editing Just a dummy trait that exists on all HasTraits objects. It’s an Event, so it won’t cause Traits UI to add any synchronization, and because it already exists, it won’t force the addition of a new trait with a bogus name.