GuiElement Class Reference
[2D graphical user interface]

Base class for all graphical user interface objects. More...

#include <guielement.h>

Inheritance diagram for GuiElement:

Inheritance graph
[legend]
Collaboration diagram for GuiElement:

Collaboration graph
[legend]
List of all members.

Public Member Functions

DECLSPEC GuiElement (const SDL_Rect &r, GuiElement *p, const char *name)
DECLSPEC GuiElement (TiXmlElement *el, GuiElement *p)
virtual const char * getClassName ()
virtual bool isGuiElement () const
 
Returns:
always true

DECLSPEC void resizeTo (Uint32 w, Uint32 h)
DECLSPEC void resizeBy (Sint32 dw, Sint32 dh)
DECLSPEC void moveTo (Sint32 x, Sint32 y)
DECLSPEC void moveRelCenterTo (Sint32 x, Sint32 y)
DECLSPEC void moveBy (Sint32 x, Sint32 y)
DECLSPEC void getWndSize (Uint32 &w, Uint32 &h) const
DECLSPEC SDL_Rect getRelWindow () const
DECLSPEC void setRelWindow (const SDL_Rect &r)
DECLSPEC SDL_Rect getAbsWindow ()
DECLSPEC void setAbsWindow (const SDL_Rect &r)
DECLSPEC SDL_Rect getClientWindow () const
DECLSPEC SDL_Rect getDrawWindow ()
DECLSPEC void getRelCenterPoint (Sint32 &x, Sint32 &y)
DECLSPEC void getAbsCenterPoint (Sint32 &x, Sint32 &y)
DECLSPEC void getClientCenterPoint (Sint32 &x, Sint32 &y)
DECLSPEC SDL_Rect getClip ()
DECLSPEC GuiElement * getParent () const
DECLSPEC GuiElement * getToplevel ()
DECLSPEC void setVisible (bool b)
DECLSPEC bool isVisible () const
DECLSPEC void setEnabled (bool b)
DECLSPEC bool isEnabled () const
 
Returns:
false, if this or a parent is disabled; true, if enabled

DECLSPEC void setRedraw ()
bool getRedraw ()
 
Returns:
true, if the element will be redrawn in the next onFrame-event

virtual bool hasSurface () const

Static Public Member Functions

static GuiElement * create (TiXmlElement *el, GuiElement *parent=NULL)
static GuiElement * createWithoutChildren (TiXmlElement *el, GuiElement *parent=NULL)
 Behaves as create(), but does not create children elements.
static void newelement (void *presult, BasicObject *o, void *xmldata)
static void togglevisibility (void *sender, BasicObject *aim, void *)

Protected Member Functions

virtual DECLSPEC Uint32 onMouseOver ()
virtual DECLSPEC Uint32 onMouseOut ()
virtual Uint32 onMouseMove (Uint32 x, Uint32 y)
virtual Uint32 onResize ()
virtual DECLSPEC Uint32 onFrame (SdlSurface *dest)
virtual DECLSPEC void onInit ()
virtual DECLSPEC void onDestroy ()
virtual DECLSPEC Uint32 onThemeChanged (UiTheme *t)
virtual DECLSPEC void onEnabledChanged (bool enabled)
virtual void incRequireOnFrame ()
virtual void decRequireOnFrame ()
 Does the opposite of incRequireOnFrame().
void setDrawRectDirty ()

Friends

class GuiManager

Detailed Description

Base class for all graphical user interface objects.

All classes, derived from GuiElement, can be used to display 2D-graphics on the screen. Every graphical element, but one (the top level element), is placed on another one, called its "parent", whose "child" it is. If an element becomes invisible, all child elements (and their children, ...) are hidden, too. The same is with the enabled state. If an element is invisible, the onFrame-event is not called. If an element is disabled, the mouse-events are not called. Also an element cannot (or better should not) be drawn beyond the parent's borders. The method getClip() is used to arrange the rect, in which blitting... should be done.

When deriving a class from GuiElement and implementing an event (a on...() method), do not forget to call finally the GuiElement::on...() method. Otherwise some features will not be availible.
In order to be able to create elements from an XML-tree, it is required to have a class constructor with the params TiXmlElement* and GuiElement*. Furthermore it must be registered in GuiElement::create().

For some more information, have a look at UiObject.

See also:
GuiManager, UiObject, BasicObject

Constructor & Destructor Documentation

GuiElement::GuiElement ( const SDL_Rect &  r,
GuiElement *  p,
const char *  name 
)

Constructor. There must be UiManager initialized before creating a GuiElement!

Parameters:
r the rect of the element's appearance, relative to the parent's top-left position
p the parent element (a GuiElement cannot have a child derived from UiObject or BasicObject and not from GuiElement), if NULL, GuiManager::the is its parent.
name the element's name
See also:
UiObject()

GuiElement::GuiElement ( TiXmlElement *  el,
GuiElement *  p 
)

Constructor, used to create an element from XML data. There must be UiManager initialized before creating a GuiElement!

Parameters:
el the XML data, the attribute "Rect" is required, optional are "Visible" (bool) and "Enabled" (bool)
p the parent element, or NULL to take GuiManager::the as parent

Member Function Documentation

virtual const char* GuiElement::getClassName (  )  [inline, virtual]

This function should be overriden in every sub-class of BasicObject!

Returns:
the name of the class.

Reimplemented from UiObject.

Reimplemented in GuiBackground, GuiFrame, GuiBorder, GuiRadioContainer, GuiPictureBg, GuiFlowWindow, GuiPageControl, GuiCheck, GuiRadio, GuiNumScroller, GuiCursor, GuiDropDown, GuiDynamicButton, GuiClickableBtn, GuiCheckableBtn, GuiRadioBtn, GuiFileElement, GuiFlowMenu, GuiForm, GuiHint, GuiListBox, GuiMenuBar, GuiMenuItem, GuiMessageBox, GuiProgressBar, GuiRotator, GuiScroller, GuiScrollBg, GuiSurface, GuiText, GuiTextInput, GuiKeyControl, GuiFrameCounter, GuiTextField, and GuiUpDown.

void GuiElement::resizeTo ( Uint32  w,
Uint32  h 
)

Resizes the rect of appearance of the element. The top-left corner will not be changed, but the right and bottom borders. After changing the rect, the onResize() event is called.

Parameters:
w the new width
h the new height

void GuiElement::resizeBy ( Sint32  dw,
Sint32  dh 
)

Resizes the rect of appearance of the element. The top-left corner will not be changed, but the right and bottom borders. After changing the rect, the onResize() event is called.

Parameters:
dw the value to add to the width
dh the value to add to the height

void GuiElement::moveTo ( Sint32  x,
Sint32  y 
)

Moves the rect of appearance of the element. The width and height will not be affected, but the relative position. After changing the rect, the onResize() event is called.

Parameters:
x the new x coordinate of the rect's left border
y the new y coordinate of the rect's top border

void GuiElement::moveRelCenterTo ( Sint32  x,
Sint32  y 
)

Moves the rect of appearance of the element. The width and height will not be affected, but the relative position. After changing the rect, the onResize() event is called.

Parameters:
x the new x coordinate of the rect's center
y the new y coordinate of the rect's center

void GuiElement::moveBy ( Sint32  x,
Sint32  y 
)

Moves the rect of appearance of the element. The width and height will not be affected, but the relative position. After changing the rect, the onResize() event is called.

Parameters:
x the value to add to the relative x position
y the value to add to the relative y position

void GuiElement::getWndSize ( Uint32 &  w,
Uint32 &  h 
) const

Gets the size of the rect of apperance.

Parameters:
w the width will be stored there
h the height will be stored there

SDL_Rect GuiElement::getRelWindow (  )  const

Gets the relative (to the parent's top-left) rect of apperance.

Returns:
the window's relative rect

void GuiElement::setRelWindow ( const SDL_Rect &  r  ) 

Sets the relative (to the parent's top-left) rect of apperance.

Parameters:
r the window's relative rect

SDL_Rect GuiElement::getAbsWindow (  ) 

Gets the absolute rect of apperance (distance from the screen's top-left)

Returns:
the window's absolute rect

void GuiElement::setAbsWindow ( const SDL_Rect &  r  ) 

Sets the absolute rect of apperance (distance from the screen's top-left)

Parameters:
r the window's new, absolute rect

SDL_Rect GuiElement::getClientWindow (  )  const

Get the rect of apperance, relative to the window itself, so the x and y coordinates are zero. So the result contains the same information as getWndSize(w,h)

Returns:
the rect at position 0, 0

SDL_Rect GuiElement::getDrawWindow (  ) 

Get the rect of apperance on the surface on which to draw (not limited to the surface's borders).

Returns:
the rect relative to the surface on which to draw

void GuiElement::getRelCenterPoint ( Sint32 &  x,
Sint32 &  y 
)

Get the relative center of apperance.

Parameters:
x the x coordinate will be stored there
y the y coordinate will be stored there

void GuiElement::getAbsCenterPoint ( Sint32 &  x,
Sint32 &  y 
)

Get the absolute center of apperance.

Parameters:
x the x coordinate will be stored there
y the y coordinate will be stored there

void GuiElement::getClientCenterPoint ( Sint32 &  x,
Sint32 &  y 
)

Get the center of apperance, relative to the rect itself. The assigned values equal the half values of getWndSize(x,y).

Parameters:
x the x coordinate will be stored there
y the y coordinate will be stored there

SDL_Rect GuiElement::getClip (  ) 

Get the absolute, visible rect of appearance. You should not draw anything beyond its borders.

Returns:
the clip rect

GuiElement * GuiElement::getParent (  )  const

Returns:
the parent element, or NULL, if there is not parent

Reimplemented from BasicObject.

GuiElement * GuiElement::getToplevel (  ) 

Returns:
the top level element (the element, that has no parent)

void GuiElement::setVisible ( bool  b  ) 

Changes the visible-state. (All children will become invisible, if this element becomes invisible)

Parameters:
b true, to show it; false, to hide it

bool GuiElement::isVisible (  )  const

Returns:
the visible-state (true, if shown on parent, so if parent is invisible and so this is invisible, it is also true; false, if hidden on parent)

void GuiElement::setEnabled ( bool  b  ) 

Changes the enabled state. (All children will become disabled, if this element is disabled)

Parameters:
b true, to enable it; false to disable it

void GuiElement::setRedraw (  ) 

Sets the redraw-state, so that the element (and it's children) will be redrawn in the next frame.

virtual bool GuiElement::hasSurface (  )  const [inline, virtual]

Returns:
true, if the element has its own surface to draw on, so that children need not refresh, if this element has to draw itself to its parent

Reimplemented in GuiSurface.

GuiElement * GuiElement::create ( TiXmlElement *  el,
GuiElement *  parent = NULL 
) [static]

Creates a new GuiElement object (or from a derived class) with all information taken from the XML element. If the XML element has children, they are recursively created as well. The XML code looks like: 

    <TYPE name="name of the object" rect="X,Y,W,H" [ parent="parent name"] [...]>[...]</TYPE>
("TYPE" is the class name ie. "GuiElement", children can be put into the element, further arguments may be required - it depends on the class)
Parameters:
el the XML element with all necessary data
parent the parent object (only used, if not specified in the XML data)
Returns:
a pointer to the new element or, if the class is not availible, NULL

static void GuiElement::togglevisibility ( void *  sender,
BasicObject *  aim,
void *   
) [inline, static]

Toggles the element's visibility. Name of slot: "ToggleVisibility". Param is ignored.

Uint32 GuiElement::onMouseOver (  )  [protected, virtual]

This event is called, when the mouse cursor just moved into the object's rect.

Returns:
currently the result is not used; may be zero, if no error...

Reimplemented in GuiFrame, and GuiClickableBtn.

Uint32 GuiElement::onMouseOut (  )  [protected, virtual]

This event is called, when the mouse cursor just moved out of the object's rect.

Returns:
currently the result is not used; may be zero, if no error...

Reimplemented in GuiFrame, and GuiClickableBtn.

virtual Uint32 GuiElement::onMouseMove ( Uint32  x,
Uint32  y 
) [inline, protected, virtual]

This event is called, when the mouse cursor is moved over the object.

Parameters:
x the absolute x coordinate of the cursor (distance from left)
y the absolute y coordinate of the cursor (distance from top)
Returns:
currently the result is not used; may be zero, if no error...

Reimplemented in GuiCursor.

virtual Uint32 GuiElement::onResize (  )  [inline, protected, virtual]

This event is called, when the element changed its place or size.

Returns:
currently the result is not used; may be zero, if no error...

Reimplemented in GuiBorder, GuiPageControl, GuiCheck, GuiRadio, GuiNumScroller, GuiDropDown, GuiHint, GuiMessageBox, GuiProgressBar, GuiScroller, GuiScrollBg, GuiSurface, and GuiUpDown.

Uint32 GuiElement::onFrame ( SdlSurface *  dest  )  [protected, virtual]

This event is called, when a frame is drawn. If the object should be visible, is has to draw it's look to a valid surface. This method calls the children's function, if visible.

Returns:
zero, if no error occured; if not zero, drawing is stopped
Note:
if you derive the function, then call GuiElement::onFrame(SdlSurface*) after your class's drawing was done in the onFrame-event, otherwise you paint over the children elements

Reimplemented in GuiBackground, GuiBorder, GuiPictureBg, GuiFlowWindow, GuiDynamicButton, GuiProgressBar, GuiRotator, GuiSurface, GuiText, GuiTextInput, GuiKeyControl, and GuiFrameCounter.

void GuiElement::onInit (  )  [protected, virtual]

Initializes the object's variables by reading data from the XML element. If there were no XML data used for creation, nothing is done. This function calls onInit() of its children recursively (after it has inited itself). It is highly recommended to call BasicObject::onInit(), usually at the end of the onInit() method, when overwriting it in a derived class.

Reimplemented from BasicObject.

Reimplemented in GuiBackground, GuiFrame, GuiBorder, GuiRadioContainer, GuiPictureBg, GuiFlowWindow, GuiPageControl, GuiCheck, GuiRadio, GuiNumScroller, GuiCursor, GuiDropDown, GuiDynamicButton, GuiClickableBtn, GuiCheckableBtn, GuiRadioBtn, GuiFileElement, GuiFlowMenu, GuiFlowMenuItem, GuiForm, GuiHint, GuiListBox, GuiMessageBox, GuiProgressBar, GuiRotator, GuiScroller, GuiScrollBg, GuiSurface, GuiText, GuiTextInput, GuiKeyControl, GuiFrameCounter, GuiTextField, and GuiUpDown.

void GuiElement::onDestroy (  )  [protected, virtual]

May be called to reinitialise this object or stop an initialised module. Calls all children's onDestroy(). Most classes do not use this method. But sometimes it is useful to reset the functionality of an object.

Reimplemented from UiObject.

Uint32 GuiElement::onThemeChanged ( UiTheme *  t  )  [protected, virtual]

This event is called, when the theme changes. Perform here the changes of the object's look and feel.

Parameters:
t pointer to the new used theme
Returns:
currently the result is not used; may be zero, if no error...

Reimplemented from UiObject.

Reimplemented in GuiBackground, GuiBorder, GuiPictureBg, GuiFlowWindow, GuiPageControl, GuiDropDown, GuiDynamicButton, GuiClickableBtn, GuiCheckableBtn, GuiRadioBtn, GuiForm, GuiHint, GuiProgressBar, GuiScroller, GuiText, GuiTextInput, and GuiUpDown.

void GuiElement::onEnabledChanged ( bool  enabled  )  [protected, virtual]

Called, after the object became enabled or disabled. (Only when the result of isEnabled() changed.)

Parameters:
enabled is true if the object became enabled

Reimplemented in GuiClickableBtn.

virtual void GuiElement::incRequireOnFrame (  )  [inline, protected, virtual]

Increments the reference counters of parent GuiSurfaces, to disable their off-screen surface blitting. So the onFrame-Method will always be called when drawing a frame.

See also:
GuiSurface::incUnuseRef()

Reimplemented in GuiSurface.

void GuiElement::setDrawRectDirty (  )  [protected]

Sets the draw rect dirty, so that it is recalculated at the next call to getDrawRect(). This method is required by the GuiSurface class.

The documentation for this class was generated from the following files:
Generated on Wed May 9 17:36:16 2007 for netrinjo by  doxygen 1.5.1