class Component(MessageHandler)

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.