Methods Index

CButton

Heritage

Superclass: CSubview

Subclasses: CMenuButton

Description

CButton objects are CSubviews that have push or toggle button behavior. These objects have the same look-and-feel on all platforms. Unlike native buttons (NButtons), CButton objects have the ability to send notification (via the DoCommand mechanism) both when the cursor enters or leaves the CButton and when a mouse button is pressed down or released over the CButton.

A togglable CButton has the following three states: TS_UP, TS_DOWN, and TS_UNKNOWN. If the button is clicked while in the TS_UNKNOWN state, it shifts to the TS_DOWN state.

Although CButtons are typically used for displaying a portable image inside a button, they may enclosure any CView-derived object. Note, however, that CNativeView-derived classes do not behave properly inside a CButton because the native view still receives events.

Usage

The CButton class provides two convenience constructors for common usage. The class provides one constructor for creating a CButton that contains text (CStringRW) and one for creating a CButton that contains a portable image (CImage).

You can also instantiate CButtons as a CSubview to which you can add other CView-derived objects.

All CButton constructors have an isTogglable argument, which indicates whether the button acts like a push button or a toggle button.

CButton objects do not react to a change in their CEnvironment. The colors used to render the button may be specified in the IButton initializer method. However, CSubviews that are enclosed by a CButton react to a change in their CEnvironment.

Enums

ToggleState

TS_UP Toggle button is in up state TS_DOWN Toggle button is in down state TS_UNKNOWN Toggle button is in unknown state (neither up nor down)


`TS_UP`	Toggle button is in up state
`TS_DOWN`	Toggle button is in down state
`TS_UNKNOWN`	Toggle button is in unknown state (neither up nor down)

Protected Data Members

BOOLEAN itIsIn; Indicates if cursor is in button
BOOLEAN itIsDown; Indicates if button is pressed down
COLOR itsDarkBorder; Color used to draw dark border
COLOR itsLightShadowColor; Color used to draw light border
COLOR itsDarkShadowColor; Color used to draw shadow border
COLOR itsFlatColor; Color used to draw flat background
CPoint itsSubviewOrigin; Origin of its subviews
long itsDownCommand; Command sent when button is pressed down
long itsInCommand; Command sent when cursor enters button
long itsOutCommand; Command sent when cursor leaves button
BOOLEAN itDrawsBackground; Indicates if button draws its background
BOOLEAN itIsDrawingBorder; Indicates if button needs to draw border
BOOLEAN itIsTogglable; Indicates if button has toggle behavior
ToggleState itsToggleState; Indicates toggle state of togglable button data needed to change MouseMouse/Up/Down/Double into DoIn/Out/Up/Down
CView* itsPreviousSelectedView; Resets selected view after clicking is finished
static BOOLEAN isMouseDown; Indicates if mouse button is down
static BOOLEAN isInButton; Indicates if mouse is in a CButton; provided for easier subclassing of CButton
static int itsBorderPixels; Number of pixels needed for border
static int itsTopLeftBorderPixels; Pixels needed for upper-left border


`BOOLEAN itIsIn;`	Indicates if cursor is in button
`BOOLEAN itIsDown;`	Indicates if button is pressed down
`COLOR itsDarkBorder;`	Color used to draw dark border
`COLOR itsLightShadowColor;`	Color used to draw light border
`COLOR itsDarkShadowColor;`	Color used to draw shadow border
`COLOR itsFlatColor;`	Color used to draw flat background
`CPoint itsSubviewOrigin;`	Origin of its subviews
`long itsDownCommand;`	Command sent when button is pressed down
`long itsInCommand;`	Command sent when cursor enters button
`long itsOutCommand;`	Command sent when cursor leaves button
`BOOLEAN itDrawsBackground;`	Indicates if button draws its background
`BOOLEAN itIsDrawingBorder;`	Indicates if button needs to draw border
`BOOLEAN itIsTogglable;`	Indicates if button has toggle behavior
`ToggleState itsToggleState;`	Indicates toggle state of togglable button data needed to change `MouseMouse/Up/Down/Double` into `DoIn/Out/Up/Down`
`CView* itsPreviousSelectedView;`	Resets selected view after clicking is finished
`static BOOLEAN isMouseDown;`	Indicates if mouse button is down
`static BOOLEAN isInButton;`	Indicates if mouse is in a `CButton`; provided for easier subclassing of `CButton`
`static int itsBorderPixels;`	Number of pixels needed for border
`static int itsTopLeftBorderPixels;`	Pixels needed for upper-left border

Public Methods

Constructor, Destructor, and Initializer Methods

CButton(CSubview *theEnclosure, 
	const CRect &theSize,
	BOOLEAN isTogglable = FALSE);

A constructor that creates a CButton of size theSize with enclosure theEnclosure. The isTogglable argument indicates whether the CButton acts like a push button or a toggle button. By default, CButtons are push buttons.

This constructor is generally followed by creation of other CView objects that have the CButton as their enclosure. You should however use this constructor only when constructing a CButton that contains views other then CText or CPicture objects. XVT provides convenience constructors for these common construction cases.

CButton(CSubview *theEnclosure,
	const CPoint &theTopLeft,	// autosized to theText
	const CStringRW &theText
	BOOLEAN isTogglable = FALSE);

The convenience constructor for creating a CButton object that contains text. This constructor creates a CText object, places it in the new CButton, and sizes the CButton to the text.

CButton(CSubview *theEnclosure,
	const CPoint &theTopLeft, 	// autosized to theImage
	const CImage &theImage,
	BOOLEAN isTogglable = FALSE);

The convenience constructor for creating a CButton object that contains a portable image. This constructor creates a CPicture object, places it in the new CButton, and sizes the CButton to the image.

CButton(const CButton &theButton);

A copy constructor that makes a shallow copy of theButton's attributes. Note that a button's colors and commands are copied, but they are not contained subviews. Attributes copied from the inherited CSubview copy constructor are also copied.

CButton & operator = (const CButton &theButton);

An assignment operator that copies the attributes of one button to another. Button colors and commands are copied, but they are not contained subviews. Attributes copied by the inherited CSubview assignment operator are also copied.

virtual ~CButton();

The CButton destructor. Deletes button and all nested subviews.

void IButton(COLOR theDarkBorder		= COLOR_BLACK,
	COLOR theLightShadowColor		= COLOR_WHITE,
	COLOR theDarkShadowColor		= COLOR_GRAY,
	COLOR theFlatColor			= COLOR_LTGRAY);

Initializer for CButton class. This method is used to set the colors with which CButton are rendered.

Methods Overridden from CSubview

The CButton class overrides the MouseUp, MouseDown, MouseMove, and MouseDouble methods from CSubview and translates them into "events" that are meaningful to a button. Specifically, this class translates these methods into DoIn, DoOut, DoUp, and DoDown events.

The following is the possible sequence of synthesized events:

When cursor enters a button, a DoIn event is sent
If the mouse button was pressed down in another button and dragged into this button, the DoIn event is followed by a DoDown event
If the mouse button is pressed down while the cursor is in the button, a DoDown event is sent
If the mouse button is released while the cursor is in the button, a DoUp event is sent
If the cursor leaves the button, a DoOut event is sent

The following are the possible sequences of synthesized DoIn, DoOut events for a CButton:

The cursor moves into and out of a CButton object with the mouse button up
The mouse button is pressed down outside of all of the CButtons, and then the cursor is dragged into and out of button
The mouse button is pressed down outside of all of the CButtons, and then the cursor is dragged into a button, the mouse button is released, and the cursor is moved out of the button

The following are the possible sequences of synthesized DoIn, DoDown, DoOut events for a CButton:

The cursor moves into a button with the mouse button up, the mouse button is pressed in the button area, and the cursor is dragged out of button without releasing mouse button
The mouse button is pressed down in any CButton object, the cursor is dragged into the button, and then it is dragged out of the button, without releasing mouse button

The following are the possible sequences of synthesized DoIn, DoDown, DoUp, DoOut events for a CButton:

The cursor moves into a button with the mouse button up, then the mouse button is pressed and released in the button, and the cursor is moved out of button
The mouse button is pressed down in any CButton, then the cursor is dragged into the button, the mouse button is then release in the button, and cursor is moved out of the button
Note: A CButton always receives a DoIn before a DoOut, DoUp, or DoDown event.

virtual void MouseUp(CPoint  theLocation,
	short theButton	= 0,
	BOOLEAN isShiftKey	= FALSE,
	BOOLEAN isControlKey	= FALSE);

Translates a MouseUp event into a DoUp event.

virtual void MouseDown(CPoint  theLocation,
	short theButton	= 0,
	BOOLEAN isShiftKey	= FALSE,
	BOOLEAN isControlKey	= FALSE);

Translates a MouseDown event into a DoDown event (and possibly a DoIn event).

virtual void MouseMove(CPoint  theLocation,
	short theButton	= 0,
	BOOLEAN isShiftKey	= FALSE,
	BOOLEAN isControlKey	= FALSE);

Translates a MouseMove event into DoIn (and possibly DoDown) and DoOut events.

virtual void MouseDouble(CPoint  theLocation,
	short theButton	= 0,
	BOOLEAN isShiftKey	= FALSE,
	BOOLEAN isControlKey	= FALSE);

Treats a MouseDouble event as a MouseDown event, which is how CButton objects respond to MouseDouble events.

Methods for Handling Synthesized In/Out/Up/Down Events

virtual BOOLEAN IsInButton(CPoint theLocation);

Returns TRUE if theLocation is in the CButton.

virtual void DoIn(void);

Handles pointer moving into the button.

virtual void DoOut(void);

Handles pointer moving out of the button.

virtual void DoUp(void);

Handles mouse button pressing down in the button.

virtual void DoDown(void);

Handles mouse button being released in the button. This method is called only if a DoUp event has been received for the button.

Overridden Methods

virtual void DoDraw(
	const CRect &theClippingRegion = MAXRect);

Implements the clipping of the CButton's contents to inside the button border.

virtual void Draw(const CRect &theClippingRegion);

Handles the drawing of the button in its correct state.

virtual void AddSubview(const CView* theSubview);

Overridden to offset theSubview by the width of the button border. If necessary, this method also sets itDrawsBackground to TRUE.

virtual void Size(const CRect& theNewSize);

Overridden to set itDrawsBackground to TRUE if it is needed.

virtual void Key(const CKey& theKey);

Sends a keyboard event to the button if it has focus. This method allows you to set a keyboard accelerator (e.g., the Space or Return keys), which will cause a behavior as if the button was clicked with the mouse. thekey represents the character key that was pressed, including the Shift and Control key states, when the key was pressed.

virtual void SetTitle(const CStringRW& the NewTitle);

Gives the button the title designated by theNewTitle.

virtual BOOLEAN ClassCanGetKeyFocus(void) const;

Overrides CView::ClassCanGetKeyFocus to return TRUE.

virtual CView * FindEventTarget(
	const CPoint &theLoc) const;

Overridden to send all events to the CButton; subviews enclosed by a CButton do not receive events.

virtual CView * FindDeepSubview(const CPoint &theLoc) const;

Overridden to send all events to the CButton; subviews enclosed by a CButton do not receive events.

Note: On some platforms, you cannot stop enclosed native views from receiving events, and the native views consume events before XVT-Power++ receives them. Therefore, you should not place native views inside of CButton objects.

Methods Specific to Togglable CButtons

virtual void SetTogglable(BOOLEAN isTogglable);

Makes a CButton object togglable according to the isTogglable parameter.

virtual BOOLEAN IsTogglable(void) const;

Returns TRUE if button is togglable, and FALSE otherwise.

virtual ToggleState GetToggleState(void) const;

Returns the toggle state of a togglable CButton. The possible returned states are as follows:

CButton::TS_UP
CButton::TS_DOWN
CButton::TS_UNKNOWN

This method is not meaningful for non-togglable CButtons.

virtual void SetToggleState(ToggleState theState);

Sets the state of a togglable CButton to theState parameter.The possible states are as follows:

CButton::TS_UP CButton::TS_DOWN CButton::TS_UNKNOWN

This method has no effect on non-togglable CButtons.

virtual void SetEnabled(BOOLEAN isEnabled, 
	BOOLEAN isUpdated);

Changes enabled state of the button to isEnabled if needed, and invalidates the button if isUpdated is TRUE.

Sizing Method

virtual void SizeToFit(void);

Modifies the size (but not the position) of a CButton so that it is the minimum size that includes all of its subviews. This method also moves the CButton subviews up and left in the CButton, as far as possible, while maintaining their relationship to each other.

Methods for Accessing Commands

void SetCommands(long theUpCommand		= NULLcmd,
	long theDownCommand			= NULLcmd,
	long theInCommand			= NULLcmd,
	long theOutCommand			= NULLcmd);

Sets the commands for Up, Down, In, and Out events.

void SetDownCommand(long theCommand);

Sets the command sent when a CButton receives a DoDown event.

long GetDownCommand(void) const;

Returns the command sent when a CButton receives a DoDown event.

void SetUpCommand(long theCommand);

Sets the command sent when a CButton receives a DoUp event.

long GetUpCommand(void) const;

Returns the command sent when a CButton receives a DoUp event.

void SetInCommand(long theCommand);

Sets the command sent when a CButton receives a DoIn event.

long GetInCommand(void) const;

Returns the command sent when a CButton receives a DoIn event.

void SetOutCommand(long theCommand);

Sets the command sent when a CButton receives a DoOut event.

long GetOutCommand(void) const;

Returns the command sent when a CButton receives a DoOut event.

Methods for Retrieving the Border Size of a Button

virtual int GetBorderPixels(void) const;

Returns the number of pixels needed for the drawing of the CButton border.

virtual int GetTopLeftBorderPixels(void) const;

Returns the number of pixels needed for this button's border drawing on the top and left.

TDI Enabling Methods

virtual void DoCommand(long theCommand, 
	void* theData = NULL);

Overrides CView::DoCommand to provide handling for TDI commands.

virtual void DoUpdateModel(long theControllerId, 
	long theCommand, const CModel* theModel);

Overrides CView::DoUpdateModel to provide handling of TDI messages.

Protected Methods

void CopyInternals(const CButton &theButton);

An internal method used by copy constructor and assignment operator.

void SubviewsDoSetOrigin(int theHOffset, int theVOffset);

When the button is pressed, this method implements shifting the button's contents by offsetting the origin of all subviews in pixels.

virtual BOOLEAN NeedsDoOut(void);

Provided to allow disabling of DoOut events by subclasses.

virtual vo id InternalDoDraw(
	const CRect &theClippingRegion = MAXRect);

Calls the DoDraw method, but this method does not draw the button's border.

Methods to Facilitate Creating CButton Subclasses

XVT provides the following protected methods to facilitate the subclassing of CButton. To provide a new button class with a different button border look, simply override the methods described below as needed.

virtual void IndicateIn(void);

Performs drawing to indicate that the mouse cursor is in the button. Default behavior for CButton is not to provide any visual feedback.

virtual void DrawBorder(void);

Performs drawing of the border of a CButton. By default, this border is a black rectangle with grey corners.

virtual void DrawDisabled(void);

Draws the button in with a disabled look. This method is called after all other drawing methods. In a CButton, this method "grays-out" the entire button.

virtual void DrawUp(void);

Draws the button in an up state. When a button is in up state, this method is called by the Draw method

virtual void DrawDown(void);

Draws the button in a down state. When a button is in a down state, this method is called by the Draw method

virtual void DrawPressed(void);

Draws the button in a pressed state. When a togglable button is in pressed state, this method is called by Draw method

CButton

virtual void DrawUnknown(void);

Draws the button in as neither up nor down. When a togglable button is in an unknown state, this method is called by the Draw method

virtual void DoUpAction(void);

Performs the desired action when a DoUp event is sent. By default, this method calls the DoCommand method

itsCommand

NULLcmd

virtual void DoDownAction(void);

Performs the desired action when a DoDown event is sent. By default, this method calls the DoCommand method

itsDownCommand

NULLcmd

virtual void DoInAction(void);

Performs the desired action when a DoIn event is sent. By default, this method calls the DoCommand method

itsInCommand

NULLcmd

virtual void DoOutAction(void);

Performs the desired action when a DoOut event is sent. By default, this method calls the DoCommand method

itsOutCommand

NULLcmd

virtual void InternalUp(void);

Performs the shifting of the button's subviews up and left on a DoUp event. This method also toggles the state for togglable buttons.

virtual void InternalDown(void);

Performs the shifting of the button's subviews down and right on a DoDown event.

[Classes] [Prev] [Next] [Methods]

support@xvt.com