Contents of the TFIELD.DOC file

A TField object provides a basic input line string editor. It handles keyboardinput and mouse clicks and drags for block marking and a variety of line editingfunctions (see TField handleEvent). The selected text is deleted and thenreplaced by the first text input.

Optional scrolling is provided if maxLen is greater than the x dimension(size.x). If scrollable is True then horizontal scrolling is supported andindicated by left and right arrows. While the scrollable variable can bedirectly manipulated, the function setScroll has been provided. setScrollhandles the task of automatically calling drawView when the scroll statechanges. If the programmer wants to change the scroll state directly, TField'sdrawView function should be called after doing so.

Text justification is supported via the justification variable. justificationcan currently be either jLeft (default) or jRight. If jRight justification isselected, any data-entry occurs from right to left (calculator style.) setJustification handles the task of automatically calling drawView when thejustification value changes. If the programmer wants to change thejustification value directly, TField's drawView function should be called afterdoing so.

The getData and setData member functions are available for writing and readingdata strings (referenced via the data string data member) into the given record.TField::setState simplifies the redrawing of the view with appropriate colorswhen the state changes from or to sfActive and sfSelected.

TField can be extended to handle data types other than strings. To do so, you'llgenerally add additional data members and then override the constructors and thestore, valid, dataSize, getData, and setData member functions. For example, todefine a numeric input line, you might want it to contain minimum and maximumallowable values which will be tested by the valid function. These minimum andmaximum data members would be loaded (with the load constructor) and stored onthe stream. valid would be modified to make sure the value was numeric andwithin range. dataSize would be modified to include the size of the new rangedata members (probably sizeof(long) for each). Oddly enough, in this example itwould not be necessary to add a data member to store the numeric value itself. It could be stored as a string value (which is already managed by TField) andconverted from string to numeric value and back by getData and setData,respectively.

Data members

curPos int curPos;

Index to insertion point (that is, to the current cursor position).

See also: TField::selectAll

data char *data;

The string containing the edited information.

firstPos int firstPos;

Index to the first displayed character.

See also: TField::selectAll

justification int justification;

Holds the desired justification value for the field. Current options are jLeft or jRight. Default is jRight.

See also: TField::setJustification

maxLen int maxLen;

Maximum length allowed for string to grow (excluding the final 0).

See also: TField::dataSize

scrollState Boolean scrollState;

Flag to indicate whether scrolling is enabled or disabled. Default is True (enabled).

See also: TField::setScroll

selEnd int selEnd;

Index to the end of the selection area (that is, to the last character block marked).

See also: TField::selectAll

selStart int selStart;

Index to the beginning of the selection area (that is, to the first character block marked).

See also: TField::selectAll

Member functions

constructor TField(const TRect& bounds, int aMaxLen);

Creates an input box control with the given values by calling TView(bounds). state is then set to sfCursorVis, options is set to (ofSelectable | ofFirstClick), and maxLen is set to aMaxLen. Memory is allocated and cleared for aMaxlen + 1 bytes and the data data member set to point at this allocation. justification is initialized to jLeft and scrollable is initialized to True.

constructor TField( StreamableInit streamableInit); protected

Each streamable class needs a "builder" to allocate the correct memory for its objects together with the initialized vtable pointers. This is achieved by calling this constructor with an argument of type StreamableInit. Refer also to Chapter 8.

See also: TView::TView, sfCursorVis, ofSelectable, ofFirstClick

destructor ~TField();

Deletes the data memory allocation, then calls ~TView to destroy the TField object.

See also: ~TView

build static TStreamable *build();

Called to create an object in certain stream-reading situations.

See also: TStreamableClass, ipstream::readData

dataSize virtual ushort dataSize ();

Returns the size of the record for TField::getData and TField:: setData calls. By default, it returns maxLen + 1. Override this member function if you define descendants to handle other data types.

See also: TField::getData, TField::setData

draw virtual void draw();

Draws the input box and its data. The box is drawn with the appropriate colors depending on whether the box is sfFocused (that is, whether the box view owns the cursor), and arrows are drawn if the input string exceeds the size of the view (in either or both directions). Any selected (blockmarked) characters are drawn with the appropriate palette.

getData vlrtual void getData (void *rec);

Writes the number of bytes (obtained from a call to dataSize) from the data string to the array given by rec. Used with setData for a variety of applications; for example, temporary storage, or passing on the input string to other views. Override getData if you define TField descendants to handle non-string data types. You can also use getData to convert from a string to other data types after editing by TField.

See also: TField::dataSize, TField::setData

getPalette vlrtual TPalette& getPalette() const;

Returns the default palette string, cplnputLine, "\x13\x13\x14\x15".

handleEvent void handleEvent(TEvent& event);

Calls TView::handleEvent, then handles all mouse and keyboard events if the input box is selected. This member function implements the standard editing capability of the input box.

Editing features include: block marking with mouse click and drag; block deletion; insert or overwrite control with automatic cursor shape change; automatic and manual scrolling as required (depending on relative sizes of the data string and size.x); manual horizontal scrolling via mouse clicks on the arrow icons; manual cursor movement by arrow, Home, and End keys (and their standard control-key equivalents); character and block deletion with Del and Ctrl-G. The view is redrawn as required and the TField data members are adjusted appropriately.

See also: sfCursorlns, TView::handleEvent, TField::selectAll

read virtual void *read( ipstream& is);

Reads from the input stream is.

See also: TStreamableClass, TStreamable, ipstream

selectAll void selectAll (Boolean enable);

Sets curPos, firstPos, and selStart to 0. If enable is set to True, selEnd is set to the length of the data string, thereby selecting the whole input line; if enable is set to False, selEnd is set to 0, thereby deselecting the whole line. Finally, the view is redrawn by calling drawView.

See also: TView::drawView

setData virtual void setData (void *rec);

By default, copies the number of bytes (as returned by dataSize) from the rec array to the data string, and then calls selectAll(True). This zeros curPos, firstPos, and selStart. Finally, drawView is called to redraw the input box.

Override setData if you define descendants to handle non-string data types. You also use setData to convert other data types to a string for editing by TField.

See also: TField::dataSize, TField::getData, TField::selectAll

setJustification virtual void setJustification ( int jValue );

Called to change the justification value. Currently checks if jValue == jRight, if so it sets jValue to jRight and calls drawView, otherwise it sets jValue to jLeft and calls drawView.

See also: jRight, jLeft, TField::justification

setScroll virtual void setScroll (Boolean enable);

Called to enable/disable scrolling. Sets scrollState to enable then calls drawView.

See also: TField::scrollState

setState virtual void setState (ushort aState, Boolean enable);

Called when the input box needs redrawing (for example, if the palette is changed) following a change of state. Calls TView::setState to set or clear the view's state with the given aState bit(s). Then if aState is sfSelected (or sfActive and the input box is sfSelected), selectAll(enable) is called (which, in turn, calls drawView).

See also: TView::setState, TField::selectAll

write virtual void write( opstream& os);

Writes to the output stream os.

See also: TStreamableClass, TStreamable, opstream

Related functions Certain operator functions are related to TField but are notmember functions; see page 232 for more information.

PaletteTFields use the default palette, cpField, to map onto the 19th through 21stentries in the standard dialog palette.