MoSync 3.3
MAUI::Widget Class Reference

A MAUI widget; a graphical object the user can interact with. More...

#include <MAUI/Widget.h>

Inheritance diagram for MAUI::Widget:
MAP::MapWidget MAUI::AnimatedImage MAUI::Image MAUI::Label MAUI::Layout MAUI::ListBox MAUI::EditBox

List of all members.

Public Member Functions

 Widget (int x, int y, int width, int height, Widget *parent)
virtual void add (Widget *w)
virtual void clear ()
void setParent (Widget *w)
WidgetgetParent ()
Vector< Widget * > & getChildren ()
const Vector< Widget * > & getChildren () const
virtual void draw (bool forceDraw=false)
virtual void update ()
void requestRepaint ()
virtual bool isTransparent () const
virtual void setSkin (WidgetSkin *widgetSkin)
void setDrawBackground (bool b=true)
void setBackgroundColor (int col)
WidgetwidgetAt (const Point &p)
WidgetwidgetAt (int x, int y)
virtual void setPosition (int x, int y)
const PointgetPosition () const
const PointgetPaddedPosition () const
virtual void setWidth (int width)
int getWidth () const
virtual void setHeight (int height)
int getHeight () const
virtual const RectgetBounds ()
virtual bool contains (const Point &p)
virtual bool contains (int x, int y)
virtual void setSelected (bool selected=true)
bool isSelected () const
virtual void setEnabled (bool enabled=true)
bool isEnabled () const
virtual void trigger ()
void addWidgetListener (WidgetListener *wl)
void removeWidgetListener (WidgetListener *wl)
Vector< WidgetListener * > & getWidgetListeners ()
void setInputManager (InputManager *inputManager)
virtual void setPaddingLeft (int l)
virtual void setPaddingTop (int t)
virtual void setPaddingRight (int r)
virtual void setPaddingBottom (int b)
int getPaddingLeft () const
int getPaddingTop () const
int getPaddingRight () const
int getPaddingBottom () const
const RectgetPaddedBounds () const
virtual void setParameter (const String &name, const String &value)
virtual ~Widget ()

Protected Member Functions

virtual void drawWidget ()=0
void drawBackground ()
void updateAbsolutePosition ()
void updateAbsolutePositionChildren (int x, int y)
void updatePaddedBounds ()
bool isDirty () const
void setDirty (bool d=true)

Protected Attributes

Vector< Widget * > children
Rect bounds
int relX
int relY
bool dirty
int backColor
bool shouldDrawBackground
bool selected
bool enabled
Vector< WidgetListener * > widgetListeners
Rect paddedBounds
int paddingLeft
int paddingTop
int paddingBottom
int paddingRight


class Screen
class Layout

Detailed Description

A MAUI widget; a graphical object the user can interact with.

A Widget is an object that has a graphical representation and can perform (or be subjected to) interactions by the user. It is abstract, since there is no default implementation of the drawWidget() function.

Examples of components are the images, labels and listboxes you would usually find in a user interface.

The Widget class is the abstract superclass of all MAUI Widgets. It can also be directly inherited to create new Widgets. For simple widgets, all you need to do is to implement the drawWidget() function.

Widgets are rectangular and may not overlap each other. Overlapping widgets lead to undefined rendering behaviour. A widget is clipped by its parent.

Widget constructors take a "parent" argument which, if not NULL, causes the widget being constructed to be added as a child of the parent.

When a Widget is deleted, it deletes all its children as well.

The position of a widget is always expressed relatively to the top left corner of the parent widget.

Widgets have padding parameters, which specify a margin from each side of the widget by which the widgets' content is offset. This applies both to the widgets' own content (such as a the caption of a Label) and its children.

Since mobile devices have different input mechanisms, MAUI Widgets are designed not to depend on any specific form of input. They do not deal with mouse, stylus or key events. Instead, widgets provide logical actions that they can perform. For instance, a listbox does not receive MAK_UP or MAK_DOWN key events - instead, it has the functions selectNextItem() and selectPreviousItem() to move one up or down among the items it contains.

Constructor & Destructor Documentation

MAUI::Widget::Widget ( int  x,
int  y,
int  width,
int  height,
Widget parent 

Constructor for Widget. 'x' and 'y' are the relative position of the top left corner of the widget, and 'width' and 'height' is the dimensions of the widget. 'parent' is the parent to the widget and the widget will be automatically added as a child to the parent. If parent equals NULL no parent will be set.

virtual MAUI::Widget::~Widget ( ) [virtual]

Deletes all children.

Member Function Documentation

virtual void MAUI::Widget::add ( Widget w) [virtual]

Function used to add children to a widget. The parent of the children will automatically be set. The widget cannot have a parent already.

Reimplemented in MAUI::ListBox, and MAUI::Layout.

virtual void MAUI::Widget::clear ( ) [virtual]

Function used to remove all children from a widget. The parent of the children will automatically removed.

Reimplemented in MAUI::ListBox, and MAUI::Layout.

Function used to set the parent of a widget. The widget will not be added to the parent as a child. The widget cannot have a parent already.

Function to retrieve the parent of a widget.

Function to retrieve a reference to the list of childrens for a widget.

const version of getChildren()

virtual void MAUI::Widget::draw ( bool  forceDraw = false) [virtual]

Renders the Widget and all its children recursively.

Reimplemented in MAUI::ListBox.

virtual void MAUI::Widget::update ( ) [virtual]

Called by the Engine before drawing. The Widget should update any cached data here, if needed. The default implementation calls update() on all children.

Reimplemented in MAUI::Layout, MAUI::Label, and MAUI::ListBox.

Registers an idle listener with the current environment that will redraw the widget and anything else that may be made dirty by doing so. For instance, if the widget is transparent its parent also has to be repainted, and so on recursively.

virtual bool MAUI::Widget::isTransparent ( ) const [virtual]

Returns whether or not the widget is transparent. A widget is transparent if it has a skin that is transparent in the current selection state (selected/unselected) or if it has no solid background color.

virtual void MAUI::Widget::setSkin ( WidgetSkin widgetSkin) [virtual]

Assigns a widget skin to be used during the rendering of the widget. What The skin applies to varies depending on the widget. Labels extend the skin over their entire area, while listboxes apply the skin to each individual item they contain.

void MAUI::Widget::setDrawBackground ( bool  b = true)

Sets the background drawing state. If b is true, the Widget's background will be drawn - otherwise not. In most cases, the background is either a constant color or a skin.

Returns a pointer to the first child widget or deeper descendant, surrounding the point. Returns NULL if no widget is found.

Widget* MAUI::Widget::widgetAt ( int  x,
int  y 
virtual void MAUI::Widget::setPosition ( int  x,
int  y 
) [virtual]

setPosition() and getPosition() deal with the widget's position relative to its children. the getBounds() function, however, deals with the absolute position of the widget on the screen. Sets the widget's position relative to its parent.

Reimplemented in MAUI::Layout.

const Point& MAUI::Widget::getPosition ( ) const

Gets the widget's position relative to its parent.

Gets the widget's padded position relative to its parent.

virtual void MAUI::Widget::setWidth ( int  width) [virtual]

Sets the width of the widget

Reimplemented in MAUI::ListBox, MAUI::Layout, and MAP::MapWidget.

int MAUI::Widget::getWidth ( ) const

Returns the width of the widget

virtual void MAUI::Widget::setHeight ( int  height) [virtual]

Sets the height of the widget

Reimplemented in MAUI::ListBox, MAUI::Layout, and MAP::MapWidget.

int MAUI::Widget::getHeight ( ) const

Returns the height of the widget

virtual const Rect& MAUI::Widget::getBounds ( ) [virtual]

Returns a Rect containing the absolute screen position of the widget together with its dimensions.

virtual bool MAUI::Widget::contains ( const Point p) [virtual]

Check if widget surrounds position 'p'.

virtual bool MAUI::Widget::contains ( int  x,
int  y 
) [virtual]

Check if widget surrounds position 'x' and 'y'.

virtual void MAUI::Widget::setSelected ( bool  selected = true) [virtual]

Set widget selected state (default: true).

Reimplemented in MAUI::EditBox.

bool MAUI::Widget::isSelected ( ) const

Is widget selected?.

virtual void MAUI::Widget::setEnabled ( bool  enabled = true) [virtual]

Set Widget enabled state

Reimplemented in MAUI::EditBox.

bool MAUI::Widget::isEnabled ( ) const

Is Widget enabled ?

virtual void MAUI::Widget::trigger ( ) [virtual]

This function is called whenever the widget is "triggered", which is roughly equivalent to having been "clicked" on. However, sice MAUI is independant of input facilities, the more input-neutral concept of triggering is used.

Reimplemented in MAUI::Layout.

returns a reference the the vector of Widget listeners

void MAUI::Widget::setInputManager ( InputManager inputManager)

Sets the input manager to use for this widget

virtual void MAUI::Widget::setPaddingLeft ( int  l) [virtual]

Set left padding width.

Reimplemented in MAUI::Label.

virtual void MAUI::Widget::setPaddingTop ( int  t) [virtual]

Set top padding height.

Reimplemented in MAUI::Label.

virtual void MAUI::Widget::setPaddingRight ( int  r) [virtual]

Set right padding width.

Reimplemented in MAUI::Label.

virtual void MAUI::Widget::setPaddingBottom ( int  b) [virtual]

Set bottom padding height.

Reimplemented in MAUI::Label.

Get left padding width.

Get top padding height.

Get right padding width.

Get bottom padding height.

virtual void MAUI::Widget::setParameter ( const String name,
const String value 
) [virtual]

Reimplemented in MAUI::Label.

virtual void MAUI::Widget::drawWidget ( ) [protected, pure virtual]

This is the only function that is absolutely neccesary to implement when inheriting Widget to create a custom widget. It is responsible for painting the widget. When it is called, the widget must respect its own padded bounds and not extend rendering beyond that area.

Implemented in MAUI::EditBox, MAUI::ListBox, MAP::MapWidget, MAUI::Label, MAUI::Layout, MAUI::Image, and MAUI::AnimatedImage.

void MAUI::Widget::drawBackground ( ) [protected]

This function is used to regenerate the absolute positions of each widget in the tree. This is done in a depth first manner where each widget takes the parent absolute position and adds it to their own relative position to calculate their absolute position.

void MAUI::Widget::updateAbsolutePositionChildren ( int  x,
int  y 
) [protected]

the recursive function used by updateAbsolutePosition().

void MAUI::Widget::updatePaddedBounds ( ) [protected]

Used to recalculate the padded bounds from the global bounds.

bool MAUI::Widget::isDirty ( ) const [protected]

Returns the dirty state of the widget, indicating whether it requires to be redrawn or not. When a widget calls requestRepaint(), it's dirty state is set to true. Normally, you shouldn't have to use isDirty() or setDirty() unless possibly when implementing your own widgets.

void MAUI::Widget::setDirty ( bool  d = true) [protected]

Sets the dirty state of the widget.

Friends And Related Function Documentation

friend class Screen [friend]
friend class Layout [friend]

Member Data Documentation

int MAUI::Widget::relX [protected]
int MAUI::Widget::relY [protected]
bool MAUI::Widget::dirty [protected]
int MAUI::Widget::backColor [protected]
bool MAUI::Widget::selected [protected]
bool MAUI::Widget::enabled [protected]
int MAUI::Widget::paddingLeft [protected]
int MAUI::Widget::paddingTop [protected]
int MAUI::Widget::paddingBottom [protected]
int MAUI::Widget::paddingRight [protected]
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines