This is class represents a text field. This class is a little bit
problematic, because of PalmOS's intrinsic memory handling.
PalmOS seems to allow a field to grow, shrink and delete the block of
memory it has assigned. So read the descriptions of
PField(...),
text(PString&) and
handle(Handle)
carefully.
Synopsis
#include <PLField.h>
PField(PForm* parent, Word id,
Word scrollbarId,
PString& initialText = 0, Boolean keepText = false);
Contructs a field from the resource id and adds it to
parent as a child. Specifying initialText and
keep does the same thing as calling
text(initialText, keepText)
. Please read this and the notes to
handle(Handle)carefully.
PField(PForm* parent, Word id,
Word scrollbarId,
PString& initialText = 0, Boolean keepText = false);
Attaches a scrollbar from a resource id to the field. The class runtime
does the adjustment and the handling of the scrollbar. There is no overlap
when scrolling. I will allow this in the future. Again, please read
text(initialText, keepText)
and handle(Handle).
PField(PForm* parent, FieldPtr fieldPtr);
Creates a Field from a FieldPtr returned by the system. This is intended
for internal use by tables only (BTW, keep is set to true).
PString text();
Returns the field's contents as a PString
PField& text(const PString& text, Boolean keepText = false);
A new memory handle will be created, the text will be
copied to it and the field's text handle
will be set. When the object is destroyed, the field's handle will
be set to 0 and the allocated memory will be freed, unless
keepText is set to true. In this case,
the handle will be left to the field and will be freed when the form
is closed. Leaving keepText false will result in an empty
field when the object is destroyed.handle() if keepText is false
and will be freed when the form is closed or the
application sets it explicitely with handle(Handle h).
Handle handle();
Returns the handle of the field's allocated text memory, if available
to the application, 0 otherwise. It's length can be retrieved with
allocated().
PField& handle(Handle h, Boolean keepHandle = true);
Sets the field's memory handle. The meaning of keepHandle
differs from the one of text(PString&). If it is true (default)
the memory will be left to the application. That is, if a form is closed
or another call to handle(Handle) is made, the field's internal
handle is reset to 0 respectively replaced. If it false, the field takes over
the management of the handle. Closing a form or calling
handle(Handle) again will release and invalidate the memory.
Be very carefull with this when passing handles to database records! You
can explicetely avoid this by calling handle(0).
In opposite to text(PString&) only non-kept handles can be
retrieved by handle() and allocated().
PField& attachScrollbar(Word id);
Associates a scrollbar with a field. See
constructors for details.
PField& scroll(enum directions dir, short lines = 0)
Scrolls the field. dir can be either up or
down. If lines is omitted, the field scrolls
the number of visible lines.
FieldPtr fieldPtr();
Returns the FieldPtr if the parent form is already shown,
otherwise it returns 0. This can be used to access PalmOS APIs that are not
implemented yet.
PField& underline(Boolean underlined = true);
Boolean underlined();
Set and query the underlined attribute of a field.
PField& grabFocus(Boolean focus = true);
PField& relaseFocus();
Grabs or releases the focus. These functions do not always work,
don't ask me why.