This chapter provides the following information about field objects:
The header file Field.h
declares the API that this chapter describes. For more information on fields, see the section "Fields" in the Palm OS Programmer's Companion, vol. I.
Field Data Structures
FieldAttrType Struct
Purpose
The FieldAttrType
bit field defines the visible characteristics of the field. The functions FldGetAttributes()
and FldSetAttributes()
return and set these values. There are other functions that retrieve or set individual attributes defined here. Those functions are noted below.
WARNING! You must not call
FldSetAttributes()
to change any attributes that are noted as "for internal use only."
Prototype
typedef struct { UInt16 usable:1; UInt16 visible:1; UInt16 editable:1; UInt16 singleLine:1; UInt16 hasFocus:1; UInt16 dynamicSize:1; UInt16 insPtVisible:1; UInt16 dirty:1; UInt16 underlined:2; UInt16 justification:2; UInt16 autoShift:1; UInt16 hasScrollBar:1; UInt16 numeric:1; } FieldAttrType;
Fields
-
usable
- If not set, the field object is not considered part of the current interface of the application, and it doesn't appear on screen. The function
FldSetUsable()
sets this value, but it is better to useFrmShowObject()
. -
visible
- Set or cleared internally when the field object is drawn with
FldDrawField()
FrmShowObject()
, and erased withFldEraseField()
orFrmHideObject()
. -
editable
- If not set, the field object doesn't accept text input or editing commands and the insertion point cannot be positioned with the pen. The text can still be selected and copied.
-
singleLine
- (This flag is for internal use only) If set, the field is a single line of text high and the text does not wrap when it exceeds the width of the field. If not set, the text wraps to fill multiple lines. You cannot change the field type from single-line to multi-line, or vice versa, by changing the value of this flag.
-
hasFocus
- Set internally when the field has the current focus. The blinking insertion point appears in the field that has the current focus. Use the function
FrmSetFocus()
andFldReleaseFocus()
to set this value. Do not try to set this attribute withFldSetAttributes
. -
dynamicSize
- If set, a
fldHeightChangedEvent
is generated whenever the number of lines needs to increase or decrease. Your application needs to respond to this event by adjusting the size of the field's bounding box. If not set, the text wraps to fill more (or less) lines as required, but the event is not generated. Note that this bit does not cause the field to change size automatically; your application must respond to thefldHeightChangedEvent
and resize the field itself. - Set this attribute to
false
if the Single Line attribute is set. -
insPtVisible
- If set, the insertion point is scrolled into view. This attribute is for internal use only..
-
dirty
- If set, the user has modified the field. The functions
FldDirty()
andFldSetDirty()
retrieve this field's value. Do not try to set this attribute withFldSetAttributes
. -
underlined
- If set each line of the field, including blank lines, is underlined. Possible values are defined by the
UnderlineModeType
defined inWindow.h
: -
noUnderline
-
grayUnderline
-
solidUnderline
-
colorUnderline
- Editable text fields generally use
grayUnderline
as the value. - The
solidUnderline
value is only valid for Palm OS 3.1 and higher. - The
colorUnderline
value is only valid for Palm OS 3.5 and higher. -
justification
- Specifies the text alignment. Possible values are
leftAlign
andrightAlign
. (left or right justification only;centerAlign
justification is not supported). -
autoShift
- If set, auto-shift rules are applied.
-
hasScrollBar
- If set, the field has a scrollbar. The system sends more frequent
fldChangedEvent
s so the application can adjust the height appropriately. -
numeric
- If set, only the characters 0 through 9 and associated separators are allowed to be entered in the field. The associated separators are the thousands separator and the decimal character. The values of these two characters depend on the settings in the Formats prefs panel.
FieldPtr Typedef
Purpose
The FieldPtr
type defines a pointer to a FieldType
structure.
Prototype
typedef FieldType *FieldPtr;
You pass the FieldPtr
as an argument to all field functions. You can obtain the FieldPtr
using the function FrmGetObjectPtr()
in this way:
fldPtr = FrmGetObjectPtr(frm, FrmGetObjectIndex(frm, fldID));
where fldID
is the resource ID assigned when you created the field.
FieldType Struct
Purpose
The FieldType
structure represents a field.
WARNING! PalmSource, Inc. does not support or provide backward compatibility for the
FieldType
structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
Prototype
typedef struct { UInt16 id; RectangleType rect; FieldAttrType attr; Char *text; MemHandle textHandle; LineInfoPtr lines; UInt16 textLen; UInt16 textBlockSize; UInt16 maxChars; UInt16 selFirstPos; UInt16 selLastPos; UInt16 insPtXPos; UInt16 insPtYPos; FontID fontID; UInt8 reserved; } FieldType;
Your code should treat the FieldType
structure as opaque. Use the functions specified in the descriptions below to retrieve and set each value. Do not attempt to change structure member values directly.
Fields
-
id
- ID value you specified when you created the field resource. This ID value is included as part of the event data of
fldEnterEvent
. -
rect
- Position and size of the field object. The functions
FldGetBounds()
,FrmGetObjectBounds()
,FldSetBounds()
, andFrmSetObjectBounds()
-
attr
- Field object attributes. (See
FieldAttrType
.) -
text
- Pointer to the null-terminated string that is displayed by the field object. The functions
FldGetTextPtr()
andFldSetTextPtr()
retrieve and set this value (see below). - Never set the contents of this string directly; for example, do not pass this pointer as the destination value to a function such as
StrCopy
. -
textHandle
- Handle to the stored text or to a database record containing the stored text. The functions
FldGetTextHandle()
andFldSetTextHandle()
retrieve and set this value. - If
textHandle
is defined, the field calculates thetext
pointer when it locks the handle. In general, you should only useFldGetTextPtr()
andFldSetTextPtr()
on text fields that aren't editable. On editable text fields, useFldGetTextHandle()
andFldSetTextHandle()
. - Also note that editable text fields allocate the text handle as necessary. If a user starts typing in a field that doesn't have a text handle allocated, the field will allocate one. The field also resizes the text's memory block as necessary when the user adds more text.
-
lines
- Pointer to an array of
LineInfoType
structures. There is one entry in this array for each visible line of the text. (SeeLineInfoType
.) The field code maintains this array internally; you should never change thelines
array yourself. - Note that this value is
NULL
for single line fields, and for fields that do not have an allocated text handle. -
textLen
- Length in bytes of the string currently displayed by the field object; the null terminator is excluded. You can retrieve this value with
FldGetTextLength()
. -
textBlockSize
- Allocated size of the memory block that holds the field object's text string. You can retrieve this value with
FldGetTextAllocatedSize()
. - Fields allocate memory for the field text as needed, several bytes at a time.
- Note that
textBlockSize
may be different from the size of the chunk pointed to bytextHandle
. ThetextHandle
may point to a database record that contains, in part, the text displayed by the field. If you calledMemHandleSize()
on such atextHandle
, the number returned may be greater thantextBlockSize
. -
maxChars
- Maximum number of bytes the field object accepts. The functions
FldGetMaxChars()
andFldSetMaxChars()
retrieve and set this value. - Note the difference between
textLen
,textBlockSize
, andmaxChars
.textLen
is the number of bytes of character data thattext
actually holds.textBlockSize
is the amount of memory currently allocated for the text (which must be greater than or equal totextLen
), andmaxChars
sets the maximum value thattextBlockSize
andtextLen
can expand to. - For example, if you've created a text field for users to enter their first names in, you might specify that the maximum length of this field is 20 bytes. If a user enters "John" in this field,
textLen
is 4,textBlockSize
is 16, andmaxChars
is 20. -
selFirstPos
- Starting character offset in bytes of the current selection. Use
FldGetSelection()
andFldSetSelection()
to retrieve and set this value and theselLastPos
value. -
selLastPos
- Ending character offset in bytes of the current selection. When
selFirstPos
equalsselLastPos
, there is no selection. -
insPtXPos
- Horizontal location of the insertion point, given as the offset in bytes into the line indicated by
insPtYPos
. The functionsFldGetInsPtPosition()
andFldSetInsPtPosition()
retrieve and set a byte offset calculated from this value. If the insertion point isn't visible—if it's on a line that's either above or below the set of visible lines—insPtXPos
is the absolute byte offset of the insertion point. -
insPtYPos
- Vertical location of the insertion point, given as the display line where the insertion point is positioned. The first display line is zero. The first display line may be different from the first line of text in the field if the field has been scrolled. The functions
FldGetInsPtPosition()
andFldSetInsPtPosition()
retrieve and set a byte offset calculated from this value. If the insertion point isn't visible—if it's on a line that's either above or below the set of visible lines—insPtYPos
is set to0x8000
. -
fontID
- Font ID for the field. See
Font.h
for more information. The functionsFldGetFont()
andFldSetFont()
retrieve and set this value. -
reserved
- Reserved for future use.
LineInfoPtr Typedef
Purpose
The LineInfoPtr
type defines a pointer to the LineInfoType
.
Prototype
typedef LineInfoType *LineInfoPtr;
LineInfoType Struct
Purpose
The LineInfoType
structure defines an element in the field's lines
array. The lines
array contains the field's word wrapping information. There is one element in the array per visible line in the field, including visible lines that contain no text. The field code maintains this array internally; you should never change the lines
array yourself.
The functions FldCalcFieldHeight()
, FldGetVisibleLines()
, FldRecalculateField()
, and FldGetNumberOfBlankLines()
retrieve or set information in this structure. The scrolling functions FldGetScrollPosition()
, FldGetScrollValues()
, FldScrollField()
, and FldSetScrollPosition()
also retrieve or set information in this structure.
WARNING! PalmSource, Inc. does not support or provide backward compatibility for the
LineInfoType
structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
Prototype
typedef struct { UInt16 start; UInt16 length; } LineInfoType;
Fields
-
start
- The byte offset into the
FieldType
'stext
field of the first character displayed by this line. If the line is blank,start
is equal totextLen
andlength
is 0. -
length
- The length in bytes of the portion of the string displayed on this line. If the line is blank, the length is 0.
Field Resources
The Field Resource (tFLD) represents a field on screen. See Palm OS User Interface Guidelines for more information.
Field Functions
FldCalcFieldHeight Function
Purpose
Determine the height of a field for a string.
Declared In
Field.h
Prototype
UInt16 FldCalcFieldHeight ( const Char *chars, UInt16 maxWidth )
Parameters
Returns
Returns the total number of lines needed to draw the string passed.
Comments
The width of a field is contained in the rect
member of the FieldType
structure. You can retrieve this value in the following way:
FrmGetObjectBounds(frm, FrmGetObjectIndex(frm, fldID), &myRect); fieldWidth = myRect.extent.x; FldCalcFieldHeight(myString, fieldWidth);
See Also
FldCompactText Function
Purpose
Compact the memory block that contains the field's text to release any unused space.
Declared In
Field.h
Prototype
void FldCompactText ( FieldType *fldP )
Parameters
-
→
fldP
- Pointer to a field object (
FieldType
structure).
Returns
Comments
As characters are added to the field's text, the block that contains the text is grown. The block is expanded several bytes at a time so that it doesn't have to expand each time a character is added. This expansion may result in some unused space in the text block.
Applications should call this function on field objects that edit data records in place before the field is unlocked, or at any other time when a compact field is desirable; for example, before writing to the storage heap.
See Also
FldGetTextAllocatedSize()
, FldSetTextAllocatedSize()
FldCopy Function
Purpose
Copy the current selection to the text clipboard.
Declared In
Field.h
Prototype
void FldCopy ( const FieldType *fldP )
Parameters
-
→
fldP
- Pointer to a field object (
FieldType
structure).
Returns
Comments
This function leaves the current selection highlighted.
This function replaces anything previously in the text clipboard if there is text to copy. If no text is selected, the function beeps and the clipboard remains intact.
See Also
FldCut Function
Purpose
Copy the current selection to the text clipboard, delete the selection from the field, and redraw the field.
Declared In
Field.h
Prototype
void FldCut ( FieldType *fldP )
Parameters
-
→
fldP
- Pointer to a field object (
FieldType
structure).
Returns
Comments
If text is selected, the text is removed from the field, the field's dirty attribute is set, and anything previously in the text clipboard is replaced by the selected text.
If there is no selection or if the field is not editable, this function beeps.
See Also
FldCopy()
, FldPaste()
, FldUndo()
FldDelete Function
Purpose
Delete the specified range of characters from the field and redraw the field.
Declared In
Field.h
Prototype
void FldDelete ( FieldType *fldP, UInt16 start, UInt16 end )
Parameters
-
→
fldP
- Pointer to the field object (
FieldType
structure) to delete from. -
→
start
- The beginning of the range of characters to delete given as a valid byte offset into the field's
text
string. -
→
end
- The end of the range of characters to delete given as a valid byte offset into the field's
text
string. On systems that support multi-byte characters, this position must be an inter-character boundary. That is, it must not point to a middle byte of a multi-byte character. - If you pass a value that is greater than the number of bytes in the field, all characters in the field are deleted.
Returns
Comments
This function deletes all characters from the starting offset up to the ending offset and sets the field's dirty attribute. It does not delete the character at the ending offset.
If start
or end
point to an intra-character boundary, FldDelete
attempts to move the offset backward, toward the beginning of the text, until the offset points to an inter-character boundary (i.e., the start of a character).
FldDelete
posts a fldChangedEvent
to the event queue. If you call this function repeatedly, you may overflow the event queue with fldChangedEvents
. An alternative is to remove the text handle from the field, change the text, and then set the field's handle again. See FldGetTextHandle()
for a code example.
See Also
FldInsert()
, FldEraseField()
, TxtCharBounds()
FldDirty Function
Purpose
Return true
if the field has been modified since the text value was set.
Declared In
Field.h
Prototype
Boolean FldDirty ( const FieldType *fldP )
Parameters
-
→
fldP
- Pointer to a field object (
FieldType
structure).
Returns
Returns true
if the field has been modified either by the user or through calls to certain functions such as FldInsert()
and FldDelete()
, false
if the field has not been modified.
See Also
FldDrawField Function
Purpose
Declared In
Field.h
Prototype
void FldDrawField ( FieldType *fldP )
Parameters
-
→
fldP
- Pointer to a field object (
FieldType
structure).
Returns
Comments
The field's usable
attribute must be true
or the field won't be drawn.
This function doesn't erase the area behind the field before drawing.
If the field has the focus, the blinking insertion point is displayed in the field.
See Also
FldEraseField Function
Purpose
Erase the text of a field and turn off the insertion point if it's in the field.
Declared In
Field.h
Prototype
void FldEraseField ( FieldType *fldP )
Parameters
-
→
fldP
- Pointer to a field object (
FieldType
structure).
Returns
Comments
You rarely need to call this function directly. Instead, use FrmHideObject()
, which calls FldEraseField
for you.
This function visibly erases the field from the display, but it doesn't modify the contents of the field or free the memory associated with it.
If the field has the focus, the blinking insertion point is turned off.
This function sets the visible
attribute to false
. (See FieldAttrType
.)
See Also
FldFreeMemory Function
Purpose
Release the handle-based memory allocated to the field's text and the associated word-wrapping information.
Declared In
Field.h
Prototype
void FldFreeMemory ( FieldType *fldP )
Parameters
-
→
fldP
- Pointer to a field object (
FieldType
structure).
Returns
Returns nothing. May raise a fatal error message if the text associated with the field is actually a record in a database.
Comments
- The memory allocated to the text of a field—the memory block that the
textHandle
member of theFieldType
data structure points to.If the field's
textHandle
isNULL
but there is atext
string associated with that field (which is often the case with noneditable text fields), the text string is not freed. - The memory allocated to hold the word-wrapping information—the memory block that the
lines
member of theFieldType
data structure points to.
This function doesn't affect the display of the field. Fields allocate memory for the text string as needed, so it is not an error to call this function while the field is still displayed. That is, if text
is NULL
and the user starts typing in the field, the field simply allocates memory for text and continues.
FldGetAttributes Function
Purpose
Return the attributes of a field.
Declared In
Field.h
Prototype
void FldGetAttributes ( const FieldType *fldP, FieldAttrPtr attrP )
Parameters
-
→
fldP
- Pointer to a
FieldType
structure. -
←
attrP
- Pointer to the
FieldAttrType
structure.
Returns
Returns the field's attributes in the attrP
parameter.
See Also
FldGetBounds Function
Purpose
Return the current bounds of a field.
Declared In
Field.h
Prototype
void FldGetBounds ( const FieldType *fldP, RectanglePtr rect )
Parameters
-
→
fldP
- Pointer to a field object (
FieldType
structure). -
←
rect
- Pointer to a
RectangleType
structure.
Returns
Returns nothing. Stores the field's bounds in the RectangleType
structure reference by rect
.
Comments
Returns the rect
field of the FieldType
structure.
See Also
FldSetBounds()
, FrmGetObjectBounds()
FldGetFont Function
Purpose
Return the ID of the font used to draw the text of a field.
Declared In
Field.h
Prototype
FontID FldGetFont ( const FieldType *fldP )
Parameters
-
→
fldP
- Pointer to a field object (
FieldType
structure).
Returns
See Also
FldGetInsPtPosition Function
Purpose
Return the insertion point position within the string.
Declared In
Field.h
Prototype
UInt16 FldGetInsPtPosition( const FieldType *fldP )
Parameters
-
→
fldP
- Pointer to a field object (
FieldType
structure).
Returns
Returns the byte offset of the insertion point.
Comments
The insertion point is to the left of the byte offset that this function returns. That is, if this function returns 0, the insertion point is to the left of the first character in the string. In multiline fields, line feeds are counted as a single character in the string, and the byte offset after the line feed character is the beginning of the next line.
See Also
FldGetMaxChars Function
Purpose
Return the maximum number of bytes the field accepts.
Declared In
Field.h
Prototype
UInt16 FldGetMaxChars ( const FieldType *fldP )
Parameters
-
→
fldP
- Pointer to a field object (
FieldType
structure).
Returns
Returns the maximum length in bytes of characters the user is allowed to enter. This is the maxChars
field in FieldType
.
See Also
FldGetNumberOfBlankLines Function
Purpose
Return the number of blank lines that are displayed at the bottom of a field.
Declared In
Field.h
Prototype
UInt16 FldGetNumberOfBlankLines( const FieldType *fldP )
Parameters
-
→
fldP
- Pointer to a
FieldType
structure.
Returns
Returns the number of blank lines visible.
Comments
This routine is useful for updating a scroll bar after characters have been removed from the text in a field. See the NoteViewScroll
function in the Address sample application for an example.
Compatibility
Implemented only if 2.0 New Feature Set is present.
FldGetScrollPosition Function
Purpose
Return the offset of the first character in the first visible line of a field.
Declared In
Field.h
Prototype
UInt16 FldGetScrollPosition( const FieldType *fldP )
Parameters
-
→
fldP
- Pointer to a field object (
FieldType
structure).
Returns
Returns the offset of the first visible character.
See Also
FldSetScrollPosition()
, LineInfoType
FldGetScrollValues Function
Purpose
Return the values necessary to update a scroll bar.
Declared In
Field.h
Prototype
void FldGetScrollValues ( const FieldType *fldP, UInt16 *scrollPosP, UInt16 *textHeightP, UInt16 *fieldHeightP )
Parameters
-
→
fldP
- Pointer to a
FieldType
structure. -
←
scrollPosP
- The line of text that is the topmost visible line. Line numbering starts with 0.
-
←
textHeightP
- The number of lines needed to display the field's text, given the width of the field.
-
←
fieldHeightP
- The number of visible lines in the field.
Returns
Returns nothing. Stores the position, text height, and field height in the parameters passed in.
Comments
Use the values returned by this function to calculate the values you send to SclSetScrollBar()
to update the scroll bar. For example:
FldGetScrollValues (fldP, &scrollPos, &textHeight, &fieldHeight); if (textHeight > fieldHeight) maxValue = textHeight - fieldHeight; else if (scrollPos) maxValue = scrollPos; else maxValue = 0; SclSetScrollBar (bar, scrollPos, 0, maxValue, fieldHeight-1); }
Compatibility
Implemented only if 2.0 New Feature Set is present.
See Also
FldGetSelection Function
Purpose
Return the current selection of a field.
Declared In
Field.h
Prototype
void FldGetSelection ( const FieldType *fldP, UInt16 *startPosition, UInt16 *endPosition )
Parameters
-
→
fldP
- Pointer to a field object (
FieldType
structure). -
←
startPosition
- Pointer to the start of the selected characters range, given as the byte offset into the field's text.
-
←
endPosition
- Pointer to end of the selected characters range given as the byte offset into the field's text.
Returns
Returns the starting and ending byte offsets in startPosition
and endPosition
.
Comments
The first character in a field is at offset zero.
If the user has selected the first five characters of a field, startPosition
will contain the value 0 and endPosition
the value 5, assuming all characters are a single byte long.
See Also
FldGetTextAllocatedSize Function
Purpose
Return the number of bytes allocated to hold the field's text string. Don't confuse this number with the actual length of the text string displayed in the field.
Declared In
Field.h
Prototype
UInt16 FldGetTextAllocatedSize( const FieldType *fldP )
Parameters
Returns
Returns the number of bytes allocated for the field's text. This is the textBlockSize
field in FieldType
.
See Also
FldGetTextHandle Function
Purpose
Return a handle to the block that contains the text string of a field.
Declared In
Field.h
Prototype
MemHandle FldGetTextHandle ( const FieldType *fldP )
Parameters
-
→ fldP
- Pointer to a field object (
FieldType
structure).
Returns
Returns the handle to the text string of a field or NULL
if no handle has been allocated for the field pointer.
Comments
The handle returned by this function is not necessarily the handle to the start of the string. If you've used FldSetText()
to set the field's text to a string that is part of a database record, the text handle points to the start of that record. You'll need to compute the offset from the start of the record to the start of the string. You can either store the offset that you passed to FldSetText
or you can compute the offset by performing pointer arithmetic on the pointer you get by locking this handle and the pointer returned by FldGetTextPtr()
.
If you are obtaining the text handle so that you can edit the field's text, you must remove the handle from the field before you do so. If you change the text while it is being used by a field, the field's internal structures specifying the text length, allocated size, and word wrapping information can become out of sync. To avoid this problem, remove the text handle from the field, change the text, and then set the field's text handle again. For example:
// Get the handle for the string and unlock // it by removing it from the field. textH = FldGetTextHandle(fldP); FldSetTextHandle (fldP, NULL); /* Insert code that modifies the string here.*/ /* The basic steps are: */ /* resize the chunk if necessary,*/ /* lock the chunk, write to it, and then */ /* unlock the chunk. If the text is in a */ /* database record, use Data Manager calls. */ /* Update the text in the field. */ FldSetTextHandle (fldP, textH); FldDrawField(fldP);
See Also
FldSetTextHandle()
, FldGetTextPtr()
FldGetTextHeight Function
Purpose
Return the height in pixels of the number of visible lines that are not empty.
Declared In
Field.h
Prototype
UInt16 FldGetTextHeight ( const FieldType *fldP )
Parameters
-
→ fldP
- Pointer to a field object (
FieldType
structure).
Returns
Returns the height in pixels of the number of visible lines that are not empty.
Comments
Empty lines are all of the lines in the field following the last byte of text. Note that lines that contain only a linefeed are not empty. Also note that only lines that are visible are counted.
See Also
FldGetTextLength Function
Purpose
Return the length in bytes of the field's text.
Declared In
Field.h
Prototype
UInt16 FldGetTextLength ( const FieldType *fldP )
Parameters
-
→ fldP
- Pointer to a field object (
FieldType
structure).
Returns
Returns the length in bytes of a field's text, not including the terminating null character. This is the textLen
field of FieldType
.
FldGetTextPtr Function
Purpose
Return a locked pointer to the field's text string.
Declared In
Field.h
Prototype
Char *FldGetTextPtr ( const FieldType *fldP )
Parameters
-
→ fldP
- Pointer to a field object (
FieldType
structure).
Returns
Returns a locked pointer to the field's text string or NULL if the field is empty.
Comments
The pointer returned by this function can become invalid if the user edits the text after you obtain the pointer.
Do not modify the contents of the pointer yourself. If you change the text while it is being used by a field, the field's internal structures specifying the text length, allocated size, and word wrapping information can become out of sync. To avoid this problem, follow the instructions given under FldGetTextHandle()
.
WARNING! The pointer returned by this function is "owned" by the field until you specify a different pointer for the field. You should not store this pointer for future use, since the field can modify the size of the string, which can cause the pointer to become invalid.
See Also
FldSetTextPtr()
, FldGetTextHandle()
FldGetVisibleLines Function
Purpose
Return the number of lines that can be displayed within the visible bounds of the field, regardless of what text is stored in the field.
Declared In
Field.h
Prototype
UInt16 FldGetVisibleLines ( const FieldType *fldP )
Parameters
-
→ fldP
- Pointer to a field object (
FieldType
structure).
Returns
Returns the number of lines the field displays. (This is the size of the lines
array in the FieldType
structure.)
See Also
FldGetNumberOfBlankLines()
, FldCalcFieldHeight()
FldGrabFocus Function
Purpose
Turn the insertion point on (if the specified field is visible) and position the blinking insertion point in the field.
Declared In
Field.h
Prototype
void FldGrabFocus ( FieldType *fldP )
Parameters
-
→ fldP
- Pointer to a field object (
FieldType
structure).
Returns
Comments
You rarely need to call this function directly. Instead, use FrmSetFocus()
, which calls FldGrabFocus
for you.
One instance where you need to call FldGrabFocus
directly is to programmatically set the focus in a field that is contained in a table cell.
This function sets the field attribute hasFocus
to true
. (See FieldAttrType
.)
See Also
FrmSetFocus()
, FldReleaseFocus()
FldHandleEvent Function
Purpose
Handles events that affect the field, including the following: keyDownEvent
, penDownEvent
, and fldEnterEvent
.
Declared In
Field.h
Prototype
Boolean FldHandleEvent ( FieldType *fldP, EventType *eventP )
Parameters
-
→ fldP
- Pointer to a field object (
FieldType
structure). -
→ eventP
- Pointer to an event (
EventType
data structure).
Returns
Returns true
if the event was handled.
Comments
When a keyDownEvent
occurs in an editable text field, the keystroke appears in the field if it's a printable character or manipulates the insertion point if it's a "movement" character. The field is automatically updated.
When a penDownEvent
occurs, the field sends a fldEnterEvent
to the event queue.
When a fldEnterEvent
occurs, the field grabs the focus. If the user has tapped twice in the current location, the word at that location is selected. If the user has tapped three times, the entire line is selected. Otherwise, the insertion point is placed in the specified position.
When a menuCmdBarOpenEvent
occurs, the field adds paste, copy, cut, and undo buttons to the command toolbar. These buttons are only added if they make sense in the current context. That is, the cut button is only added if the field is editable, the paste button is only added if there is text on the clipboard and the field is editable, and the undo button is only added if there is an action to undo.
If the event alters the contents of the field, this function visually updates the field.
This function doesn't handle any events if the field is not editable or usable.
Compatibility
Double-tapping to select a word and triple-tapping to select a line are only supported if 3.5 New Feature Set is present.
FldHandleEvent
only handles the menuCmdBarOpenEvent
if 3.5 New Feature Set is present.
FldInsert Function
Purpose
Replace the current selection if any with the specified string and redraw the field.
Declared In
Field.h
Prototype
Boolean FldInsert ( FieldType *fldP, const Char *insertChars, UInt16 insertLen )
Parameters
-
→ fldP
- Pointer to the field object (
FieldType
structure) to insert to. -
→ insertChars
- Text string to be inserted.
-
→ insertLen
- Length in bytes of the text string to be inserted, not counting the trailing null character.
Returns
Returns true
if string was successfully inserted. Returns false
if:
- The
insertLen
parameter is 0. - The field is not editable.
- Adding the text would exceed the field's size limit (the
maxChars
value). - More memory must be allocated for the field, and the allocation fails.
Comments
If there is no current selection, the string passed is inserted at the position of the insertion point.
This function sets the field's dirty attribute and posts a fldChangedEvent
to the event queue. If you call this function repeatedly, you may overflow the event queue with fldChangedEvents
. An alternative is to remove the text handle from the field, change the text, and then set the field's handle again. See FldGetTextHandle()
for a code example.
See Also
FldPaste()
, FldDelete()
, FldCut()
, FldCopy()
FldMakeFullyVisible Function
Purpose
Generates an event to cause a dynamically resizable field to expand its height to make its text fully visible.
Declared In
Field.h
Prototype
Boolean FldMakeFullyVisible ( FieldType *fldP )
Parameters
-
→ fldP
- Pointer to a field object (
FieldType
structure).
Returns
Returns true
if the field is dynamically resizable and was not fully visible; false otherwise.
Comments
Use this function on a field whose dynamicSize
attribute is true
(see FieldAttrType
).
This function does not actually resize the field. Instead, it computes how big the field should be to be fully visible and then posts this information to the event queue in a fldHeightChangedEvent
.
NOTE: The event does not get generated if the number of lines in the field is equal to or greater than the value of the maximum lines attribute for the field.
If the field is contained in a table, the table's code handles the fldHeightChangedEvent
. If the field is directly on a form, your application code should handle the fldHeightChangedEvent
itself. The form code does not handle the event for you. Note that the constant maxFieldLines
defines the maximum number of lines a field can expand to if the field is using the standard font.
See Also
FldNewField Function
Purpose
Create a new field object dynamically and install it in the specified form.
Declared In
Field.h
Prototype
FieldType *FldNewField ( void **formPP, UInt16 id, Coord x, Coord y, Coord width, Coord height, FontID font, UInt32 maxChars, Boolean editable, Boolean underlined, Boolean singleLine, Boolean dynamicSize, JustificationType justification, Boolean autoShift, Boolean hasScrollBar, Boolean numeric )
Parameters
-
↔ formPP
- Pointer to the pointer to the form in which the new field is installed. This value is not a handle; that is, the old form pointer value is not necessarily valid after this function returns. In subsequent calls, always use the new form pointer value returned by this function.
-
→ id
- Symbolic ID of the field, specified by the developer. By convention, this ID should match the resource ID (not mandatory).
-
→ x
- Horizontal coordinate of the upper-left corner of the field's boundaries, relative to the window in which it appears.
-
→ y
- Vertical coordinate of the upper-left corner of the field's boundaries, relative to the window in which it appears.
-
→ width
- Width of the field, expressed in pixels.
-
→ height
- Height of the field, expressed in pixels.
-
→
font
- Font to use to draw the field's text.
-
→
maxChars
- Maximum number of bytes held by the field this function creates.
-
→ editable
- Pass
true
to create a field in which the user can edit text. Passfalse
to create a field that cannot be edited. -
→ underlined
- Pass
noUnderline
for no underline, orgrayUnderline
to have the field underline the text it displays. On Palm OS® version 3.1 and higher, passsolidUnderline
to use a solid underline instead of a dotted underline. -
→ singleLine
- Pass
true
to create a field that can display only a single line of text. -
→ dynamicSize
- Pass
true
to create a field that resizes dynamically according to the amount of text it displays. -
→ justification
- Pass either of the values
leftAlign
orrightAlign
to specify left justification or right justification, respectively. ThecenterAlign
value is not supported. -
→ autoShift
- Pass
true
to specify the use of Palm OS 2.0 (and later) auto-shift rules. -
→ hasScrollBar
- Pass
true
to attach a scroll bar control to the field this function creates. -
→ numeric
- Pass
true
to specify that only characters in the range of 0 through 9 are allowed in the field.
Returns
Returns a pointer to the new field object or NULL
if there wasn't enough memory to create the field. Out of memory situations could be caused by memory fragmentation.
Compatibility
Implemented only if 3.0 New Feature Set is present.
See Also
FrmValidatePtr()
, WinValidateHandle()
, CtlValidatePointer()
, FrmRemoveObject()
FldPaste Function
Purpose
Replace the current selection in the field, if any, with the contents of the text clipboard.
Declared In
Field.h
Prototype
void FldPaste ( FieldType *fldP )
Parameters
-
→ fldP
- Pointer to a field object (
FieldType
structure).
Returns
Comments
The function performs these actions:
- Scrolls the field, if necessary, so the insertion point is visible.
- Inserts the clipboard text at the position of the insertion point if there is no current selection.
- Positions the insertion point after the last character inserted.
- Doesn't delete the current selection if there is no text in the clipboard.
See Also
FldInsert()
, FldDelete()
, FldCut()
, FldCopy()
FldUndo()
FldRecalculateField Function
Purpose
Update the structure that contains the word-wrapping information for each visible line.
Declared In
Field.h
Prototype
void FldRecalculateField ( FieldType *fldP, Boolean redraw )
Parameters
-
→ fldP
- Pointer to a field object (
FieldType
structure). -
→ redraw
- If
true
, redraws the field.
Returns
Comments
This function will allocate the memory block that contains the displayed lines information if, and only if, the block does not yet exist.
You should call this function when you change the field width or text length of the field. Do not call this function after changing the font or field height.
Note that many of the field functions, including FldSetTextHandle()
, FldInsert()
, and FldDelete()
, recalculate the word-wrapping information for you.
Compatibility
In releases prior to Palm OS 4.0, the word-wrapping information is only updated if the redraw
parameter is set to true
. As of Palm OS 4.0 it is updated whenever FldRecalculateField
is called, regardless of the value of the redraw
parameter.
FldReleaseFocus Function
Purpose
Turn the blinking insertion point off if the field is visible and has the current focus, reset the Graffiti® or Graffiti 2 state, and reset the undo state.
Declared In
Field.h
Prototype
void FldReleaseFocus ( FieldType *fldP )
Parameters
-
→ fldP
- Pointer to a field object (
FieldType
structure).
Returns
Comments
This function sets the field attribute hasFocus
to false. (See FieldAttrType
.)
Usually, you don't need to call this function. If the field is in a form or in a table that doesn't use custom drawing functions, the field code releases the focus for you when the focus changes to some other control. If your field is in any other type of object, such as a table that uses custom drawing functions or a gadget, you must call FldReleaseFocus
when the focus moves away from the field.
See Also
FldScrollable Function
Purpose
Return true
if the field is scrollable in the specified direction.
Declared In
Field.h
Prototype
Boolean FldScrollable ( const FieldType *fldP, WinDirectionType direction )
Parameters
-
→ fldP
- Pointer to a field object (
FieldType
structure). -
→ direction
- The direction to test.
DirectionType
is defined inWindow.h
. It is an enum defining the constantsup
anddown
.
Returns
Returns true
if the field is scrollable in the specified direction; false otherwise.
See Also
FldScrollField Function
Purpose
Scroll a field up or down by the number of lines specified.
Declared In
Field.h
Prototype
void FldScrollField ( FieldType *fldP, UInt16 linesToScroll, WinDirectionType direction )
Parameters
-
→ fldP
- Pointer to a field object (
FieldType
structure). -
→ linesToScroll
- Number of lines to scroll.
-
→ direction
- The direction to scroll.
DirectionType
is defined inWindow.h
. It is an enum defining, among others, the constantswinUp
andwinDown
.
Returns
Comments
This function can't scroll horizontally, that is, right or left.
The field object is redrawn if it's scrolled; however, the scrollbar is not updated. Use SclSetScrollBar()
to update the scrollbar. For example:
FldScrollField (fldP, linesToScroll, direction); // Update the scroll bar. SclGetScrollBar (bar, &value, &min, &max, &pageSize); if (direction == winUp) value -= linesToScroll; else value += linesToScroll; SclSetScrollBar (bar, value, min, max, pageSize);
If the field is not scrollable in the direction indicated, this function returns without performing any work. You can use FldScrollable()
before calling this function to see if the field can be scrolled.
See Also
FldScrollable()
, FldSetScrollPosition()
FldSendChangeNotification Function
Purpose
Send a fldChangedEvent
to the event queue.
Declared In
Field.h
Prototype
void FldSendChangeNotification( const FieldType *fldP )
Parameters
Returns
Comments
This function is used internally by the field code. You normally never call it in application code.
FldSendHeightChangeNotification Function
Purpose
Send a fldHeightChangedEvent
to the event queue.
Declared In
Field.h
Prototype
void FldSendHeightChangeNotification( const FieldType *fldP, UInt16 pos, Int16 numLines )
Parameters
-
→ fldP
- Pointer to a field object.
-
→ pos
- Character position of the insertion point.
-
→ numLines
- New number of lines in the field.
Returns
Comments
This function is used internally by the field code. You normally never call it in application code.
FldSetAttributes Function
Purpose
Set the attributes of a field.
Declared In
Field.h
Prototype
void FldSetAttributes ( FieldType *fldP, const FieldAttrType *attrP )
Parameters
-
→ fldP
- Pointer to a
FieldType
structure. -
→ attrP
- Pointer to the attributes.
Returns
Comments
This function does not do anything to make the new attribute values take effect. For example, if you use this function to change the value of the underline attribute, you won't see its effect until you call FldDrawField()
.
You usually do not have to modify field attributes at runtime, so you rarely need to call this function.
WARNING! You must not call this function to change any attributes that are noted as "for internal use only."
The proper way to use FldSetAttributes
is to:
- Call
FldGetAttributes
to retrieve the attributes. - Set the specific flags that you want to modify.
- Call
FldSetAttributes
to make the modifications.
WARNING! You must not call any field routines between calling
FldGetAttributes
and FldSetAttributes
; this can cause the attributes to be out of sync, with unpredictable results.
See Also
FldGetAttributes()
, FieldAttrType
FldSetBounds Function
Purpose
Change the position or size of a field.
Declared In
Field.h
Prototype
void FldSetBounds ( FieldType *fldP, const RectangleType *rP )
Parameters
-
→ fldP
- Pointer to a field object (
FieldType
structure). -
→ rP
- Pointer to a RectangleType structure that contains the new bounds of the display.
Returns
Returns nothing. May raise a fatal error message if the memory block that contains the word-wrapping information needs to be resized and there is not enough space to do so.
Comments
If the field is visible, the field is redrawn within its new bounds.
NOTE: You can change the height or location of the field while it's visible, but do not change the width.
The memory block that contains the word-wrapping information (see LineInfoType
) will be resized if the number of visible lines is changed. The insertion point is assumed to be off when this routine is called.
Make sure that rect
is at least as tall as a single line in the current font. (You can determine this value by calling FntLineHeight()
.) If it's not, results are unpredictable.
See Also
FldGetBounds()
, FrmSetObjectBounds()
FldSetDirty Function
Purpose
Set whether the field has been modified.
Declared In
Field.h
Prototype
void FldSetDirty ( FieldType *fldP, Boolean dirty )
Parameters
-
→ fldP
- Pointer to a field object (
FieldType
structure). -
→ dirty
-
true
if the text is modified.
Returns
Comments
You typically call this function when you want to clear the dirty attribute. The dirty attribute is set when the user enters or deletes text in the field. It is also set by certain field functions, such as FldInsert()
and FldDelete()
.
See Also
FldSetFont Function
Purpose
Set the font used by the field, update the word-wrapping information, and draw the field if the field is visible.
Declared In
Field.h
Prototype
void FldSetFont ( FieldType *fldP, FontID fontID )
Parameters
-
→
fldP
- Pointer to a field object (
FieldType
structure). -
→
fontID
- ID of new font.
Returns
See Also
FldSetInsertionPoint Function
Purpose
Set the location of the insertion point based on a specified string position.
Declared In
Field.h
Prototype
void FldSetInsertionPoint ( FieldType *fldP, UInt16 pos )
Parameters
-
→
fldP
- Pointer to a
FieldType
structure. -
→
pos
- New location of the insertion point, given as a valid offset in bytes into the field's text. On systems that support multi-byte characters, you must make sure that this specifies an inter-character boundary (does not specify the middle or end bytes of a multi-byte character).
Returns
Comments
This routine differs from FldSetInsPtPosition()
in that it doesn't make the character position visible. FldSetInsertionPoint
also doesn't make the field the current focus of input if it was not already.
If pos
indicates a position beyond the end of the text in the field, the insertion point is set to the end of the field's text.
Compatibility
Implemented only if 2.0 New Feature Set is present.
See Also
FldSetInsPtPosition Function
Purpose
Set the location of the insertion point for a given string position.
Declared In
Field.h
Prototype
void FldSetInsPtPosition ( FieldType *fldP, UInt16 pos )
Parameters
-
→ fldP
- Pointer to a field object (
FieldType
structure). -
→ pos
- New location of the insertion point, given as a valid offset in bytes into the field's text. On systems that support multi-byte characters, you must make sure that this specifies an inter-character boundary (does not specify the middle or end bytes of a multi-byte character).
Returns
Comments
If the position is beyond the visible text, the field is scrolled until the position is visible.
See Also
FldGetInsPtPosition()
, TxtCharBounds()
FldSetMaxChars Function
Purpose
Set the maximum number of bytes the field accepts (the maxChars
value).
Declared In
Field.h
Prototype
void FldSetMaxChars ( FieldType *fldP, UInt16 maxChars )
Parameters
-
→ fldP
- Pointer to a field object (
FieldType
structure). -
→ maxChars
- Maximum size in bytes of the characters the user may enter. You may specify any value up to
maxFieldTextLen
.
Returns
Comments
Line feed characters are counted when the length of characters is determined.
See Also
FldSetMaxVisibleLines Function
Purpose
Allows the creation of tables and fields smaller than 121 pixels tall that still drag-select when there are more lines of text than will fit in the space provided.
Declared In
Field.h
Prototype
void FldSetMaxVisibleLines ( FieldType *fldP, UInt8 maxLines )
Parameters
-
→ fldP
- Pointer to a field object (
FieldType
structure). -
→ maxLines
- Maximum number of lines to which the field will visually grow.
Returns
Comments
A field can be dynamically expandable. When it is, the field package needs to know the maximum number of lines that should be visible so it can prevent the field from being expanded further. Since field expansion is actually handled by enclosing objects—tables or forms—this function's primary purpose is to allow the enclosing object to tell the field how big it can get.
By default, tables assume that the field can get as big as the table.
If you don't call this function, fields expect to be at least 121 pixels tall and try to grow repeatedly until they are.
FldSetScrollPosition Function
Purpose
Scroll the field such that the character at the indicated offset is the first character on the first visible line. Redraw the field if necessary.
Declared In
Field.h
Prototype
void FldSetScrollPosition ( FieldType *fldP, UInt16 pos )
Parameters
-
→ fldP
- Pointer to a field object (
FieldType
structure). -
→ pos
- Byte offset into the field's text string of first character to be made visible. On systems that support multi-byte characters, you must make sure that this specifies an inter-character boundary (does not specify the middle or end bytes of a multi-byte character).
Returns
Comments
This function scrolls the field but does not update the field's scrollbar. You should update the scrollbar after calling this function. To do so, first call FldGetScrollValues()
to determine the values to use, and then call SclSetScrollBar()
.
See Also
FldGetScrollPosition()
, FldScrollField()
, TxtCharBounds()
FldSetSelection Function
Purpose
Set the current selection in a field and highlight the selection if the field is visible.
Declared In
Field.h
Prototype
void FldSetSelection ( FieldType *fldP, UInt16 startPosition, UInt16 endPosition )
Parameters
-
→ fldP
- Pointer to a field object (
FieldType
structure). -
→ startPosition
- Starting offset of the character range to highlight, given as a byte offset into the field's text.
-
→ endPosition
- Ending offset of the character range to highlight. The ending offset should be greater than or equal to the starting offset. On systems that support multi-byte characters, this position must be an inter-character boundary. That is, it must not point to a middle byte of a multi-byte character.
Returns
Comments
To cancel a selection, set both startPosition
and endPosition
to the same value. If startPosition equals endPosition, then the current selection is unhighlighted.
If either startPosition
or endPosition
point to an intra-character boundary, FldSetSelection
attempts to move that offset backward, toward the beginning of the string, until the offset points to an inter-character boundary (i.e., the start of a character).
See Also
FldSetText Function
Purpose
Set the text value of the field without updating the display.
Declared In
Field.h
Prototype
void FldSetText ( FieldType *fldP, MemHandle textHandle, UInt16 offset, UInt16 size )
Parameters
-
→ fldP
- Pointer to a field object (
FieldType
structure). -
→ textHandle
- Unlocked handle of a block containing a null-terminated text string. Pass
NULL
for this parameter to remove the association between the field and the string it is currently displaying so that the string is not freed with the field when the form is deleted. -
→ offset
- Offset from start of block to start of the text string.
-
→ size
- The allocated size of the text string. This is not the string length, and should not be set to
0
, unless you are setting the text to the empty string.
Returns
Comments
This function allows applications to perform editing in place in memory. You can use it to point the field to a string in a database record so that you can edit that string directly using field routines.
As characters are added to the field's text, the block that contains the text is grown. So that the block doesn't have to be expanded for each character, it is expanded several bytes at a time; this expansion may result in some unused space in the text block. As characters are removed from the field's text, the space is not automatically reclaimed. Because adding or removing characters when editing a data record in place may result in unused space at the end of the field's text block, applications should call FldCompactText()
on before the field is unlocked to release any unused space.
The handle that you pass to this function is assumed to contain a null-terminated string starting at offset
bytes in the memory chunk. The string should be between 0 and size
- 1 bytes in length. The field does not make a copy of the memory chunk or the string data; instead, it stores the handle to the record in its structure.
WARNING! You cannot use this function to set two fields on a form so that they share a single string value. Thus, for instance, if you have a single string containing a person's name you cannot call
FldSetText
twice with the same string (but a different offset) to set up a first name field and a last name field.
FldSetText
updates the word-wrapping information and places the insertion point after the last visible character, but it does not update the display. You must call FldDrawField()
after calling this function to update the display.
FldSetText
increments the lock count for textHandle
and decrements the lock count of its previous text handle (if any).
Because FldSetText
(and FldSetTextHandle
) may be used to edit database records, they do not free the memory associated with the previous text handle. If the previous text handle points to a string on the dynamic heap and you want to free it, use FldGetTextHandle()
to obtain the handle before using FldSetText
and then free that handle after using FldSetText
. (See FldSetTextHandle()
for a code example.)
If the field points to a database record, you want the memory associated with the text handle to persist; however, this memory and all other memory associated with the field is freed when the field itself is freed, which happens when the form is closed. If you don't want the memory associated with the text handle freed when the field is freed, use FldSetText
and pass NULL
for the text handle immediately before the form is closed. Passing NULL
removes the association between the field and the text handle that you want retained. That text handle is unlocked as a result of the FldSetText
call, and when the field is freed, there is no text handle to free with it.
See Also
FldSetTextPtr()
, FldSetTextHandle()
FldSetTextAllocatedSize Function
Purpose
Set the number of bytes allocated to hold the field's text string. Don't confuse this with the actual length of the text string displayed in the field.
Declared In
Field.h
Prototype
void FldSetTextAllocatedSize ( FieldType *fldP, UInt16 allocatedSize )
Parameters
-
→ fldP
- Pointer to a field object (
FieldType
structure). -
→ allocatedSize
- Number of bytes to allocate for the text.
Returns
Comments
This function generally is not used. It does not resize the field's allocated memory for the text string; it merely sets the textBlockSize
field of the FieldType
structure. The value of this field is computed and maintained internally by the field, so you should not have to call FldSetTextAllocatedSize
directly.
See Also
FldGetTextAllocatedSize()
, FldCompactText()
FldSetTextHandle Function
Purpose
Set the text value of a field to the string associated with the specified handle. Does not update the display.
Declared In
Field.h
Prototype
void FldSetTextHandle ( FieldType *fldP, MemHandle textHandle )
Parameters
-
→ fldP
- Pointer to a field object (
FieldType
structure). -
→ textHandle
- Unlocked handle of a field's text string. Pass
NULL
for this parameter to remove the association between the field and the string it is currently displaying so that the string is not freed with the field when the form is deleted.
Returns
Comments
This function differs from FldSetText()
in that it uses the entire memory chunk pointed to by textHandle
for the string. In fact, this function simply calls FldSetText
with an offset of 0 and a size equal to the entire length of the memory chunk. Use it to have the field edit a string in a database record if the entire record consists of that string, or use it to have the field edit a string in the dynamic heap.
As characters are added to the field's text, the block that contains the text is grown. So that the block doesn't have to be expanded for each character, it is expanded several bytes at a time; this expansion may result in some unused space in the text block. As characters are removed from the field's text, the space is not automatically reclaimed. Because adding or removing characters when editing a data record in place may result in unused space at the end of the field's text block, applications should call FldCompactText()
on before the field is unlocked to release any unused space.
FldSetTextHandle
updates the word-wrapping information and places the insertion point after the last visible character, but it does not update the display. You must call FldDrawField()
after calling this function to update the display.
FldSetTextHandle
increments the lock count for textHandle
and decrements the lock count of its previous text handle (if any).
Because FldSetTextHandle
(and FldSetText
) may be used to edit database records, they do not free the memory associated with the previous text handle. If the previous text handle points to a string on the dynamic heap and you want to free it, use FldGetTextHandle()
to obtain the handle before using FldSetText
and then free that handle after using FldSetText
. For example:
/* get the old text handle */ oldTxtH = FldGetTextHandle(fldP); /* change the text and update the display */ FldSetTextHandle(fldP, txtH); FldDrawField(fldP); /* free the old text handle */ if (oldTxtH != NULL) MemHandleFree(oldTxtH);
If the field points to a database record, you want the memory associated with the text handle to persist; however, this memory and all other memory associated with the field is freed when the field itself is freed, which happens when the form is closed. If you don't want the memory associated with the text handle freed when the field is freed, use FldSetTextHandle
and pass NULL
for the text handle immediately before the form is closed. Passing NULL
removes the association between the field and the text handle that you want retained. That text handle is unlocked as a result of the FldSetTextHandle
call, and when the field is freed, there is no text handle to free with it.
See Also
FldSetTextPtr Function
Purpose
Set a noneditable field's text to point to the specified text string.
Declared In
Field.h
Prototype
void FldSetTextPtr ( FieldType *fldP, Char *textP )
Parameters
-
→ fldP
- Pointer to a field object (
FieldType
structure). -
→ textP
- Pointer to a null-terminated string.
Returns
Returns nothing. May display an error message if passed an editable text field.
Comments
Do not call FldSetTextPtr
with an editable text field. Instead, call FldSetTextHandle()
for editable text fields. FldSetTextPtr
is intended for displaying noneditable text in the user interface.
If the field has more than one line, use FldRecalculateField()
to recalculate the word wrapping.
This function does not visually update the field. Use FldDrawField()
to do so.
The field never frees the string that you pass to this function, even when the field itself is freed. You must free the string yourself. Before you free the string, make sure the field is not still displaying it. Set the field's string pointer to some other string or call FldSetTextPtr(fldP, NULL)
before freeing a string you have passed using this function.
Compatibility
On versions of Palm OS prior to Palm OS 4.0 you cannot supply NULL
for the textP
parameter: the function calls StrLen()
on the NULL
pointer which results in a crash.
See Also
FldSetTextHandle()
, FldGetTextPtr()
FldSetUsable Function
Purpose
Set a field to usable or nonusable.
Declared In
Field.h
Prototype
void FldSetUsable ( FieldType *fldP, Boolean usable )
Parameters
-
fldP
- Pointer to a
FieldType
structure. -
usable
-
true
to set usable; false to set nonusable.
Returns
Comments
A nonusable field doesn't display or accept input.
Use FrmHideObject()
and FrmShowObject()
instead of using this function.
See Also
FldEraseField()
, FldDrawField()
, FieldAttrType
FldUndo Function
Purpose
Undo the last change made to the field object, if any. Changes include typing, backspaces, delete, paste, and cut.
Declared In
Field.h
Prototype
void FldUndo ( FieldType *fldP )
Parameters
-
fldP
- Pointer to the field (
FieldType
structure) that has the focus.
Returns
See Also
FldPaste()
, FldCut()
, FldDelete()
, FldInsert()
FldWordWrap Function
Purpose
Given a string and a width, return the number of bytes of characters that can be displayed using the current font.
Declared In
Field.h
Prototype
UInt16 FldWordWrap ( const Char *chars, Int16 maxWidth )
Parameters
Returns
Returns the length in bytes of the characters that can be displayed.