---

TCluster Class Reference

The base class of TCheckBoxes and TRadioButtons. More...

#include <dialogs.h>

Inheritance diagram for TCluster::

List of all members.

Public Methods
	TCluster (const TRect &bounds, TSItem *aStrings)
	~TCluster ()
virtual ushort	dataSize ()
void	drawBox (const char *icon, char marker)
void	drawMultiBox (const char *icon, const char *marker)
virtual void	getData (void *rec)
ushort	getHelpCtx ()
virtual TPalette&	getPalette () const
virtual void	handleEvent (TEvent &event)
virtual Boolean	mark (int item)
virtual uchar	multiMark (int item)
virtual void	press (int item)
virtual void	movedTo (int item)
virtual void	setData (void *rec)
virtual void	setState (ushort aState, Boolean enable)
virtual void	setButtonState (unsigned long aMask, Boolean enable)
Boolean	buttonState (int item)
Static Public Methods
TStreamable*	build ()
Static Public Attributes
const char* const	name
Protected Methods
	TCluster (StreamableInit)
virtual void	write (opstream &os)
virtual void*	read (ipstream &is)
Protected Attributes
unsigned long	value
unsigned long	enableMask
int	sel
TStringCollection*	strings

---

Detailed Description

The base class used both by TCheckBoxes and TRadioButtons.

A cluster is a group of controls that all respond in the same way. TCluster is an abstract class from which the useful group controls such as TRadioButtons, TCheckBoxes, and TMonoSelector are derived.

Cluster controls are often associated with TLabel objects, letting you select the control by selecting on the adjacent explanatory label. Clusters are used to toggle bit values in the value data member, which is of type unsigned long.

The two standard descendants of TCluster use different algorithms when changing value: TCheckBoxes simply toggles a bit, while TRadioButtons toggles the enabled one and clears the previously selected bit. Both inherit most of their behavior from TCluster.

Definition at line 856 of file dialogs.h.

---

Constructor & Destructor Documentation

TCluster::TCluster ( const TRect & bounds, TSItem * aStrings )

Constructor. Calls TView::TView(bounds) to create a TCluster object with the given `bounds', where `bounds' is the desired bounding rectangle of the view. The strings data member is set to `aStrings', a pointer to a linked list of TSItem objects, one for each cluster item. Every TSItem object stores the caption of the related item. See also: TView::TView TCluster handles a maximum of 32 items. The constructor clears the value and sel data members.

TCluster::~TCluster ( )

Deletes the cluster's string collection, then destroys the view with TView::~TView(). See also: TView::~TView

TCluster::TCluster ( StreamableInit ) [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.

---

Member Function Documentation

TStreamable * TCluster::build ( ) [static]

Creates a new TCluster view. Called to create an object in certain stream-reading situations. Reimplemented from TView. Reimplemented in TMonoSelector, TRadioButtons, TCheckBoxes, and TMultiCheckBoxes.

Boolean TCluster::buttonState ( int item )

Returns True if the specified item is enabled. Parameter `item' specifies which item to check. 0 is the first item, 1 is the second item, etc. See also: TCluster::enableMask

ushort TCluster::dataSize ( ) [virtual]

Returns the size of the data record of this view (composed by the value data member). Must be overridden in derived classes that change value or add other data members, in order to work with getData() and setData(). It returns `sizeof(short)' for compatibility with earlier TV, even if value data member is now an unsigned long; TMultiCheckBoxes returns sizeof(long). Reimplemented from TView. Reimplemented in TMultiCheckBoxes.

void TCluster::drawBox ( const char * icon, char marker )

Redraws the view. Called within the draw() method of derived classes to draw the box in front of the string for each item in the cluster. See also: TCheckBoxes::draw , TRadioButtons::draw , TView::draw Parameter `icon' is a five-character string that points to a string which will be written at the left side of every item (" [ ] " for check boxes, " () " for radio buttons). Parameter `marker' is the character to use to indicate the box has been marked ("X" for check boxes, "." for radio buttons). A space character will be used if the box is unmarked. See also: TCluster::drawMultiBox

void TCluster::drawMultiBox ( const char * icon, const char * marker )

Redraws the view. Called within the draw() method of derived classes. See also: TCheckBoxes::draw , TRadioButtons::draw , TView::draw Parameter `icon' points to a string which will be written at the left side of every item. For example TCheckBoxes::draw() calls this method with string " [ ] " as `icon' parameter. TRadioButton::draw() calls this method with string " ( ) " as parameter `icon'. Parameter `marker' is a pointer to an array of 2 characters. If the item is not checked the first character will be written. Otherwise the second character will be used. See also: TCluster::drawBox

void TCluster::getData ( void * rec ) [virtual]

Reads the data record of this view. Writes the value data member to the given `rec' address and calls drawView(). Must be overridden in derived classes that change the value data member in order to work with dataSize() and setData(). Reimplemented from TView. Reimplemented in TMultiCheckBoxes.

ushort TCluster::getHelpCtx ( ) [virtual]

Returns the help context of the selected item. The help context is calculated by summing view variable helpCtx and the number of the currently selected item (0 for the first item, 1 for the second item, etc). Redefines TView::getHelpCtx(). Enables you to have separate help contexts for each item in the cluster. Use it to reserve a range of help contexts equal to helpCtx plus the number of cluster items minus one. Reimplemented from TView.

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

Returns a reference to the standard TCluster palette. Reimplemented from TView.

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

Calls TView::handleEvent(), then handles all mouse and keyboard events appropriate to this cluster. Controls are selected by mouse click or cursor movement keys (including Spacebar). The cluster is redrawn to show the selected controls. Reimplemented from TView. Reimplemented in TMonoSelector.

Boolean TCluster::mark ( int item ) [virtual]

Called by the draw() method redefined both in TCheckBoxes and TRadioButtons classes to determine which items are marked. mark() should be overridden to return True if the item'th control in the cluster is marked; otherwise, it should return False. See also: TCheckBoxes::draw , TRadioButton::draw The default mark() returns False. Redefined in TCheckBoxes and in TRadioButtons. See also: TCheckBoxes::mark , TRadioButtons::mark Reimplemented in TMonoSelector, TRadioButtons, and TCheckBoxes.

void TCluster::movedTo ( int item ) [virtual]

Called by handleEvent() to move the selection bar to the item'th control of the cluster. This member function does nothing and must be overridden. Redefined in TRadioButtons. See also: TRadioButtons::movedTo Reimplemented in TMonoSelector, and TRadioButtons.

uchar TCluster::multiMark ( int item ) [virtual]

It just returns `(uchar)(mark(item) == True)'. Reimplemented in TMultiCheckBoxes.

void TCluster::press ( int item ) [virtual]

Called by handleEvent() when the item'th control in the cluster is pressed either by mouse click or keyboard event. This member function does nothing and must be overridden. Redefined in TCheckBoxes and in TRadioButtons. See also: TCheckBoxes::press , TRadioButtons::press Reimplemented in TMonoSelector, TRadioButtons, TCheckBoxes, and TMultiCheckBoxes.

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

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

void TCluster::setButtonState ( unsigned long aMask, Boolean enable ) [virtual]

Sets the state of one or more items. `aMask` is a bitmap which specifies what items to enable or disable. `enable' is the action to perform: False to disable, True to enable.

void TCluster::setData ( void * rec ) [virtual]

Writes the data record of this view. Reads the value data member from the given `rec' address and calls drawView(). Must be overridden in derived cluster types that require other data members to work with dataSize() and getData(). Reimplemented from TView. Reimplemented in TRadioButtons, and TMultiCheckBoxes.

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

Changes the state of the view. Calls TView::setState(aState), then calls drawView() if `aState' is sfSelected. See also: TView::setState , TView::state Reimplemented from TView.

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

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

---

Member Data Documentation

unsigned long TCluster::enableMask [protected]

This variable stores a bitmap which selectively enables cluster items. If bit 0 is set the first item is enabled, if bit 1 is set the second item is enabled, etc. If a bit is cleared the related item is disabled. Its initial value is 0xffffffff. Definition at line 1054 of file dialogs.h.

const char *const TCluster::name [static]

Undocumented. Reimplemented from TView. Reimplemented in TMonoSelector, TRadioButtons, TCheckBoxes, and TMultiCheckBoxes. Definition at line 1106 of file dialogs.h.

int TCluster::sel [protected]

This integer contains the current selected item. If its value is 0 the first item is selected, if its value is 1 the second item is selected, etc. Its initial value is 0. Definition at line 1061 of file dialogs.h.

TStringCollection * TCluster::strings [protected]

This object contains all the item captions. Definition at line 1065 of file dialogs.h.

unsigned long TCluster::value [protected]

This variable stores the item status bitmap (current value of the control). Its initial value is 0. The actual meaning of this data member is determined by the member functions developed in the classes derived from TCluster. For example, TCheckBoxes interprets each of the 32 bits of value as the state (on or off) of 32 distinct check boxes. If bit 0 is set the first box is checked, if bit 1 is set the second box is checked, etc. If a bit is cleared the related box is unchecked. In TRadioButtons, value can represent the state of a cluster of up to 2^32 buttons, since only one radio button can be "on" at any one time. Note: unsigned long is currently a 32-bit unsigned integer giving a range of 0 to 2^32-1. Definition at line 1046 of file dialogs.h.

---

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

• dialogs.h

---