#include <Pt/Gui/Widget.h>
Public Member Functions | |
| Widget (Widget &parent, const Math::Point &at, const Math::Size &size) | |
| Constructs a new widget using the given point as position and size as size. | |
| Widget (Widget &parent) | |
| Constructs a new widget using the platform's default position and size. | |
| Widget (const Math::Point &at, const Math::Size &size) | |
| Constructs a new top-level widget using the given point as position and size as size. | |
| Widget () | |
| Constructs a new top-level widget using the platform's default position and size. | |
| virtual | ~Widget () |
| Destructs the widget and frees all resources which are currently used by the widget. | |
| void | setTitle (const Pt::String &text) |
| Sets the title of this widget. | |
| Pt::String | title () |
| Returns the title of this widget. | |
| const Gfx::ARgbColor & | backgroundColor () const |
| Returns a reference to the color which is currently set as background color for this widget. | |
| void | setBackgroundColor (const Gfx::ARgbColor &color) |
| Sets the background color of this widget to the given color. | |
| const Gfx::ARgbColor & | foregroundColor () const |
| Returns a reference to the color which is currently set as foreground color for this widget. | |
| void | setForegroundColor (const Gfx::ARgbColor &color) |
| Sets the foreground color of this widget to the given color. | |
| void | setInsets (const Insets &insets) |
| Sets the insets of this widget. | |
| const Insets & | insets () const |
| Returns the insets of this widget. | |
| const Pt::Gfx::Region & | region () const |
| Returns this widget's current bounding box (= position + size). | |
| const Math::Size & | size () const |
| Returns this widget's current size. | |
| virtual void | move (ssize_t x, ssize_t y) |
| Moves the widget to the given position (x, y). | |
| ssize_t | x () const |
| Returns the x-position of this widget relative to its parent widget. | |
| ssize_t | y () const |
| Returns the y-position of this widget relative to its parent widget. | |
| size_t | width () const |
| Returns the width of this widget. | |
| size_t | height () const |
| Returns the height of this widget. | |
| virtual void | resize (size_t width, size_t height) |
| Resizes this widget to the given width and height. | |
| virtual void | resize (const Math::Size &newSize) |
| Resizes this widget to the given size. | |
| virtual void | show () |
| Makes this widget visible. | |
| virtual void | hide () |
| Makes this widget invisible. | |
| virtual Math::Size | minimumSize () |
| Calculates and returns the minimum size of this widget. | |
| virtual Math::Size | preferredSize () |
| Calculates and returns the preferred size of this widget. | |
| virtual void | updateLayout () |
| Updates the layout of this widget by doing a re-layout of all child widgets. | |
| virtual void | pack () |
| Resizes this top-level widget to its preferred size and layouts its child widgets accordingly. | |
| const LayoutData & | layoutData () const |
| Returns the LayoutData object of this widget. | |
| Layout & | layout () const |
| Returns the LayoutManager which is set for this widget. | |
| const std::list< Widget * > & | childWidgets () |
| Returns a list containing the child widgets of this widget. | |
| const std::list< Widget * > & | childWidgets () const |
| Returns a list containing the child widgets of this widget. | |
| void | unparent () |
| Removes this widget from the child list of its parent and sets the parent to 0. | |
| void | reparent (Widget *parent) |
| Sets a new parent for this widget. | |
| Widget * | parent () const |
| Returns a pointer to the parent widget of this widget. | |
| void | enable () |
Enables this widget. This is the same as calling setEnabled(true);. | |
| void | disable () |
Disabled this widget. This is the same as calling setEnabled(false);. | |
| void | setEnabled (bool newEnabledState) |
| Enables or disables this widget. | |
| bool | isEnabled () const |
| Returns the current enabled/disabled state of this widget. | |
| virtual void | update () |
| Does a complete repaint of this widget's presentation. | |
| Painter | painter () |
| Returns a Painter object to draw on this widget's surface. | |
| void | event (const Event &event) |
| Receives all events for this widgets and dispatches them to specific methods. | |
| void | closeEvent (const CloseEvent &event) |
| Receives and processes a CloseEvent. | |
| void | mouseEvent (const MouseEvent &event) |
| Receives and processes a MouseEvent. | |
| void | mouseMoveEvent (const MouseMoveEvent &event) |
| Receives and processes a MouseMoveEvent. | |
| void | moveEvent (const MoveEvent &event) |
| Receives and processes a MoveEvent. | |
| void | paintEvent (const PaintEvent &event) |
| Receives and processes a PaintEvent. | |
| void | resizeEvent (const ResizeEvent &event) |
| Receives and processes a ResizeEvent. | |
| void | keyEvent (const KeyEvent &event) |
| Receives and processes a KeyEvent. | |
| WidgetImpl & | impl () |
| Returns the platform-dependent implementation of this Widget. | |
| const WidgetImpl & | impl () const |
| Returns the platform-dependent implementation of this Widget. | |
Public Attributes | |
| Signal | closed |
| Signal which is sent when the widget is closed by the underlying platform. To get informed about signals use one of the connect()-methods. | |
| Signal< Widget & > | destroyed |
| Signal which is sent when the widget object is destroyed (-> destructor). To get informed about signals use one of the connect()-methods. | |
Protected Member Functions | |
| virtual void | _event (const Event &event) |
| Receives all events for this widgets and dispatches them to specific methods. | |
| virtual void | _closeEvent (const CloseEvent &event) |
| Receives and processes a CloseEvent. | |
| virtual void | _mouseEvent (const MouseEvent &event) |
| Receives and processes a MouseEvent. | |
| virtual void | _moveEvent (const MoveEvent &event) |
| Receives and processes a MoveEvent. | |
| virtual void | _mouseMoveEvent (const MouseMoveEvent &event) |
| Receives and processes a MouseMoveEvent. | |
| virtual void | _paintEvent (const PaintEvent &event) |
| Receives and processes a PaintEvent by doing a repaint of the widget. | |
| virtual void | _resizeEvent (const ResizeEvent &event) |
| Receives and processes a ResizeEvent. | |
| virtual void | _keyEvent (const KeyEvent &event) |
| Receives and processes a KeyEvent. | |
| void | addChild (Widget &widget) |
| Add the given widget to the child list of this widget. | |
| void | removeChild (Widget &widget) |
| Removes the given widget from the child list of this widget. | |
Friends | |
| class | WidgetImpl |
| class | Layout |
!General presentation properties Each widget has some general presentation properties:
Each widget has a position and size. For top-level widgets this position is relative to top-left corner of the desktop. For child widgets this position is relative to the top-left corner of the parent's widget.
A widget also has a minimum and preferred size, which may depend on its content. These sizes are relevant for layouting and are described below.
Widgets can be shown an hidden. When hidden a widget will still be layouted as if it was visible. Use show() and hide() to show or hide a widget.
!Parent - child relationship In principle any widget can act as a container which can contain child widgets. This widget base class provides operations for this matter. To add a widget to a parent widget, the parent widget can be passed as first argument to the widget class' constructor. This will add the widget to the child list of the parent and set the parent of the newly created widget to the given widget. Adding children to parent widget will create a physical tree structure, for example to create a logical dependency structure.
Nesting widgets by adding a container to a container makes it possible to nest LayoutManagers (see below) which allows the creation of complex layouts using only simple LayoutManagers.
By hiding a parent, all direct or indirect child widgets will be hidden, too.
A widget can be removed from a parent by calling unparent(). To set another widget as new parent reparent() can be used.
The position of a widget is always relative to its parent top-left corner. When a widget is partly or completely outside of the parents bounds it will be clipped.
To access the children of the widget childWidgets() can be called. To access the parent of a widget parent() can be called.
Not every widget does support to contain child widgets. (A button, for example, will possible not have children). In this case the more specific widget class (e.g. Button) may block the attempt to being used as a parent widget during widget creation.
!Event-Handling and signals For a widget a set of GUI events can occur. These events are generated as platform-dependent events and transformed to GUI events before delivered to one of the event-handling method of the widget. All events are delivered to the event()-method from which they are dispatched to one of the XXXevent() methods according to their type. At this point the events are processed internally or may be further delivered to one of the signals the widget provides. The closed-signal will for example be sent as result of a received CloseEvent.
An application can register a slot to one or more of the signals the widget or one of its sub-classes provides by using the connect()-methods.
Sub-classes of Widget can add specific event handling functionality to the existing event-handling methods by overriding the protected event-handling methods which names start with an underscore (_). The public event handling methods contain house-keeping code and call the underscore-methods.
To add support for other events in a sub-class of Widget, the sub-class must override _event(), call it's direct base-class' _event() method (so all other events are still handled correctly) and add the event handling code for the new event.
!Layout-Manager A LayoutManager can be set for every widget. It will layout the child widgets of the widget in a defined way whenever updateLayout() is called. To set the LayoutManager for a widget call the static create()-method of the concrete LayoutManager-class and specify the widget for which the LayoutManager is created.
To help the layouting two methods - minimumSize() and preferredSize() - exist which return the minimum size and preferred size of the widget. The preferred size is used by several LayoutManagers to calculate parts of the positioning and sizing of the involved widgets. The minimum size is used to describe the minimum size a widget should be set to by a layout manager and should be respected by the layouting process. The preferred size usually depends on the content of the widget. The preferred size of the Button, for example, depends on the length of the button's text, its font size, the spacing of the text to the border (=insets) and the border width itself. The optimal presentation concerning all those attributes contribute to the preferred size.
By calling the method pack() the widget will calculate the preferred size of the widget by using the preferred size of all child widgets (and their child widgets) and then resize the top-level widget to this preferred size. This does only work for top-level widgets (=windows and dialogs).
LayoutManager
| Widget | ( | Widget & | parent, | |
| const Math::Point & | at, | |||
| const Math::Size & | size | |||
| ) |
A widget is created. The given parent is set as parent of this widget and the widget is added to the parent's children list. The widget is positioned at the given location using the given size. If the widget is a child widget the position is relative to the parent's top-left corner of the parent. If it is a top-level widget the position is relative to the top-left corner of the desktop.
If the widget is a top-level widget (parent == 0), it is hidden from start. Use show() to show it. Child widgets are visible from start.
| parent | The parent widget for this widget. The widget will become the child of this parent and be shown inside of it. To create a top-level widget 0 can be passed as an argument. | |
| at | The position of this widget inside its parent relative to the parent's top-left corner. | |
| size | The size of this widget. The size must be >0 for width and height. |
A widget is created. The given parent is set as parent of this widget and the widget is added to the parent's children list. The widget is positioned at the default position of the platform. As widget size the default widget size of the platform is used. This is especially useful for top-level widgets when using mobile platforms as they position and size top-level widgets in a way they occupy all of the screen.
If the widget is a top-level widget (parent == 0), it is hidden from start. Use show() to show it. Child widgets are visible from start.
| parent | The parent widget for this widget. The widget will become the child of this parent and be shown inside of it. To create a top-level widget 0 can be passed as an argument. |
| Widget | ( | const Math::Point & | at, | |
| const Math::Size & | size | |||
| ) |
A widget is created. The widget is positioned relative to the top-left corner of the desktop using the given size.
As the widget is a top-level widget it is hidden from start. Use show() to show it.
| at | The position of this widget inside its parent relative to the parent's top-left corner. | |
| size | The size of this widget. The size must be >0 for width and height. |
| Widget | ( | ) |
A widget is created. The widget is positioned at the default position of the platform. As widget size the default widget size of the platform is used. This is especially useful for top-level widgets when using mobile platforms as they position and size top-level widgets in a way they occupy all of the screen.
As the widget is a top-level widget it is hidden from start. Use show() to show it.
| void setTitle | ( | const Pt::String & | text | ) |
Sets the title of this widget. In case the widget is a top-level widget and the platform show's the window's title, the newly set title will be visible immediately. In case this widget is a child widget the call will not have a visible effect as child widgets usually don't have a visible title. In case the widget becomes a top-level widget at a later time the set title will be visible, though.
| text | The new title for this widget. |
| Pt::String title | ( | ) |
| const Gfx::ARgbColor& backgroundColor | ( | ) | const |
| void setBackgroundColor | ( | const Gfx::ARgbColor & | color | ) |
The background color is used to paint the background. The usage of the background color is widget-dependent. For a button this may be the color of the button area, for a label this may be the background where there is no text, for a checkbox this may be the color inside the marker-box. For other widgets the background color may have no meaning at all.
| color | The new background color for this widget. |
| const Gfx::ARgbColor& foregroundColor | ( | ) | const |
| void setForegroundColor | ( | const Gfx::ARgbColor & | color | ) |
The foreground color is the color which is usually used to paint the content of the widget. The usage of the foreground color is widget-dependent. For a button or label this may be the text color, for a checkbox this may be the color of the marker and or other widget it may have no meaning at all.
| color | The new foreground color for this widget. |
| void setInsets | ( | const Insets & | insets | ) |
The insets are the inner spacing between the actual content of the widget and its border. The usage of insets is widget-dependent. For a button this may be the spacing between the button's text and its painted border, for a checkbox this may be the distance between the marker-box and its text.
When a widget contains other widgets (parent-child-relationship) the insets are the spacing between the child widgets and the border of the parent widget.
| insets | The new insets for this widget. |
| const Insets& insets | ( | ) | const |
| const Pt::Gfx::Region& region | ( | ) | const |
A Region object is returned which describes the widget's current bounds; the widget's position and size. For top-level widgets the position is relative to the top-left corner of the desktop. For child widgets the position is relative to the top-left corner of the parent widget.
| const Math::Size& size | ( | ) | const |
The current size of this widget is returned.
rect()
The widget is moved to the specified position. For top-level widgets this position is relative to the top-left corner of the desktop. For child widgets this position is relative to the top-left corner of the parent widget.
Moving a widget will result in a MoveEvent.
| x | The new x-position for this widget. | |
| y | The new y-position for this widget. |
rect()
| ssize_t x | ( | ) | const |
| ssize_t y | ( | ) | const |
| size_t width | ( | ) | const |
| size_t height | ( | ) | const |
| virtual void resize | ( | size_t | width, | |
| size_t | height | |||
| ) | [virtual] |
Resizing a widget will result in a ResizeEvent.
| width | The new width for this widget. | |
| height | The new height for this widget. |
| virtual void resize | ( | const Math::Size & | newSize | ) | [virtual] |
Resizing a widget will result in a ResizeEvent.
| size | The new size for this widget. |
| virtual void show | ( | ) | [virtual] |
The widget will be shown after calling this method. If the widget was invisible before calling this method a PaintEvent is triggered. If the widget already was visible, nothing happens.
| virtual void hide | ( | ) | [virtual] |
The widget will be hidden (not being shown) after calling this method. If the widget already was invisible, nothing happens.
Note that hidden widgets are still layouted by the LayoutManager as if they were visible.
| virtual Math::Size minimumSize | ( | ) | [virtual] |
When resizing a widget the new size should not be smaller than the minimum size returned by this method. The minimum size specifies the size at which the widget can still be shown normally without major graphical glitches.
A call to resize() does no check against the minimum size. The widget can be resized to a smaller size than is returned by minimumSize().
Reimplemented in Button, ImageButton, Label, and Panel.
| virtual Math::Size preferredSize | ( | ) | [virtual] |
The preferred size specifies the size at which the presentation of the widget is optimal. The preferred size depends on the widget, on its content, its insets and its presentation. The preferred size of the Button, for example, depends on the length of the button's text, its font size, the spacing of the text to the border (=insets) and the border width itself.
The optimal presentation concerning all those attributes contribute to the preferred size.
Reimplemented in Button, ImageButton, Label, and Panel.
| virtual void updateLayout | ( | ) | [virtual] |
This methods lays out the child widgets of this widget by initiating the layouting process of the associated LayoutManager.
| virtual void pack | ( | ) | [virtual] |
The widget will calculate the preferred size by considering the preferred sizes of all child widgets (and their child widgets) and then resize this widget so all child widgets can be layouted using their preferred sizes.
This method only has an effect if the widget is a top-level widget (=window or dialog). For child widgets the method does nothing.
Packing a widget will usually result in a ResizeEvent and several PaintEvents as the widget is resized and contained widgets are re-positioned and resized.
| const LayoutData& layoutData | ( | ) | const |
The LayoutData object contains LayoutManager-specific information on how this widget is supposed to be layouted in the LayoutManager's context. TODO Does this method really exist?
| Layout& layout | ( | ) | const |
To set the LayoutManager for a widget use the Factory-method of the specific LayoutManager which should be set. The the documentation of the LayoutManager for further details.
The LayoutManager object returned by this method is of the generic base class for all LayoutManager objects. To access specific functionality of the actual
LayoutManager which is set for this widget, the returned object has to be cast.
| const std::list<Widget*>& childWidgets | ( | ) |
Widgets can be added as child to a widget using the Widget-constructor or by using reparent(). To remove a children from a widget use unparent() or reparent().
| const std::list<Widget*>& childWidgets | ( | ) | const |
Widgets can be added as child to a widget using the Widget-constructor or by using reparent(). To remove a children from a widget use unparent() or reparent().
| void unparent | ( | ) |
If the widget has no parent nothing happens.
The widget becomes a top-level widget when it is removed from its parent. To set another widget as parent reparent() can be used.
| void reparent | ( | Widget * | parent | ) |
If the parent had a parent before this method is called, it is removed from this parent before the given widget is set a parent widget. If the widget had no parent the given widget is set as parent directly.
0 can be passed as parent pointer. In this case this method does the same as unparent().
| Widget* parent | ( | ) | const |
If there is no parent set for this widget, 0 is returned.
| void enable | ( | ) |
| void disable | ( | ) |
| void setEnabled | ( | bool | newEnabledState | ) |
A disabled widget does not receive input events like mouse events or key events. It is usually also displayed as being disabled, for example by showing the text or background in a specific color.
Widgets are enabled by default.
Currently the disable state is not propagated to the child widgets. If all children of a widget also need to be disabled, this has currently to be done manually by disabling/enabling all child widgets.
newEnabledState New enabled state: true for enabled and false for disabled.
| bool isEnabled | ( | ) | const |
If the widget is currently enabled true is returned. If the widget is disabled false is returned.
See setEnabled(bool) for more details about the enabled/disabled state of a widget.
true if this widget is enabled; false if it is disabled. | virtual void update | ( | ) | [virtual] |
Does a complete repaint of this widget. If the widget is backbuffered the backbuffer is drawn on the widget's surface to avoid the possibly complex repaint of the widget's graphical representation.
This method must be overwritten in sub-classes to draw the specific presentation of the concrete widget.
Reimplemented in Button, ImageButton, Label, and Panel.
| Painter painter | ( | ) |
The Painter which is returned by this widget can be used to draw on this widget at every time. Note that the paint operations only affect the widget's surface but not its backbuffer. The backbuffer has to be drawn separately by getting a Painter object for the backbuffer.
The returned Painter can be copied as often as necessary without much overhead. The Painter object should not be stored for a longer time, for example inside a member variable! It should only be held as long as it is needed to finish the current paint process. After this, it should be freed.
Requesting the Painter object may be expensive in resources, so do not request Painter objects multiple times during a paint process, except it is absolutely necessary.
| void event | ( | const Event & | event | ) |
This method only calls _event() and does the house-keeping. For a precise description of the underlying mechanism see _event().
To add event dispatching for new events don't override this method, but override _event() directly.
| event | The event which should be dispatched. |
| void closeEvent | ( | const CloseEvent & | event | ) |
This method only does the house-keeping and then calls _closeEvent(). For a precise description see there.
| event | The CloseEvent which is supposed to be processed. |
| void mouseEvent | ( | const MouseEvent & | event | ) |
This method only does the house-keeping and then calls _mouseEvent(). For a precise description see there.
| event | The MouseEvent which is supposed to be processed. |
| void mouseMoveEvent | ( | const MouseMoveEvent & | event | ) |
This method only does the house-keeping and then calls _mouseMoveEvent(). For a precise description see there.
| event | The MouseMoveEvent which is supposed to be processed. |
| void moveEvent | ( | const MoveEvent & | event | ) |
This method only does the house-keeping and then calls _moveEvent(). For a precise description see there.
This method updates the internally stored position of the widget.
| event | The MoveEvent which is supposed to be processed. |
| void paintEvent | ( | const PaintEvent & | event | ) |
This method only does the house-keeping and then calls _paintEvent(). For a precise description see there.
| event | The PaintEvent which is supposed to be processed. |
| void resizeEvent | ( | const ResizeEvent & | event | ) |
This method only does the house-keeping and then calls _resizeEvent(). For a precise description see there.
This method updates the internally stored size of the widget.
| event | The ResizeEvent which is supposed to be processed. |
| void keyEvent | ( | const KeyEvent & | event | ) |
This method only does the house-keeping and then calls _keyEvent(). For a precise description see there.
| event | The KeyEvent which is supposed to be processed. |
| virtual void _event | ( | const Event & | event | ) | [protected, virtual] |
This method receives all events for this widget and dispatches them to one of the xxxEvent-methods. A CloseEvent is passed to closeEvent(), a MouseEvent is passed to mouseEvent() and so on. These methods forward them to the corresponding method starting with an underscore, for example _closeEvent() and _mouseEvent() after they have finished their house-keeping code.
If the received event is unknown and so can not be dispatched, it is discarded.
To add new events to the dispatch processing this method must be overridden. (Do not override event()!) To allow the _event()-method to dispatch all events which already were know before, the _event()-method of the super-class should be called.
| event | The event which should be dispatched. |
| virtual void _closeEvent | ( | const CloseEvent & | event | ) | [protected, virtual] |
A CloseEvent is generated when a widget is closed, which means that it was destroyed.
When a CloseEvent is received by this method the 'closed' signal is sent to all registered slots.
Override this method to add a more specific CloseEvent-handling.
| event | The CloseEvent which is processed. |
| virtual void _mouseEvent | ( | const MouseEvent & | event | ) | [protected, virtual] |
A MouseEvent is generated when the widget was clicked.
Override this method to add a more specific MouseEvent-handling.
| event | The MouseEvent which is processed. |
Reimplemented in Button, ImageButton, and Label.
| virtual void _moveEvent | ( | const MoveEvent & | event | ) | [protected, virtual] |
A MoveEvent is generated when the widget was moved by the user or when Widget::move() was called.
Override this method to add a more specific MoveEvent-handling.
| event | The MoveEvent which is processed. |
| virtual void _mouseMoveEvent | ( | const MouseMoveEvent & | event | ) | [protected, virtual] |
A MouseMoveEvent is generated when the mouse cursor is moved over the widget or when the mouse cursor enters or leaves the widget.
Override this method to add a more specific MouseMoveEvent-handling.
| event | The MouseMouseEvent which is processed. |
Reimplemented in Button, and ImageButton.
| virtual void _paintEvent | ( | const PaintEvent & | event | ) | [protected, virtual] |
A PaintEvent is usually generated when parts of or all of the widget is disclosed or when the widget becomes visible for other reasons.
Override this method to paint the widget whenever it is necessary.
| event | The PaintEvent which is processed. |
Reimplemented in Button, ImageButton, Label, and Panel.
| virtual void _resizeEvent | ( | const ResizeEvent & | event | ) | [protected, virtual] |
A ResizeEvent is generated when the widget is resized by the user or by a call to Widget::resize().
Override this method to add a more specific ResizeEvent-handling.
| event | The ResizeEvent which is processed. |
Reimplemented in Button, ImageButton, Label, and Panel.
| virtual void _keyEvent | ( | const KeyEvent & | event | ) | [protected, virtual] |
| WidgetImpl& impl | ( | ) |
| const WidgetImpl& impl | ( | ) | const |
| void addChild | ( | Widget & | widget | ) | [protected] |
Note that this method does not update any parent-information. It only does add the widget to the child list without changing any real parent/child-relationship.
Also note that a widget may be added multiple times to this list. No checking is done to prevent this.
| widget | This widget is added to the child list of this widget. |
| void removeChild | ( | Widget & | widget | ) | [protected] |
Note that this method does not update any parent-information. It only does remove the widget from the child list without changing any real parent/child-relationship.
If the given widget can not be found in the child list, nothing happens.
| widget | This widget is removed from the child list of this widget. |