---

TButton Class Reference

The button view. More...

#include <dialogs.h>

Inheritance diagram for TButton::

List of all members.

Public Methods
	TButton (const TRect &bounds, const char *aTitle, ushort aCommand, ushort aFlags)
	~TButton ()
virtual void	draw ()
void	drawState (Boolean down)
virtual TPalette&	getPalette () const
virtual void	handleEvent (TEvent &event)
void	makeDefault (Boolean enable)
virtual void	press ()
virtual void	setState (ushort aState, Boolean enable)
Static Public Methods
TStreamable*	build ()
Public Attributes
const char*	title
Static Public Attributes
const char*	shadows
const char* const	name
Protected Methods
	TButton (StreamableInit)
virtual void	write (opstream &os)
virtual void*	read (ipstream &is)
Protected Attributes
ushort	command
uchar	flags
Boolean	amDefault

---

Detailed Description

One of the most used and easy to use views. A TButton object is a box with a title and a shadow that generates a command when pressed. A button can be selected by:

1. typing the highlighted letter
2. tabbing to the button and pressing Spacebar
3. pressing Enter when the button is the default
4. clicking on the button with a mouse

With color and black-and-white palettes, a button has a three-dimensional look that moves when selected. On monochrome systems, a button is bordered by brackets, and other ASCII characters are used to indicate whether the button is default, selected, and so on.

There can only be one default button in a window or dialog at any given time. Buttons that are peers in a group grab and release the default state via evBroadcast messages.

Definition at line 536 of file dialogs.h.

---

Constructor & Destructor Documentation

TButton::TButton ( const TRect & bounds, const char * aTitle, ushort aCommand, ushort aFlags )

Constructor. Creates a TButton class with the given size by calling the TView constructor. `bounds' is the bounding rectangle of the button `aTitle' is a pointer to a string which will be the title of the button `aCommand' is the command generated when the user presses the button. If the given `aCommand' is not enabled, sfDisabled is set in the state data member. `aFlags' is a combination of the following values: Constant Value Meaning bfNormal 0x00 Button is a normal, non-default button bfDefault 0x01 Button is the default button: if this bit is set this button will be highlighted as the default button bfLeftJust 0x02 Button label is left-justified; if this bit is clear the title will be centered bfBroadcast 0x04 Sends a broadcast message when pressed bfGrabFocus 0x08 The button grabs the focus when pressed It is the responsibility of the programmer to ensure that there is only one default button in a TGroup. However the default property can be passed to normal buttons by calling makeDefault(). See also: TButton::amDefault The bfLeftJust value can be added to bfNormal or bfDefault and affects the position of the text displayed within the button: if clear, the label is centered; if set, the label is left-justified. The options data member is set to (ofSelectable | ofFirstClick | ofPreProcess | ofPostProcess) so that by default TButton responds to these events. eventMask is set to evBroadcast.

TButton::~TButton ( )

Destructor. Frees the memory assigned to the button's title, then destroys the view with TView::~TView. See also: TView::~TView

TButton::TButton ( StreamableInit ) [inline, protected]

Constructor. Used to recover the view from a stream. Each streamable class needs a "builder" to allocate the correct memory for its objects together with the initialized virtual table pointers. This is achieved by calling this constructor with an argument of type StreamableInit. Definition at line 731 of file dialogs.h.

---

Member Function Documentation

TStreamable * TButton::build ( ) [static]

Creates a new TButton. Used to recover the view from a stream. Called to create an object in certain stream-reading situations. Reimplemented from TView.

void TButton::draw ( ) [virtual]

Draws the button by calling TButton::drawState(False). See also: TButton::drawState Reimplemented from TView.

void TButton::drawState ( Boolean down )

Called by draw(). Draws the button in the "down" state (no shadow) if down is True; otherwise, it draws the button in the "up" state if down is False. The appropriate palettes are used to reflect the current state (normal, default, disabled). The button label is positioned according to the bfLeftJust bit in the flags data member.

TPalette & TButton::getPalette ( ) const [virtual]

Returns a reference to the standard TButton palette string. Reimplemented from TView.

void TButton::handleEvent ( TEvent & event ) [virtual]

Handles TButton events. Responds to being pressed in any of three ways: mouse clicks on the button, its hot key being pressed, or being the default button when a cmDefault broadcast arrives. When the button is pressed, a command event is generated with putEvent(), with the command data member assigned to command and infoPtr set to this. Buttons also recognize the broadcast commands cmGrabDefault and cmReleaseDefault, to become or "unbecome" the default button, as appropriate, and cmCommandSetChanged, which causes them to check whether their commands have been enabled or disabled. Reimplemented from TView.

void TButton::makeDefault ( Boolean enable )

Changes the default property of this button. Used to make this button the default with `enable' set to True, or to release the default with `enable' set to False. Three notes: If `enable' is True, the button grabs the default property from the default button (if exists) with a cmGrabDefault broadcast command, so the default button losts the default property. If `enable' is False, the button releases the default property to the default button (if exists) with a cmReleaseDefault broadcast command, so the default button gains the default property. These changes are usually the result of tabbing within a dialog box. The status is changed without actually operating the button. The default button can be subsequently "pressed" by using the Enter key. This mechanism allows a normal button (without the bfDefault bit set) to behave like a default button. The button is redrawn if necessary to show the new status. This method does nothing if the button is a default button (i.e. it has the bfDefault bit set). See also: TButton::flags

void TButton::press ( ) [virtual]

This method is called whenever the button is pressed. Its task is to send a message. The message is a broadcast message to the owner of the view if the button has the bfBroadcast bit set, otherwise the message is a command message. See also: TButton::flags Used internally by handleEvent() when a mouse click "press" is detected or when the default button is "pressed" with the Enter key.

void * TButton::read ( ipstream & is ) [protected, virtual]

Used to recover the view from a stream. Reads from the input stream `is'. Reimplemented from TView.

void TButton::setState ( ushort aState, Boolean enable ) [virtual]

Changes the state of the button. Calls setState(), then calls drawView() to redraw the button if it has been made sfSelected or sfActive. See also: TView::state If focus is received (that is, if `aState' is sfFocused), the button grabs or releases default from the default button by calling makeDefault(). Reimplemented from TView.

void TButton::write ( opstream & os ) [protected, virtual]

Used to store the view in a stream. Writes to the output stream `os'. Reimplemented from TView.

---

Member Data Documentation

Boolean TButton::amDefault [protected]

If True the button has the default property. The default button is automatically selected when the user presses the Enter key. If this variable is False, the button is a normal button. Definition at line 712 of file dialogs.h.

ushort TButton::command [protected]

This is the command word of the event generated when this button is pressed. Definition at line 697 of file dialogs.h.

uchar TButton::flags [protected]

This variabile is a bitmapped data member used to indicate whether button text is left-justified or centered. The individual flags are the various bfXXXX constants. See also: TButton::TButton Definition at line 705 of file dialogs.h.

const char *const TButton::name [static]

Undocumented. Reimplemented from TView. Definition at line 748 of file dialogs.h.

const char * TButton::shadows [static]

A pointer to the shadow characters. These characters are used to draw the button shadow. Definition at line 691 of file dialogs.h.

const char * TButton::title

This is a pointer to the label text of the button. Definition at line 685 of file dialogs.h.

---

The documentation for this class was generated from the following file:

• dialogs.h

---