VCF::Control

VCF::Control Class Reference

The base class for all visual components in the Visual Component Framework. More...

#include <vcf/ApplicationKit/Control.h>

Inheritance diagram for VCF::Control:


Public Types
enum	{ ANCHOR_DTOP = 0, ANCHOR_DLEFT, ANCHOR_DBOTTOM, ANCHOR_DRIGHT }
enum	ControlState { csVisible = 0x00000001, csEnabled = 0x00000002, csUseParentFont = 0x00000004, csDoubleBuffered = 0x00000008, csAutoStartDragDrop = 0x00000010, csTabStop = 0x00000020, csIgnoreForLayout = 0x00000040, csIgnoreForParentScrolling = 0x00000080, csAllowPaintNotification = 0x00000100, csHasMouseCapture = 0x00000200, csUseRenderBuffer = 0x00000400, csAllowMouseFocus = 0x00000800, csAllowFocus = 0x00001000, csDefaultControlState = csEnabled \| csTabStop \| csDoubleBuffered \| csAllowMouseFocus \| csAllowFocus }
enum	MinMaxSizeDefaults { mmIgnoreMinWidth = -1, mmIgnoreMinHeight = -1, mmIgnoreMaxWidth = -1, mmIgnoreMaxHeight = -1 }
enum	ControlEvents { CONTROL_EVENTS = COMPONENT_EVENTS_LAST + 200, CONTROL_SIZED, CONTROL_POSITIONED, CONTROL_PARENT_CHANGED, CONTROL_MODELCHANGED, FOCUS_GAINED, FOCUS_LOST, HELP_REQUESTED, WHATS_THIS_HELP_REQUESTED, KEYBOARD_DOWN, KEYBOARD_PRESSED, KEYBOARD_UP, KEYBOARD_ACCELERATOR, MOUSE_DOWN, MOUSE_MOVE, MOUSE_UP, MOUSE_CLICK, MOUSE_DBLCLICK, MOUSE_ENTERED, MOUSE_LEAVE, BEFORE_CONTROL_PAINTED, AFTER_CONTROL_PAINTED, BEFORE_POPUP_MENU, CONTROL_EVENTS_LAST }
Public Member Functions
	Control ()
virtual	~Control ()
virtual void	handleEvent (Event *event)
	This gets called by the ControlPeer for any windowing system mouse events, as well as for any windowing system keyboard events and for any windowing system events like size changes, position changes, etc.
void	handleEventAndForwardToChildren (Event *event)
	calls handleEvent on this control, and then calls handleEventToChildren() on any child controls the container of this control may have.
Border *	getBorder ()
	Returns the control's current border object, if any.
void	setBorder (Border *border)
	`Sets` the border for this control.
virtual Rect	getBounds ()
	returns the bounds in parent coordinates of the Control.
virtual Rect	getClientBounds (const bool &includeBorder=true)
	Returns the bounds in terms of the control's coordinates.
virtual double	getLeft ()
	Returns the left position in parent coordinates.
virtual double	getRight ()
	Returns the right position in parent coordinates.
virtual double	getWidth ()
	returns the width of the control
virtual double	getTop ()
	returns the top position in parent coordinates
virtual double	getBottom ()
	returns the bottom position in parent coordinates
virtual double	getHeight ()
	returns the height of the control
virtual bool	getVisible ()
	is this control visible to the user.
AlignmentType	getAlignment ()
	`Returns` the control's alignment.
bool	isIgnoredForLayout ()
	`Returns` whether this control must be ignored in the control container's layout implementation.
void	setIgnoredForLayout (const bool &val)
void	setBounds (const double &x, const double &y, const double &width, const double &height)
	sets the bounds of the control.
virtual void	setBounds (Rect *rect, const bool &anchorDeltasNeedUpdating=true)
	sets the bounds of the control.
void	setAlignment (const AlignmentType &alignment)
	sets the alignment of the control
virtual void	setLeft (const double &left)
	sets the left value for the control, immediately updates the controls position.
virtual void	setRight (const double &right)
	sets the right value of the control.
virtual void	setWidth (const double &width)
	sets the width of the control.
virtual void	setTop (const double &top)
	sets the top value of the control.
virtual void	setBottom (const double &bottom)
	sets the bottom value of the control.
virtual void	setHeight (const double &height)
	sets the height of the control.
virtual void	setVisible (const bool &visible)
	determines whether or not the control is visible, and set it visible if it wasn't.
virtual bool	canBeginDragDrop (Point *point)
	if autoStartDragDrop_ is true then this method checks to see if the Controls dragging is with the windowing system's tolernace for a drag drop operation to start.
void	setAutoStartDragDrop (const bool &canAutoStartDragDrop)
	sets auto start dragging to true or false
bool	getAutoStartDragDrop ()
	returns whether or not auto dragging is on or off.
virtual bool	beginDragDrop (MouseEvent *event)
	Override this to provide functionality for handling the start of drag-drop operation This will get called automatically by the framework if it detects that a mouse-move has occured that indicates a drag-drop operation COULD occur.
virtual ControlPeer *	getPeer ()
	returns the control's native peer interface
virtual void	setParent (Control *parent)
	sets the parent for the control
virtual Control *	getParent ()
	returns the control's current parent
void	removeFromParent (const bool &freeInstance=true)
	throw( InvalidPeer ); -JEC - FIXME later
bool	isFocused ()
	does this control currently have focus?
Control *	setFocused ()
	Makes this control the currently focused control.
bool	getAllowsFocus ()
void	setAllowsFocus (const bool &val)
bool	getAllowsMouseFocus ()
void	setAllowsMouseFocus (const bool &val)
bool	isEnabled ()
	returns whether the control is enabled or not.
bool	areParentsEnabled ()
	This checks not only to see if the control itself is enabled, but will return false if any parent control is not enabled.
void	setEnabled (const bool &enabled)
	sets whether the control is enabled or not.
virtual void	paint (GraphicsContext *context)=0
	Paints the control.
void	paintBorder (GraphicsContext *context)
	Paints the border for the control.
virtual void	mouseEnter (MouseEvent *event)
	Called when the mouse first enters the control's bounds.
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	mouseClick (MouseEvent *event)
	Called when one or mouse buttons are held down and immediately released ( a "mouse click" ).
virtual void	mouseDblClick (MouseEvent *event)
	Called when one or mouse buttons are held down and immediately released ( a "mouse double click" ) twice, within some specific time period, as determined on the windowing system.
virtual void	mouseLeave (MouseEvent *event)
	Called when the mouse leaves the control's bounds.
virtual void	keyDown (KeyboardEvent *event)
	called when the user presses the key down
virtual void	keyPressed (KeyboardEvent *event)
	called when the user simply presses the key and represents a full key cycle having occurred, in other words the key has been pressed down and then released
virtual void	keyUp (KeyboardEvent *event)
	called when the user releases the key
virtual void	sizeChange (ControlEvent *event)
	called when the control's bounds change.
virtual void	positionChange (ControlEvent *event)
	called when the control's coordinates change.
virtual void	parentChange (ControlEvent *event)
	Called when the parent of the control is changed.
virtual void	gotFocus (FocusEvent *event)
	Called when the control gains keyboard focus.
virtual void	lostFocus (FocusEvent *event)
	Called when the control loses keyboard focus.
void	translateToParent (Point *point)
	translate the point from this controls coordinate system to the parent controls coordinate system
void	translateToLocal (Point *point)
	translate the point from parent controls coordinate system to this controls coordinate system
void	translateToScreenCoords (Point *pt)
	Takes the coordinates in pt, which are in the coordinate system of this control, and translates them into the coordinate system of the Screen.
void	translateToScreenCoords (Rect *rect)
	Takes the coordinates in rect, which are in the coordinate system of this control, and translates them into the coordinate system of the Screen.
void	translateFromScreenCoords (Point *pt)
	Takes the coordinates in pt, which are in the coordinate system of the Screen, and translates them into the coordinate system of this control.
void	translateFromScreenCoords (Rect *rect)
	Takes the coordinates in rect, which are in the coordinate system of the Screen, and translates them into the coordinate system of this control.
virtual bool	isLightWeight ()
	identifies the control as a lightweight control.
virtual Control *	getHeavyweightParent ()
	Returns the first parent of the Control that is a heavweight Control, i.e it's isLighweight() method return false.
Color *	getColor ()
	returns the color used to fill the background of this control
void	setColor (Color *color)
	sets the color to fill this control's background with
virtual void	beforeDestroy (ComponentEvent *event)
	called just prior to completely destroying the control and it's associated memory.
virtual void	afterCreate (ComponentEvent *event)
	Special initializations may then happen here.
Font *	getFont ()
	Returns the font associated with this control.
void	setFont (Font *font)
	sets the font attributes.
bool	useParentFont ()
	returns whether this control will use the font settings of the parent's font.
void	setUseParentFont (const bool &useParentFont)
	sets whether the control should use it's parent font's settigns or use it's own independent of it's parent's font.
void	repaint (Rect *repaintRect=NULL)
	repaint the control.
void	repaintNow (Rect *repaintRect=NULL)
bool	isDoubleBuffered ()
	is this component double buffered.
void	setDoubleBuffered (const bool &doubleBuffered)
	sets whether or not this control is double buffered.
bool	isUsingRenderBuffer ()
	Returns true if the Control should take advantage of the GraphicsContexts' render buffer for anti-aliased vector graphics (based on the AGG library).
void	setUsingRenderBuffer (const bool &useRenderBuffer)
	sets whether or not the control is using the render buffer of it's GraphicsContext.
void	keepMouseEvents ()
	this keeps the mouse events being sent to this control, even if the mouse leaves the physical bounds of the control
void	releaseMouseEvents ()
	releases mouse events - goes back to normal event handling
GraphicsContext *	getContext ()
	return a pointer to the graphics context of the control.
PopupMenu *	getPopupMenu ()
	returns the Control's PopupMenu, if any.
void	setPopupMenu (PopupMenu *popupMenu)
	sets the popup menu for this control.
View *	getView ()
	returns the view associated with this control
void	setView (View *view)
	sets the view to associate with this control
virtual double	getPreferredWidth ()
	returns the preferred width for this control.
virtual double	getPreferredHeight ()
	returns the preferred height for this control.
virtual void	setPreferredWidth (const double &width)
	set the preferred width.
virtual void	setPreferredHeight (const double &height)
	set the preferred height.
Size	getMinSize ()
	Returns the minimum size for this control.
void	setMinSize (const Size &val)
	Sets the minimum size of the control.
double	getMinWidth ()
	Returns the minimum width of the control.
void	setMinWidth (const double &val)
	Sets the minimum width of the control.
double	getMinHeight ()
	Returns the minimum height of the control.
void	setMinHeight (const double &val)
	Sets the minimum height of the control.
Size	getMaxSize ()
	Returns the maximum size for this control.
void	setMaxSize (const Size &val)
	Sets the maximum size of the control.
double	getMaxWidth ()
void	setMaxWidth (const double &val)
double	getMaxHeight ()
void	setMaxHeight (const double &val)
Scrollable *	getScrollable ()
	returns an object implementing the Scrollable interface The default value is NULL, indicating the control does not support scrolling behaviour
virtual void	setScrollable (Scrollable *scrollable)
	sets the scrollable for the control.
void	adjustViewableBoundsAndOriginForScrollable (GraphicsContext *context, Rect &viewBounds, Point &origin)
	Call this method to adjust the view bounds (i.e.
String	getWhatThisHelpString ()
	returns a string that is used for context sensitive help for the control.
void	setWhatThisHelpString (const String &whatThisHelpString)
	sets the string that is used for context sensitive help for the control.
String	getToolTipText ()
	returns a string that is used to display in the tooltip for the control.
void	setToolTipText (const String &tooltip)
	sets the string that is used to display in the tooltip for the control.
int32	getCursorID ()
	returns the cursor ID for the control.
void	setCursorID (const int32 &cursorID)
	sets the cursor ID for the control.
AnchorTypes	getAnchor ()
	returns the anchor mask value for this control.
void	setAnchor (const AnchorTypes &anchor)
	sets the anchor mask value for the control.
float *	getAnchorDeltas ()
	returns the current delta for each of the anchors.
virtual bool	keepReturnCharacter ()
	this function determines if the control keeps the key event when the return key is pressed, or if it will relinquish the event for the system to process.
virtual bool	keepsTabKey ()
	This function determines whether or not the control should have precedence and prevent the the tab key from switching focus to another control.
virtual bool	keepsArrowKeys ()
	This function determines whether or not the control should have precedence and prevent the the arrow keys from switching focus to another control.
bool	getTabStop ()
	Indicates whether the control responds to the TAB key to set it's focus when tabbing from control to control.
void	setTabStop (const bool &tabStop)
	sets the tab stop value of the control.
int32	getTabOrder ()
	Returns the tab order of the control.
void	setTabOrder (const int32 &tabOrder)
AcceleratorKey *	getAccelerator (const VirtualKeyCode &keyCode, const uint32 &modifierMask)
	Returns the AcceleratorKey instance that is associated with this control and the specified key code and modifier mask.
void	addAcceleratorKey (const VirtualKeyCode &keyCode, const uint32 &modifierMask, EventHandler *eventHandler)
	Associates a new AcceleratorKey with the Control.
void	addAcceleratorKey (const VirtualKeyCode &keyCode, const uint32 &modifierMask, Action *action)
	Associates a new AcceleratorKey with the Control.
void	addAcceleratorKey (AcceleratorKey *accelerator)
	This should generally not be called.
virtual void	mnemonicActivate ()
	Pressing the accelerator character will cause the control's mnemonicActivate() method to be fired, which by default sets focus to the control.
Frame *	getParentFrame ()
	This returns a pointer to the top level frame that this control is associated with.
bool	isActive ()
	This returns a value that indicates whether or not hte control is considered to be active.
bool	canAcceptFocus ()
	Can the control accept focus? This method determines if the control can recieve focus.
Container *	getContainer ()
	returns the current container for this control.
void	setContainer (Container *container)
	sets the current container for a control.
bool	hasChildren ()
	This returns whether or not the control has any child controls associated with it.
bool	isChild ()
	Returns whether or not this control is a child of some other control.
bool	getAllowPaintNotification ()
	Returns whether or not the control will allow paint notification.
void	setAllowPaintNotification (const bool &val)
	Sets whether or not the control will allow paint notification.
bool	ignoreForParentScrolling ()
void	setIgnoreForParentScrolling (const bool &val)
void	preChildPaint (GraphicsContext graphicsContext, Control child, Rect *childClipRect)
	Called by the container instance of the child's parent control during it's paintChildren() function.
void	postChildPaint (GraphicsContext graphicsContext, Control child, Rect *oldClipRect)
	Called by the container instance of the child's parent control during it's paintChildren() function.
virtual void	setViewModel (Model *viewModel)
	sets a new model for the view Once set, the control fires a ControlModelChanged event.
void	internal_beforePaint (GraphicsContext *context)
	called by the internals of the framework - DO NOT CALL!
void	internal_afterPaint (GraphicsContext *context)
	called by the internals of the framework - DO NOT CALL!
Static Public Member Functions
static Control *	getCapturedMouseControl ()
	returns the current control that has captured the mouse input.
static void	setCapturedMouseControl (Control *control)
	sets the control that has captured the mouse.
static Control *	getCurrentFocusedControl ()
	returns the currently focused control.
static Control *	getPreviousMouseOverControl ()
	returns the control the mouse was previously over, if any.
static void	setPreviousMouseOverControl (Control *control)
static void	buildTabList (Control control, std::vector< Control > &tabList)
Public Attributes
VCF::Delegate	ControlSized
VCF::Delegate	ControlPositioned
VCF::Delegate	ControlParentChanged
VCF::Delegate	MouseDoubleClicked
VCF::Delegate	MouseClicked
VCF::Delegate	MouseMove
VCF::Delegate	MouseUp
VCF::Delegate	MouseDown
VCF::Delegate	MouseEnter
VCF::Delegate	MouseLeave
VCF::Delegate	KeyPressed
VCF::Delegate	KeyDown
VCF::Delegate	KeyUp
VCF::Delegate	ControlHelpRequested
VCF::Delegate	HelpRequested
VCF::Delegate	FocusGained
VCF::Delegate	FocusLost
VCF::Delegate	ToolTipRequested
VCF::Delegate	ToolTip
VCF::Delegate	ControlModelChanged
VCF::Delegate	BeforeControlPainted
VCF::Delegate	AfterControlPainted
VCF::Delegate	BeforePopupMenu
Protected Member Functions
void	updateAnchorDeltas ()
virtual void	destroy ()
	called by the free() method.
Protected Attributes
ControlPeer *	peer_
ControlGraphicsContext *	context_
Control *	parent_
AlignmentType	aligment_
uint32	anchor_
Rect *	bounds_
Rect *	clientBounds_
Border *	border_
Color *	color_
Font *	font_
View *	view_
PopupMenu *	popupMenu_
Scrollable *	scrollable_
String	whatThisHelpString_
String	toolTip_
int32	cursorID_
Cursor *	cursor_
float	anchorDeltas_ [4]
int32	tabOrder_
Point	clickPt_
Container *	container_
Size	minSize_
Size	maxSize_
uint32	controlState_
Static Protected Attributes
static Control *	currentFocusedControl
static Control *	previousMouseOverControl
static Control *	capturedMouseControl

Detailed Description

The base class for all visual components in the Visual Component Framework.

In addition it implements the View interface. This means that the Control is itself a specialized form of a View, though it may not have have a model, and can hold an external view, separate from itself.

A control receives a wide variety of events from the user such as paint events, mouse events, keyboard events, help events, etc.

Controls can have parents, and can form a hierarchy of parent-child controls. Controls can have children if they have a valid Container instance set.

Controls can also be aligned or anchored, which can aid in laying out the presentation of a UI.

Finally a Control may also be lightweight or heavyweight, which determines how many window system resources the control consumes. A heavyweight control has a native window/widget and takes up resources accordingly. In addition a heavyweight control also has a native graphics context associated with it that also takes up resources. In contrast, a lightweight control shares the underlying native window and graphics context resources with it's parent, and greatly reduces the number of resources the application will consume. This is especially useful when making complex custom controls that have many moving parts like a tree-list control, complete with a header and movable icons, etc.

To aid in the drawing of a control, all controls are double buffered by default to prevent flicker, though this can be turned off and on at will.

Event Delegates for this class:

Member Enumeration Documentation

anonymous enum

Enumerator:

ANCHOR_DTOP

ANCHOR_DLEFT

ANCHOR_DBOTTOM

ANCHOR_DRIGHT

enum VCF::Control::ControlEvents

Enumerator:

CONTROL_EVENTS

CONTROL_SIZED

CONTROL_POSITIONED

CONTROL_PARENT_CHANGED

CONTROL_MODELCHANGED

FOCUS_GAINED

FOCUS_LOST

HELP_REQUESTED

WHATS_THIS_HELP_REQUESTED

KEYBOARD_DOWN

KEYBOARD_PRESSED

KEYBOARD_UP

KEYBOARD_ACCELERATOR

MOUSE_DOWN

MOUSE_MOVE

MOUSE_UP

MOUSE_CLICK

MOUSE_DBLCLICK

MOUSE_ENTERED

MOUSE_LEAVE

BEFORE_CONTROL_PAINTED

AFTER_CONTROL_PAINTED

BEFORE_POPUP_MENU

CONTROL_EVENTS_LAST

enum VCF::Control::ControlState

Enumerator:

csVisible

csEnabled

csUseParentFont

csDoubleBuffered

csAutoStartDragDrop

csTabStop

csIgnoreForLayout

csIgnoreForParentScrolling

csAllowPaintNotification

csHasMouseCapture

csUseRenderBuffer

csAllowMouseFocus

csAllowFocus

csDefaultControlState

enum VCF::Control::MinMaxSizeDefaults

Enumerator:

mmIgnoreMinWidth

mmIgnoreMinHeight

mmIgnoreMaxWidth

mmIgnoreMaxHeight

Constructor & Destructor Documentation

VCF::Control::Control ( )

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

Member Function Documentation

void VCF::Control::addAcceleratorKey ( AcceleratorKey * accelerator )

This should generally not be called.
It's for framework usage only at this point.

void VCF::Control::addAcceleratorKey ( const VirtualKeyCode & keyCode,

const uint32 & modifierMask,

Action * action

)

Associates a new AcceleratorKey with the Control.
The key code, modifier mask and the action's accelerator event handler all become the attributes of the new AcceleratorKey instance.

void VCF::Control::addAcceleratorKey ( const VirtualKeyCode & keyCode,

const uint32 & modifierMask,

EventHandler * eventHandler

)

Associates a new AcceleratorKey with the Control.
The key code, modifier mask and event handler all become the attributes of the new AcceleratorKey

void VCF::Control::adjustViewableBoundsAndOriginForScrollable ( GraphicsContext * context,

Rect & viewBounds,

Point & origin

)

Call this method to adjust the view bounds (i.e.
what the GraphicsContext::getViewableBounds() method returns) to take into consideration the presence of scroll bars

virtual void VCF::Control::afterCreate ( ComponentEvent * event ) [virtual]

Special initializations may then happen here.

See also:
Component::afterCreate()

Reimplemented from VCF::Component.
Reimplemented in VCF::Frame, VCF::HTMLBrowserControl, and VCF::OpenGLControl.

bool VCF::Control::areParentsEnabled ( )

VCF::Control Class Reference

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation