TField TFIELD.H
--------------------------------------------------------------------------------
_________
| TView |
---------
I
____I_____
| TField |
----------

A TField object provides a basic input line string editor. It handles keyboard
input and mouse clicks and drags for block marking and a variety of line editing
functions (see TField handleEvent). The selected text is deleted and then
replaced 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 and
indicated by left and right arrows. While the scrollable variable can be
directly manipulated, the function setScroll has been provided. setScroll
handles the task of automatically calling drawView when the scroll state
changes. If the programmer wants to change the scroll state directly, TField's
drawView function should be called after doing so.

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

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

TField can be extended to handle data types other than strings. To do so, you'll
generally add additional data members and then override the constructors and the
store, valid, dataSize, getData, and setData member functions. For example, to
define a numeric input line, you might want it to contain minimum and maximum
allowable values which will be tested by the valid function. These minimum and
maximum data members would be loaded (with the load constructor) and stored on
the stream. valid would be modified to make sure the value was numeric and
within range. dataSize would be modified to include the size of the new range
data members (probably sizeof(long) for each). Oddly enough, in this example it
would 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) and
converted 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 not
member functions; see page 232 for more information.

Palette
TFields use the default palette, cpField, to map onto the 19th through 21st
entries in the standard dialog palette.

1 2 3 4
===========================
cpField || x13 | x13 | x14 | x15 ||
===========================
Passive---^ | | ^---Arrow
Active----------- ----------Selected