VCF::PushButton Class Reference

#include <vcf/ApplicationKit/PushButton.h>

Inheritance diagram for VCF::PushButton:


Public Types
enum	CaptionAlignment { bcaCenter = 0, bcaRight, bcaTop, bcaLeft, bcaBottom }
enum	ImageState { bisNone = 0x0, bisNormal = 0x1, bisUp = bisNormal, bisDown = 0x2, bisDisable = 0x4, bisFocus = 0x8, bisFocusDown = 0x10, bisHighlight = 0x20, bisAll = bisUp\|bisDown\|bisDisable\|bisFocus\|bisFocusDown\|bisHighlight }
	helps the user to know which image index is used by the button to paint its different states. More...
Public Member Functions
	PushButton ()
virtual	~PushButton ()
virtual void	setName (const String &name)
	sets the name of the component.
virtual void	addButtonClickHandler (EventHandler *handler)
	This macro creates a method for adding a listener to the CommandButton's events.
virtual void	removeButtonClickHandler (EventHandler *handler)
	This macro creates a method for removing a listener to the CommandButton's events.
virtual void	paint (GraphicsContext *context)
	Paints the control.
virtual void	click ()
	This represents the user pressing the button, which then invokes whatever command is associated with the button.
virtual void	setDefault (const bool &defaultButton)
	sets this button as the default button.
virtual bool	isDefault ()
virtual void	setCaption (const String &caption)
virtual String	getCaption ()
virtual double	getPreferredHeight ()
	returns the preferred height for this control.
virtual double	getPreferredWidth ()
	returns the preferred width for this control.
virtual void	mouseDown (MouseEvent *event)
	Called when one (or more) of the mouse buttons are held down.
virtual void	mouseMove (MouseEvent *event)
	Called when the mouse moves over the control.
virtual void	mouseUp (MouseEvent *event)
	Called when one (or more) of the mouse buttons are released.
virtual void	mouseEnter (MouseEvent *event)
	Called when the mouse first enters the control's bounds.
virtual void	mouseLeave (MouseEvent *event)
	Called when the mouse leaves the control's bounds.
virtual void	mouseClick (MouseEvent *event)
	Called when one or mouse buttons are held down and immediately released ( a "mouse click" ).
virtual void	keyDown (KeyboardEvent *event)
	called when the user presses the key down
virtual void	keyUp (KeyboardEvent *event)
	called when the user releases the key
bool	getShowCaption ()
void	setShowCaption (const bool &showCaption)
bool	getAutoSize ()
	The button resize itself automatically to adjust itself to the caption's size.
void	setAutoSize (const bool &autoSize)
Size	calcMinimumSize ()
	gets the calculated size of the button.
ImageList *	getImageList ()
	gets the ImageList instance used to display an image in the button.
void	setImageList (ImageList *imageList)
	sets the ImageList instance used to display an image in the button.
int32	getBtnImageIndex (const ImageState &imgState)
	Tells which image index is used for an image inside the ImageList, in order to display the specified ImageState ( i.e.
void	setBtnImageIndex (const int32 &btnImageIndex, ImageState imgStates=bisNormal, const bool &redraw=false)
	sets which image index is used for an image inside the ImageList, in order to display the specified ImageState(s)
void	setBtnImageIndex (ImageList *imageList, const int32 &btnImageIndex, const CaptionAlignment &captionAlignment=bcaRight, const double &separationImageCaption=5.0)
	helper to write less and more clear code.
CaptionAlignment	getCaptionAlignment ()
	Tells if the button's caption needs to be aligned on the left, right, top or bottom,or it should be centered.
void	setCaptionAlignment (const CaptionAlignment &captionAlignment)
double	getSeparationImageCaption ()
	tells the separation between image and caption when they are both displayed.
void	setSeparationImageCaption (const double &separationImageCaption)
bool	isToggled ()
	tells if the buttons has the behaviour of a toggled button.
void	setToggled (const bool &toggled)
bool	isPressed ()
	tells if the buttons is currently pressed.
void	setStatePressed (const bool &pressed)
	set the state as pressed for a toggled button.
bool	isHighlighted ()
	tells if the buttons is currently highlighted, i.e.
bool	getMoveImageWhenPressed ()
	let the user to specify if we want to move the image when pressing the button.
void	setMoveImageWhenPressed (const bool &moveImageWhenPressed)
bool	getDrawFocusRectWhenFocus ()
	let the user to specify if we want to draw the focus rect when the button has the focus.
void	setDrawFocusRectWhenFocus (const bool &drawFocusRectWhenFocus)
bool	getDrawFocusRectWhenFocusDown ()
	same as getDrawFocusRectWhenFocus, but when the button is pressed down.
void	setDrawFocusRectWhenFocusDown (const bool &drawFocusRectWhenFocusDown)
ButtonCommandType	getCommandType ()
	The command type the button represents.
void	setCommandType (const ButtonCommandType &commandType)
	sets the commad type
Public Attributes
VCF::Delegate	ButtonClicked
Protected Member Functions
void	onFocusGained (FocusEvent *event)
	event handler called when the button gets the focus
void	onFocusLost (FocusEvent *event)
	event handler called when the button looses the focus
virtual void	drawImage (const Rect &rect, const ButtonState &state, const Rect imageRect, GraphicsContext ctx)
virtual Rect	calcCenterRect (const Rect &rect, GraphicsContext context, Rect captionRect=NULL, Rect *imageRect=NULL)
	calculates the central rectangle including both the image and the caption ( if shown ).
virtual Rect	calcCaptionRect (const Rect &rect, GraphicsContext *context)
	calculates the Rect where the caption should be placed inside the button
virtual Rect	calcImageRect (const Rect &rect, GraphicsContext *context)
	calculates the Rect where the image should be placed inside the button
Protected Attributes
String	caption_
ButtonCommandType	commandType_
bool	showCaption_
bool	isHighlighted_
bool	isPressed_
bool	toggled_
bool	wasPressed_
bool	autoSize_
ImageList *	imageList_
double	separationImageCaption_
CaptionAlignment	captionAlignment_
std::map< int32, uint32 >	imageIndexes_
bool	moveImageWhenPressed_
bool	drawFocusRectWhenFocus_
bool	drawFocusRectWhenFocusDown_
int32	imageStateSpecified_

Detailed Description

Class PushButton documentation.

Member Enumeration Documentation

enum VCF::PushButton::CaptionAlignment

See also:
getCaptionAlignment

Enumerator:

bcaCenter

bcaRight

bcaTop

bcaLeft

bcaBottom

enum VCF::PushButton::ImageState

helps the user to know which image index is used by the button to paint its different states.
bisUp is used in the normal state. bisDown is used when the button is pressed. bisFocused is used when it has the focus. bisDisabled is used when the button is disabled. bisHover is used when the mouse in the normal state.
Enumerator:

bisNone

bisNormal

bisUp

bisDown

bisDisable

bisFocus

bisFocusDown

bisHighlight

bisAll

Constructor & Destructor Documentation

VCF::PushButton::PushButton ( )

virtual VCF::PushButton::~PushButton ( ) [virtual]

Member Function Documentation

virtual void VCF::PushButton::addButtonClickHandler ( EventHandler * handler ) [inline, virtual]

This macro creates a method for adding a listener to the CommandButton's events.

Implements VCF::Button.

virtual Rect VCF::PushButton::calcCaptionRect ( const Rect & rect,

GraphicsContext * context

) [protected, virtual]

calculates the Rect where the caption should be placed inside the button

virtual Rect VCF::PushButton::calcCenterRect ( const Rect & rect,

GraphicsContext * context,

Rect * captionRect = NULL,

Rect * imageRect = NULL

) [protected, virtual]

calculates the central rectangle including both the image and the caption ( if shown ).

Parameters:

const Rect& rect, the rectangle of the button. If the given rectangle is empy, then the function returns the minimum rectangle containing both image and caption.

virtual Rect VCF::PushButton::calcImageRect ( const Rect & rect,

GraphicsContext * context

) [protected, virtual]

calculates the Rect where the image should be placed inside the button

Size VCF::PushButton::calcMinimumSize ( )

gets the calculated size of the button.
This is the minimum size for the button to contain both caption and image ( if shown ), separated as requested by getSeparationImageCaption().

virtual void VCF::PushButton::click ( ) [virtual]

This represents the user pressing the button, which then invokes whatever command is associated with the button.
It should be called in the implementing controls class whenever the control is "clicked" on (see Control::mouseClick() ), it can also be called programmatically as well.
Implements VCF::Button.

virtual void VCF::PushButton::drawImage ( const Rect & rect,

const ButtonState & state,

const Rect * imageRect,

GraphicsContext * ctx

) [protected, virtual]

bool VCF::PushButton::getAutoSize ( ) [inline]

The button resize itself automatically to adjust itself to the caption's size.

int32 VCF::PushButton::getBtnImageIndex ( const ImageState & imgState )

Tells which image index is used for an image inside the ImageList, in order to display the specified ImageState ( i.e.
the state of the button displayed through a specified image ).
Parameters:

ImageState& imgState, tells which image state we are referring to. If the specified ImageState is a combination of more than one ImageState, or none of the values bisUp,bisDown,bisDisable,bisFocus,bisHighlight, or not a valid number, the return value is -1. If no images are used, then the return value is -1.

virtual String VCF::PushButton::getCaption ( ) [virtual]

CaptionAlignment VCF::PushButton::getCaptionAlignment ( ) [inline]

Tells if the button's caption needs to be aligned on the left, right, top or bottom,or it should be centered.

ButtonCommandType VCF::PushButton::getCommandType ( ) [inline]

The command type the button represents.
Certain command types will automatically send the event to the dialog they belong to when used on modal dialogs.

bool VCF::PushButton::getDrawFocusRectWhenFocus ( ) [inline]

let the user to specify if we want to draw the focus rect when the button has the focus.
The default is to always draw it. Use the value false if the focus is already drawn by the image. This flag is automatically set to false if a bisFocus state image is provided, but you can set it back to true, if you need, after the focus images are set.

bool VCF::PushButton::getDrawFocusRectWhenFocusDown ( ) [inline]

same as getDrawFocusRectWhenFocus, but when the button is pressed down.
This is important for toggled buttons, as the 'focus rect' may be good when the button is up, but not when it is down or viceversa. This flag is automatically set to true if a bisFocusDown state image is provided, but you can set it back to true, if you need, after the focus images are set.

ImageList* VCF::PushButton::getImageList ( ) [inline]

gets the ImageList instance used to display an image in the button.

bool VCF::PushButton::getMoveImageWhenPressed ( ) [inline]

let the user to specify if we want to move the image when pressing the button.
The default is to move it only if an image index has not been specified for the bisDown ImageState ( i.e. false if specified, and true if not ). In other words the user should paint the down state with in the bisDown image if he's using it.

virtual double VCF::PushButton::getPreferredHeight ( ) [virtual]

returns the preferred height for this control.
This is used when determing the height of the control when it is first created. Override it to provide a different value that is more acceptable for your control's initial display size.
Reimplemented from VCF::Control.

virtual double VCF::PushButton::getPreferredWidth ( ) [virtual]

returns the preferred width for this control.
This is used when determing the width of the control when it is first created. Override it to provide a different value that is more acceptable for your control's initial display size.
Reimplemented from VCF::Control.

double VCF::PushButton::getSeparationImageCaption ( ) [inline]

tells the separation between image and caption when they are both displayed.
Unless the function calcCaptionImageRect is overriden, the caption and the image are both displayed in a rectangle centered in the button.

bool VCF::PushButton::getShowCaption ( ) [inline]

virtual bool VCF::PushButton::isDefault ( ) [virtual]

Implements VCF::Button.

bool VCF::PushButton::isHighlighted ( ) [inline]

tells if the buttons is currently highlighted, i.e.
the mouse is over it.

bool VCF::PushButton::isPressed ( ) [inline]

tells if the buttons is currently pressed.
i.e. if it is in the down state. If the button isToggled, then it could be pressed even if we are not clicking on it.

bool VCF::PushButton::isToggled ( ) [inline]

tells if the buttons has the behaviour of a toggled button.
This means that it stays down if clicked until it is clicked again.

virtual void VCF::PushButton::keyDown ( KeyboardEvent * event ) [virtual]

called when the user presses the key down

Reimplemented from VCF::Control.

virtual void VCF::PushButton::keyUp ( KeyboardEvent * event ) [virtual]

called when the user releases the key

Reimplemented from VCF::Control.

virtual void VCF::PushButton::mouseClick ( MouseEvent * event ) [virtual]

Called when one or mouse buttons are held down and immediately released ( a "mouse click" ).
override this to provide specific behaviours when a mouse click occurs
Reimplemented from VCF::Control.

virtual void VCF::PushButton::mouseDown ( MouseEvent * event ) [virtual]

Called when one (or more) of the mouse buttons are held down.
override this to provide specific behaviours when the mouse buttons are held down
Reimplemented from VCF::Control.

virtual void VCF::PushButton::mouseEnter ( MouseEvent * event ) [virtual]

Called when the mouse first enters the control's bounds.
override this to provide specific behaviours when the control is first entered, like highlighting the control
Reimplemented from VCF::Control.

virtual void VCF::PushButton::mouseLeave ( MouseEvent * event ) [virtual]

Called when the mouse leaves the control's bounds.
override this to provide specific behaviours when the control is left, like highlighting the control
Reimplemented from VCF::Control.

virtual void VCF::PushButton::mouseMove ( MouseEvent * event ) [virtual]

Called when the mouse moves over the control.
override this to provide specific behaviours when the mouse moves over the control.
Reimplemented from VCF::Control.

virtual void VCF::PushButton::mouseUp ( MouseEvent * event ) [virtual]

Called when one (or more) of the mouse buttons are released.
override this to provide specific behaviours when the mouse buttons are released.
Reimplemented from VCF::Control.

void VCF::PushButton::onFocusGained ( FocusEvent * event ) [protected]

event handler called when the button gets the focus

void VCF::PushButton::onFocusLost ( FocusEvent * event ) [protected]

event handler called when the button looses the focus

virtual void VCF::PushButton::paint ( GraphicsContext * context ) [virtual]

Paints the control.
Called by the underlying windowing system whenever the control needs to be painted. Note that in some cases the GraphicsContext passed in to this method may not be the same pointer as the GraphicsContext that the control holds itself. During the paint() method you should only use the context value for all your drawing and not the one returned in getContext(). The value returned by getContext() should be used for drawing that takes place outside of the paint() method.
If the control allows paint notification, then the framework will fire an event to the BeforeControlPainted delegate prior to calling the control's paint() method. After the paint() method has returned, if the control allows paint notification, the framework will fire an event to the AfterControlPainted delegate. This allows outside observers to take part in the paint cycle, but beware that this does come at a bit of a cost, so use this feature sparingly.
Note: This should NEVER be called by programmers using the VCF, it will be called for you during the course of your applications native event loop, and is only here for providing custom drawing routines for controls. In other words: you implement it, you never call it yourself.
See also:
getAllowPaintNotification

Reimplemented from VCF::CustomControl.
Reimplemented in VCF::TabbedPages::ScrollButton.

virtual void VCF::PushButton::removeButtonClickHandler ( EventHandler * handler ) [inline, virtual]

This macro creates a method for removing a listener to the CommandButton's events.

Implements VCF::Button.

void VCF::PushButton::setAutoSize ( const bool & autoSize )

void VCF::PushButton::setBtnImageIndex ( ImageList * imageList,

const int32 & btnImageIndex,

const CaptionAlignment & captionAlignment = bcaRight,

const double & separationImageCaption = 5.0

)

helper to write less and more clear code.
For the button image is assumed the bisNormal ImageState.

void VCF::PushButton::setBtnImageIndex ( const int32 & btnImageIndex,

ImageState imgStates = bisNormal,

const bool & redraw = false

)

sets which image index is used for an image inside the ImageList, in order to display the specified ImageState(s)

Parameters:

const int32& btnImageIndex, the desired index in the ImageList

ImageState imgStates, tells which image states are going to be displayed with the given image index. The user can specify more than one image state at the same time for the given index. If this function is called only once for one ImageState only, then that index will be used for all image states.

const bool& redraw, repaint the button once changed the image. The default is true but the user may want this false in some cases.

virtual void VCF::PushButton::setCaption ( const String & caption ) [virtual]

void VCF::PushButton::setCaptionAlignment ( const CaptionAlignment & captionAlignment )

void VCF::PushButton::setCommandType ( const ButtonCommandType & commandType )

sets the commad type

virtual void VCF::PushButton::setDefault ( const bool & defaultButton ) [virtual]

sets this button as the default button.
A default button will have it's click() event called whenever the enter key is hit.
Implements VCF::Button.

void VCF::PushButton::setDrawFocusRectWhenFocus ( const bool & drawFocusRectWhenFocus ) [inline]

void VCF::PushButton::setDrawFocusRectWhenFocusDown ( const bool & drawFocusRectWhenFocusDown ) [inline]

void VCF::PushButton::setImageList ( ImageList * imageList )

sets the ImageList instance used to display an image in the button.

Parameters:

ImageList* imageList, the instance. To set this value to NULL is a simple way to disable the display of an image.

void VCF::PushButton::setMoveImageWhenPressed ( const bool & moveImageWhenPressed ) [inline]

virtual void VCF::PushButton::setName ( const String & name ) [virtual]

sets the name of the component.
For naming conventions/rules please see getName().
Reimplemented from VCF::Component.

void VCF::PushButton::setSeparationImageCaption ( const double & separationImageCaption ) [inline]

void VCF::PushButton::setShowCaption ( const bool & showCaption )

void VCF::PushButton::setStatePressed ( const bool & pressed )

set the state as pressed for a toggled button.
This function establish an association between a user's variable and the pressed/unpressed state of the button. For example, if the variable is onlyToday_, then toggleButton_->setInitialStatePressed( !onlyToday_ ) will state that the button will appear pressed when onlyToday_ is false. The management of the pressed/unpressed state should be done through the click() member function or through mouseClick() or keyUp() handlers, so it is suggested to use this function only to set the initial state.