Component is an abstract base class representing a visual component of
the graphical user interface. A Component owns a rectangular region
of screen space defined by its bounds property. It may be contained
within another component, in which case it is clipped to the boundaries of
its container.
You should not derive directly from Component. Custom components should be based on a View or Frame.
Geometry Properties
The geometry properties control the position and size of the component
within its container. There are several overlapping sets of geometry properties,
corresponding to different ways of defining the component's bounding rectangle.
The properties within each set are orthogonal, meaning that any one of
them may be changed without affecting the others.
- bounds
- A rectangle (left, top, right, bottom) in the container's
coordinate system.
- left
- top
- right
- bottom
- Each of these properties corresponds to one element of the bounds
rectangle. Changing one of these properties changes the position of one
edge of the component without affecting any of the others (and will consequently
change the width or height).
- x
- y
- width
- height
- The x and y properties are the coordinates of the
top left corner of the component in its container's coordinate system.
Assigning to x or y will change the position of the component
within its container, but not its size.
- position
- size
- The position property is equivalent to the tuple (x,
y). The size property is equivalent to the tuple (width, height).
Other Properties
- container
- The Frame which contains this Component, if any. Setting this property
has the effect of removing the Component from the previous container and
adding it to the new container.
- anchor
- This
property controls the layout behaviour of the component when its
container is resized. It is a string made up of the letters 'l', 'r', 't' and 'b' for left, right, top and bottom.
If
the component is anchored to the left or top of its container, it
remains stationary when the container is resized. If it is anchored to
the right or bottom, it moves along with that side of the container. If
it is anchored to both left and right, or both top and bottom, it
stretches when the container is resized.
- border
- Setting this to true requests that the component be given a border.
The width and style of the border (or whether it even exists at all) is platform-dependent.
When the border is present, it is positioned around the outside of the component's
bounds rectangle, and is not included in the component's size.
- tab_stop
- A boolean indicating whether the component can be navigated into using the Tab key.
The default value of this property depends on the component's class, platform conventions and the setting of the PYGUI_KEYBOARD_NAVIGATION
environment variable. For the standard control classes, you should
normally leave it set to the default value so as not to interfere with
the user's expectations. However, you may want to set it to false if
you provide some other way of invoking the control's function using the
keyboard.
Note: This
property is currently ignored for standard controls on MacOSX, where
the platform conventions and the user's System Preferences settings are
always followed.
Resizing Attributes
These attributes determine what happens to the container's position and
size when the size of its container changes as a result of the user resizing
the containing window, or a containing component's resize method
being called. These attributes are typically not set directly, but are established
by the container's place method when the component is added to
the container.
NOTE: Because these are attributes and not properties, you can't set them using keyword arguments in the constructor.
- hmove
- If true, a change to the width of the container causes this component
to move horizontally by the same amount.
- vmove
- If true, a change to the height of the container causes this component
to move vertically by the same amount.
- hstretch
- If true, a change to the width of the container causes the width
of this component to change by the same amount.
- vstretch
- If true, a change to the height of the container causes the height
of this component to change by the same amount.
Methods
- become_target()
- Arranges for this component to have the first chance to handle
keystrokes, menu commands and other messages dispatched to the containing
window. If the component is not contained in a window, the effect is undefined.
Note: Depending on the
platform, not all components may be capable of becoming targets. This
method is only guaranteed to work on components which directly handle
input events. Its effect on other components is undefined.
- is_target()
- Returns true if this component is the current message target
within its containing window. If the component is not contained in a window,
the result is undefined.
- broadcast(message, arg...)
- Traverses the component hierarchy, calling each component's handler for the given message, if any.
Abstract methods
- mouse_down(event)
mouse_drag(event)
mouse_up(event)
mouse_move(event) - These methods are called in response to mouse events occuring in the view. The position attribute
of the event contains the location of the mouse in local coordinates.
- container_resized(delta)
- Called from the resized() method of the component's container. The delta parameter is a tuple (dx, dy)
indicating the amount by which the container has changed size. The
default implementation updates the position and size of the component
according to its resizing options.
- targeted()
- Called whenever this view becomes the current message
target in a visible window.
- untargeted()
- Called whenever this view ceases to be the current
message target in a visible window.
Destructor
- destroy()
- Destroys the component and removes it from the screen. It should not
be used again.