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.