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

CButton

Methods Index

Heritage
Description
Usage
Environment
Enums
Protected Data Members
Public Methods
Constructor, Destructor, and Initializer Methods
Methods Overridden from CSubview
Methods for Handling Synthesized In/Out/Up/Down Events
Overridden Methods
Methods Specific to Togglable CButtons
Sizing Method
Methods for Accessing Commands
Methods for Retrieving the Border Size of a Button
TDI Enabling Methods
Protected Methods
Methods to Facilitate Creating CButton Subclasses

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.

See Also: For an example of implementing status bar help for CButtons, see the Usage section of CMenuButton.


Environment

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)


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


Public Methods

Constructor, Destructor, and Initializer Methods

CButton(CSubview *theEnclosure, 
const CRect &theSize,
BOOLEAN isTogglable = FALSE);
CButton(CSubview *theEnclosure,
const CPoint &theTopLeft, // autosized to theText
const CStringRW &theText
BOOLEAN isTogglable = FALSE);
CButton(CSubview *theEnclosure,
const CPoint &theTopLeft, // autosized to theImage
const CImage &theImage,
BOOLEAN isTogglable = FALSE);
CButton(const CButton &theButton);
CButton & operator = (const CButton &theButton);
virtual ~CButton();
void IButton(COLOR theDarkBorder		= COLOR_BLACK,
COLOR theLightShadowColor = COLOR_WHITE,
COLOR theDarkShadowColor = COLOR_GRAY,
COLOR theFlatColor = COLOR_LTGRAY);

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:

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

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

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

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);
virtual void MouseMove(CPoint  theLocation,
short theButton = 0,
BOOLEAN isShiftKey = FALSE,
BOOLEAN isControlKey = FALSE);
virtual void MouseDouble(CPoint  theLocation,
short theButton = 0,
BOOLEAN isShiftKey = FALSE,
BOOLEAN isControlKey = FALSE);

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

virtual BOOLEAN IsInButton(CPoint theLocation);
virtual void DoIn(void);
virtual void DoOut(void);
virtual void DoUp(void);
virtual void DoDown(void);

Overridden Methods

virtual void DoDraw(
const CRect &theClippingRegion = MAXRect);
virtual void Draw(const CRect &theClippingRegion);
virtual void AddSubview(const CView* theSubview);
virtual void Size(const CRect& theNewSize);
virtual void Key(const CKey& theKey);
virtual void SetTitle(const CStringRW& the NewTitle);
virtual BOOLEAN ClassCanGetKeyFocus(void) const;
virtual CView * FindEventTarget(
const CPoint &theLoc) const;
virtual CView * FindDeepSubview(const CPoint &theLoc) const;

Methods Specific to Togglable CButtons

virtual void SetTogglable(BOOLEAN isTogglable);
virtual BOOLEAN IsTogglable(void) const;
virtual ToggleState GetToggleState(void) const;
virtual void SetToggleState(ToggleState theState);
virtual void SetEnabled(BOOLEAN isEnabled, 
BOOLEAN isUpdated);

Sizing Method

virtual void SizeToFit(void);

Methods for Accessing Commands

void SetCommands(long theUpCommand		= NULLcmd,
long theDownCommand = NULLcmd,
long theInCommand = NULLcmd,
long theOutCommand = NULLcmd);
void SetDownCommand(long theCommand);
long GetDownCommand(void) const;
void SetUpCommand(long theCommand);
long GetUpCommand(void) const;
void SetInCommand(long theCommand);
long GetInCommand(void) const;
void SetOutCommand(long theCommand);
long GetOutCommand(void) const;

Methods for Retrieving the Border Size of a Button

virtual int GetBorderPixels(void) const;
virtual int GetTopLeftBorderPixels(void) const;

TDI Enabling Methods

virtual void DoCommand(long theCommand, 
void* theData = NULL);
virtual void DoUpdateModel(long theControllerId, 
long theCommand, const CModel* theModel);

Protected Methods

void CopyInternals(const CButton &theButton);
void SubviewsDoSetOrigin(int theHOffset, int theVOffset); 
virtual BOOLEAN NeedsDoOut(void);
virtual vo id InternalDoDraw(
const CRect &theClippingRegion = MAXRect);

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);
virtual void DrawBorder(void);
virtual void DrawDisabled(void);
virtual void DrawUp(void);
virtual void DrawDown(void);
virtual void DrawPressed(void);
virtual void DrawUnknown(void);
virtual void DoUpAction(void);
virtual void DoDownAction(void);
virtual void DoInAction(void);
virtual void DoOutAction(void);
virtual void InternalUp(void);
virtual void InternalDown(void);


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

support@xvt.com


Visit our online help desk for tech support

Copyright © 2009, Providence Software Solutions Inc. All rights reserved.