enable.component module

Defines the Component class

class enable.component.Component(**traits)

Bases: enable.coordinate_box.CoordinateBox, enable.interactor.Interactor

Component is the base class for most Enable objects. In addition to the basic position and container features of Component, it also supports Viewports and has finite bounds.

Since Components can have a border and padding, there is an additional set of bounds and position attributes that define the “outer box” of the components. These cannot be set, since they are secondary attributes (computed from the component’s “inner” size and margin-area attributes).

cleanup(window)

When a window viewing or containing a component is destroyed, cleanup is called on the component to give it the opportunity to delete any transient state it may have (such as backbuffers).

dispatch(event, suffix)

Dispatches a mouse event based on the current event state.

If the component has a controller, the method dispatches the event to it, and returns. Otherwise, the following objects get a chance to handle the event:

1. The component’s active tool, if any.

2. Any overlays, in reverse order that they were added and are drawn.

3. The component itself.

4. Any underlays, in reverse order that they were added and are drawn.

5. Any listener tools.

If any object in this sequence handles the event, the method returns without proceeding any further through the sequence. If nothing handles the event, the method simply returns.

Parameters

• event (an Enable MouseEvent) – A mouse event.

• suffix (string) – The name of the mouse event as a suffix to the event state name, e.g. “_left_down” or “_window_enter”.

do_layout(size=None, force=False)

Tells this component to do layout at a given size.

Parameters

• size ((width, height)) – Size at which to lay out the component; either or both values can be 0. If it is None, then the component lays itself out using bounds.

• force (Boolean) – Whether to force a layout operation. If False, the component does a layout on itself only if _layout_needed is True. The method always does layout on any underlays or overlays it has, even if force is False.

draw(gc, view_bounds=None, mode='default')

Draws the plot component.

Parameters

• gc (Kiva GraphicsContext) – The graphics context to draw the component on

• view_bounds (4-tuple of integers) – (x, y, width, height) of the area to draw

• mode (string) –

  The drawing mode to use; can be one of:

  ’normal’

  Normal, antialiased, high-quality rendering

  ’overlay’

  The plot component is being rendered over something else, so it renders more quickly, and possibly omits rendering its background and certain tools

  ’interactive’

  The plot component is being asked to render in direct response to realtime user interaction, and needs to make its best effort to render as fast as possible, even if there is an aesthetic cost.

draw_select_box(gc, position, bounds, width, dash, inset, color, bgcolor, marker_size)

Renders a selection box around the component.

Subclasses can implement this utility method to render a selection box around themselves. To avoid burdening subclasses with various selection-box related traits that they might never use, this method takes all of its required data as input parameters.

Parameters

• gc (Kiva GraphicsContext) – The graphics context to draw on.

• position ((x, y)) – The position of the selection region.

• bounds ((width, height)) – The size of the selection region.

• width (integer) – The width of the selection box border

• dash (float array) – An array of floating point values specifying the lengths of on and off painting pattern for dashed lines.

• inset (integer) – Amount by which the selection box is inset on each side within the selection region.

• color (3-tuple of floats between 0.0 and 1.0) – The R, G, and B values of the selection border color.

• bgcolor (3-tuple of floats between 0.0 and 1.0) – The R, G, and B values of the selection background.

• marker_size (integer) – Size, in pixels, of “handle” markers on the selection box

get_absolute_coords(*coords)

Given coordinates relative to this component’s origin, returns the “absolute” coordinates in the frame of the top-level parent Window enclosing this component’s ancestor containers.

Can be called in two ways:

get_absolute_coords(x, y) get_absolute_coords( (x,y) )

Returns a tuple (x,y) representing the new coordinates.

get_preferred_size()

Returns the size (width,height) that is preferred for this component.

When called on a component that does not contain other components, this method just returns the component bounds. If the component is resizable and can draw into any size, the method returns a size that is visually appropriate. (The component’s actual bounds are determined by its container’s do_layout() method.)

get_relative_coords(*coords)

Given absolute coordinates (where the origin is the top-left corner of the frame in the top-level parent Window) return coordinates relative to this component’s origin.

Can be called in two ways:

get_relative_coords(x, y) get_relative_coords( (x,y) )

Returns a tuple (x,y) representing the new coordinates.

invalidate_and_redraw()

Convenience method to invalidate our contents and request redraw

invalidate_draw(damaged_regions=None, self_relative=False)

Invalidates any backbuffer that may exist, and notifies our parents and viewports of any damaged regions.

Call this method whenever a component’s internal state changes such that it must be redrawn on the next draw() call.

is_in(x, y)

Returns if the point x,y is in the box

request_redraw()

Requests that the component redraw itself. Usually this means asking its parent for a repaint.

set_outer_bounds(ndx, val)

Since self.outer_bounds is a property whose value is determined by other (primary) attributes, it cannot return a mutable type. This method allows generic (i.e. orientation-independent) code to set the value of self.outer_bounds[0] or self.outer_bounds[1].

set_outer_position(ndx, val)

Since self.outer_position is a property whose value is determined by other (primary) attributes, it cannot return a mutable type. This method allows generic (i.e. orientation-independent) code to set the value of self.outer_position[0] or self.outer_position[1].