Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

18    Field Reference

User Interface

Exploring Palm OS®

This chapter provides the following information about text fields:

Field Structures and Types
Field Constants
Field Events
Field Functions and Macros

The header file Field.h declares the API that this chapter describes. For more information on fields, see the section Chapter 5, "Displaying Text."

Field Structures and Types ^TOP^

FieldAttrType Struct ^TOP^

Purpose

Defines the visible characteristics of the field.

Declared In

Field.h

Prototype

typedef struct FieldAttrTag {
   uint16_t usable :1;
   uint16_t visible :1;
   uint16_t editable :1;
   uint16_t singleLine :1;
   uint16_t hasFocus :1;
   uint16_t dynamicSize :1;
   uint16_t insPtVisible :1;
   uint16_t dirty :1;
   uint16_t underlined :2;
   uint16_t justification :2;
   uint16_t autoShift :1;
   uint16_t hasScrollBar :1;
   uint16_t numeric :1;
   uint16_t unused :1;
} FieldAttrType;
typedef FieldAttrType *FieldAttrPtr

Fields

usable
If not set, the field 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 use FrmShowObject() and FrmHideObject().
visible
Set or cleared internally when the field is drawn with FldDrawField() or FrmShowObject(), and erased with FldEraseField() or FrmHideObject().
editable
If not set, the field 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
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 set this value only when creating the field resource in a resource file. 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() to set this value. Do not use FldSetAttributes().
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 the fldHeightChangedEvent and resize the field itself.
This attribute should not be set for single-line fields.
insPtVisible
If set, the insertion point is scrolled into view. This attribute is set and cleared internally. Do not try to set it.
dirty
If set, the user has modified the field. The functions FldDirty() and FldSetDirty() retrieve and set this field's value. Do not try to set this value with FldSetAttributes().
underlined
If set, each line of the field, including blank lines, is underlined. Possible values are defined by the UnderlineModeType.
Editable text fields generally use grayUnderline or thinUnderline as the value.
justification
Specifies the text alignment. See JustificationType.
autoShift
If set, auto-shift rules are applied.
hasScrollBar
If set, the field has a scroll bar. The system sends more frequent fldChangedEvents 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 preferences panel.
unused
Reserved for future use.

See Also

FldGetAttributes(), FldSetAttributes()

FieldType Struct ^TOP^

Purpose

An internal structure that represents a field. The FieldPtr type defines a pointer to a FieldType structure.

Declared In

Field.h

Prototype

typedef struct FieldType FieldType;
typedef FieldType *FieldPtr

Fields

None.

Field Constants ^TOP^

JustificationType Typedef ^TOP^

Purpose

Specifies how the text field justifies the text it contains. See FieldAttrType.

Declared In

Field.h

Prototype

typedef Enum8 JustificationType

Constants

leftAlign
Text is aligned to the left with a ragged right.
centerAlign
Text is centered. This is not currently used.
rightAlign
Text is aligned along the right with a ragged left. Right justification works with both single and multi-line text fields.

Miscellaneous Constants ^TOP^

Purpose

Constants defined in Field.h.

Declared In

Field.h

Constants

#define maxFieldLines 11
The maximum number of lines a field can expand to in a standard sized form if the field is using the standard font.
Don't rely on this constant in Palm OS® Cobalt. If a form is dynamically sized, a field may display more or less than 11 lines in the standard font.
#define maxFieldTextLen SIZE_MAX
The maximum number of characters any text field can hold. Note that each field can set a maximum number of characters up to this size. See FldGetMaxChars() and FldSetMaxChars().
#define undoBufferSize 100
The number of bytes that can be held by the undo buffer. See FldUndo().

Field Events ^TOP^

fldChangedEvent ^TOP^

Purpose

Sent when the text of a field has or might have been scrolled.

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct fldChanged {
   struct FieldType *pField;
   uint16_t fieldID;
   _BA32_PADDING_16(1)
} fldChanged;

Fields

pField
Pointer to a field structure.
fieldID
Resource ID of the field.

Comments

Note that this event is not sent every time a field's value changes. It is sent only when the field might have been scrolled. Applications respond to this event to update the associated scroll bar.

fldEnterEvent ^TOP^

Purpose

Sent when a penDownEvent occurs within the bounds of a field

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct fldEnter {
   struct FieldType *pField;
   uint16_t fieldID;
   _BA32_PADDING_16(1)
} fldEnter;

Fields

pField
Pointer to a field structure.
fieldID
Resource ID of the field.

fldHeightChangedEvent ^TOP^

Purpose

Sent when the internal number of lines in the field changes.

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct fldHeightChanged {
   struct FieldType *pField;
   uint16_t fieldID;
   Coord newHeight;
   size_t currentPos;
} fldHeightChanged;

Fields

pField
Pointer to a field structure.
fieldID
Resource ID of the field.
newHeight
New visible height of the field, in number of lines.
currentPos
Current position of the insertion point.

Comments

This event is a notification to your application that the height of a field needs to change.


NOTE: This event is only sent for fields that have the dynamic size attribute set. If a field should resize because its form has been resized, the application receives the winResizedEvent instead.

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. Call FldSetBounds() to set the new height of the field, and, if necessary, reposition the other elements on the form to make room. Return false to have FldHandleEvent() adjust the insertion point for you.

Example

This example shows how to change the height of the field.


case fldHeightChangedEvent: 
   if (eventP->data.fldChanged.fieldID == MyField) { 
      RectangleType fldRect;
      FieldType *fldP = eventP->data.fldChanged.pField; 
 
      FldGetBounds(fldP, &fldRect); 
      fldRect.extent.y = eventP->data.fldChanged.newHeight; 
      FldSetBounds(fldP, fldRect); 
      handled = false; 
   } 
break; 

insertionPointOffEvent ^TOP^

Purpose

Sent when the field has focus and the cursor should blink. FldHandleEvent() responds to this event by removing the cursor from the display.

Declared In

EventCodes.h

Prototype

None.

insertionPointOnEvent ^TOP^

Purpose

Sent when the field has focus and the cursor should blink. FldHandleEvent() responds to this event by drawing the cursor.

Declared In

EventCodes.h

Prototype

None.

Field Functions and Macros ^TOP^

FldCalcFieldHeight Function ^TOP^

Purpose

Determines the height of a field for a string.

Declared In

Field.h

Prototype

uint32_t FldCalcFieldHeight (
   const char *chars,
   Coord maxWidth
)

Parameters

chars
Pointer to a null-terminated string.
maxWidth
Maximum line width in standard coordinates.

Returns

The total number of lines needed to draw the string passed.

Example

The following code shows how to determine the width of the field and pass that value as the maxWidth parameter:


FrmGetObjectBounds(frm, FrmGetObjectIndex(frm, fldID), 
  &myRect); 
fieldWidth = myRect.extent.x; 
FldCalcFieldHeight(myString, fieldWidth); 

See Also

FldWordWrap()

FldCompactText Function ^TOP^

Purpose

Compacts 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.

Returns

Nothing.

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 fields that edit data records in place within a non-schema database before the field is unlocked, or at any other time when a compact field is desirable; for example, before writing to the storage heap.

Applications should not call this function if the data is being edited in place within a schema database. Doing so has no effect.

This function may display a fatal error message if the memory cannot be compacted.

See Also

FldGetTextAllocatedSize(), FldSetTextAllocatedSize()

FldCopy Function ^TOP^

Purpose

Copies the current selection to the text clipboard.

Declared In

Field.h

Prototype

void FldCopy (
   const FieldType *fldP
)

Parameters

fldP
Pointer to a field.

Returns

Nothing.

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(), FldPaste()

FldCut Function ^TOP^

Purpose

Copies the current selection to the text clipboard, deletes the selection from the field, and redraws the field.

Declared In

Field.h

Prototype

void FldCut (
   FieldType *fldP
)

Parameters

fldP
Pointer to a field.

Returns

Nothing.

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 ^TOP^

Purpose

Deletes the specified range of characters from the field and redraws the field.

Declared In

Field.h

Prototype

void FldDelete (
   FieldType *fldP,
   size_t start,
   size_t end
)

Parameters

fldP
Pointer to a field.
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

Nothing.

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.

On debug ROMs, this function displays a fatal error message if start or end point to an intra-character boundary. On release ROMs, 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 (that is, 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 ^TOP^

Purpose

Returns 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.

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

FldSetDirty(), FieldAttrType

FldDrawField Function ^TOP^

Purpose

Draws the text of the field.

Declared In

Field.h

Prototype

void FldDrawField (
   FieldType *fldP
)

Parameters

fldP
Pointer to a field.

Returns

Nothing.

Comments

This function draws into a graphics context. Therefore, you must call it from within a frmUpdateEvent if the form that contains the field uses an update-based window.

The field must be usable or it 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(), FrmDrawForm()

FldEraseField Function ^TOP^

Purpose

Erases the text of a field and turns 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.

Returns

Nothing.

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.

See Also

FldDrawField()

FldFreeMemory Function ^TOP^

Purpose

Releases 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.

Returns

Nothing.

Comments

This function releases

  • The memory allocated to the text of a field if both a text handle and a text string are assigned to the field and are stored in the dynamic heap. If only a text string is assigned to the field but the text handle is NULL, the text string is not freed.
  • The memory allocated to hold the word-wrapping information.

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 the field's text string is NULL and the user starts typing in the field, the field simply allocates memory for text and continues.

FldGetAttributes Function ^TOP^

Purpose

Returns the attributes of a field.

Declared In

Field.h

Prototype

void FldGetAttributes (
   const FieldType *fldP,
   FieldAttrType *attrP
)

Parameters

fldP
Pointer to a field.
attrP
Pointer to the FieldAttrType structure.

Returns

Nothing.

See Also

FldSetAttributes()

FldGetBounds Function ^TOP^

Purpose

Returns the current bounds of a field.

Declared In

Field.h

Prototype

void FldGetBounds (
   const FieldType *fldP,
   RectanglePtr rect
)

Parameters

fldP
Pointer to a field.
rect
Pointer to a RectangleType structure.

Returns

Nothing.

See Also

FldSetBounds(), FrmGetObjectBounds()

FldGetFont Function ^TOP^

Purpose

Returns 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.

Returns

The FontID of the bitmapped font.

See Also

FldSetFont()

FldGetInsPtPosition Function ^TOP^

Purpose

Returns the insertion point position within the string.

Declared In

Field.h

Prototype

size_t FldGetInsPtPosition (
   const FieldType *fldP
)

Parameters

fldP
Pointer to a field.

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

FldSetInsPtPosition()

FldGetLineInfo Function ^TOP^

Purpose

Retrieves the word-wrapping information for a visible line within a field.

Declared In

Field.h

Prototype

Boolean FldGetLineInfo (
   const FieldType *fldP,
   uint32_t lineNum,
   size_t *startP,
   size_t *lengthP
)

Parameters

fldP
Pointer to a field.
lineNum
The number of the visible line in the field about which you want to retrieve information. Lines are numbered starting at 0.
startP
The byte offset into the FieldType's text string of the first character displayed by this line. If the line is empty, *startP is equal to the length of the field's text string.
lengthP
The length in bytes of the portion of the string displayed on this line. If the line is empty, the length is 0.

Returns

true if startP and lengthP contain valid values, or false if the field is a single-line field or does not contain a line numbered lineNum.

FldGetMaxChars Function ^TOP^

Purpose

Returns the maximum number of bytes the field accepts.

Declared In

Field.h

Prototype

size_t FldGetMaxChars (
   const FieldType *fldP
)

Parameters

fldP
Pointer to a field.

Returns

The maximum length in bytes of characters the user is allowed to enter.

See Also

FldSetMaxChars()

FldGetNumberOfBlankLines Function ^TOP^

Purpose

Returns the number of blank lines that are displayed at the bottom of a field.

Declared In

Field.h

Prototype

uint32_t FldGetNumberOfBlankLines (
   const FieldType *fldP
)

Parameters

fldP
Pointer to a field.

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 Book sample application for an example.

FldGetScrollPosition Function ^TOP^

Purpose

Returns the offset of the first character in the first visible line of a field.

Declared In

Field.h

Prototype

size_t FldGetScrollPosition (
   const FieldType *fldP
)

Parameters

fldP
Pointer to a field.

Returns

The offset from the start of the field's text string of the first visible character.

See Also

FldSetScrollPosition()

FldGetScrollValues Function ^TOP^

Purpose

Returns the values necessary to update a scroll bar.

Declared In

Field.h

Prototype

void FldGetScrollValues (
   const FieldType *fldP,
   uint32_t *scrollLineP,
   uint32_t *textHeightP,
   uint32_t *fieldHeightP
)

Parameters

fldP
Pointer to a field.
scrollLineP
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

Nothing.

Comments

May display a fatal error message if the field is a single-line text field.

Example

The following example shows how to use the values returned by this function to update the scroll bar associated with the field:


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); 

See Also

FldSetScrollPosition()

FldGetSelection Function ^TOP^

Purpose

Returns the current selection of a field.

Declared In

Field.h

Prototype

void FldGetSelection (
   const FieldType *fldP,
   size_t *startPosition,
   size_t *endPosition
)

Parameters

fldP
Pointer to a field.
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

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

FldSetSelection(), FldGetTextPtr()

FldGetTextAllocatedSize Function ^TOP^

Purpose

Returns 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

size_t FldGetTextAllocatedSize (
   const FieldType *fldP
)

Parameters

fldP
Pointer to a field.

Returns

The number of bytes allocated for the field's text.

Comments

Editable text fields allocate and resize the text memory block as necessary when the user adds more text.

See Also

FldSetTextAllocatedSize()

FldGetTextColumn Function ^TOP^

Purpose

Returns the schema database, record, column, and offset that this field is modifying.

Declared In

Field.h

Prototype

void FldGetTextColumn (
   const FieldType *fldP,
   DmOpenRef *databaseP,
   uint32_t *cursorP,
   uint32_t *positionP,
   uint32_t *columnIDP,
   size_t *offsetP
)

Parameters

fldP
Pointer to a field.
databaseP
Schema database where the text record is located.
cursorP
Database cursor ID, that is, the ID of the currently selected set of records.
positionP
Position of the database row within the cursor set.
columnIDP
ID of the column that the text field should modify.
offsetP
Offset into the column's data at which the text begins.

Returns

Nothing.

Comments

If the text field does not display information from a schema database, this function returns zeros in all of the parameters.

See Also

FldSetTextColumn(), FldReleaseStorage(), FldReturnStorage()

FldGetTextHandle Function ^TOP^

Purpose

Returns 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.

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.

Example

The following code shows how to properly edit the field's text:


/* 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 memory if necessary, lock the memory, write
to it, and then unlock the memory. If the text is in a
database record, use Data Manager calls. */ 
  
/* Update the text in the field and mark it invalid so that
it will be redrawn. */ 
FldSetTextHandle (fldP, textH); 
FldGetBounds(fldP, &rect); 
WinInvalidateRectangle(FrmGetWindowHandle(frmP), rect); 

See Also

FldSetTextHandle(), FldGetTextPtr()

FldGetTextHeight Function ^TOP^

Purpose

Returns the height in standard coordinates of the number of visible lines that are not empty.

Declared In

Field.h

Prototype

Coord FldGetTextHeight (
   const FieldType *fldP
)

Parameters

fldP
Pointer to a field.

Returns

The height in standard coordinates 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 line feed are not empty if they are followed by lines with text. Also note that only lines that are visible are counted.

See Also

FldCalcFieldHeight()

FldGetTextLength Function ^TOP^

Purpose

Returns the length in bytes of the field's text.

Declared In

Field.h

Prototype

size_t FldGetTextLength (
   const FieldType *fldP
)

Parameters

fldP
Pointer to a field.

Returns

The length in bytes of a field's text, not including the terminating null character.

FldGetTextPtr Function ^TOP^

Purpose

Returns 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.

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 because the field can modify the size of the string, which can cause the pointer to become invalid.

See Also

FldSetTextPtr()

FldGetVisibleLines Function ^TOP^

Purpose

Returns 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

uint32_t FldGetVisibleLines (
   const FieldType *fldP
)

Parameters

fldP
Pointer to a field.

Returns

The number of lines the field displays.

See Also

FldGetNumberOfBlankLines(), FldCalcFieldHeight()

FldGrabFocus Function ^TOP^

Purpose

Turns the insertion point on (if the specified field is visible) and positions the blinking insertion point in the field.

Declared In

Field.h

Prototype

void FldGrabFocus (
   FieldType *fldP
)

Parameters

fldP
Pointer to a field.

Returns

Nothing.

Comments

You rarely need to call this function directly. Instead, use FrmSetFocus(), which calls FldGrabFocus() for you.

If you call this function on a field whose form is not in the currently active window, this function silently fails.

See Also

FrmSetFocus(), FldReleaseFocus()

FldHandleEvent Function ^TOP^

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.
eventP
Pointer to an event (EventType data structure).

Returns

true if the event was handled.

Comments

If there is an active Front-End Processor (FEP), this function passes all events to the FEP code to give it a chance to handle them. A FEP is code that translates characters from one alphabet to another. For example, Japanese devices use a FEP to convert from Romaji characters to Katakana characters.

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 tool bar. 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.

When an insertionPointOffEvent or an insertionPointOnEvent occurs, this function either draws or erases the insertion point in the field and then posts the opposite event to the queue so that the cursor will blink.

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.

FldInsert Function ^TOP^

Purpose

Replaces the current selection if any with the specified string and redraws the field.

Declared In

Field.h

Prototype

Boolean FldInsert (
   FieldType *fldP,
   const char *insertChars,
   size_t insertLen
)

Parameters

fldP
Pointer to a field.
insertChars
Text string to be inserted.
insertLen
Length in bytes of the text string to be inserted, not counting the trailing null character.

Returns

true if string was successfully inserted, or false if:

  • The insertLen parameter is 0.
  • The field is not editable.
  • Adding the text would exceed the field's maximum number of characters.
  • 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 ^TOP^

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.

Returns

true if the field is dynamically resizable and was not fully visible; false otherwise.

Comments

Use this function only on fields that can dynamically resize.

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.

See Also

TblHandleEvent()

FldNewField Function ^TOP^

Purpose

Creates a new field dynamically and installs it in the specified form.

Declared In

Field.h

Prototype

FieldType *FldNewField (
   void **formPP,
   uint16_t id,
   Coord x,
   Coord y,
   Coord width,
   Coord height,
   FontID font,
   size_t 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 standard coordinates.
height
Height of the field, expressed in standard coordinates.
font
Font to use to draw the field's text. See FontID.
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. Pass false to create a field that cannot be edited.
underlined
true if the field should be underlined, false otherwise. By convention, editable fields are underlined, and noneditable fields are not underlined.
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 or rightAlign to specify left justification or right justification, respectively. The centerAlign value is not supported.
autoShift
Pass true to specify the use of auto-shift rules.
hasScrollBar
Pass true if you are going 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

A pointer to the new field or NULL if there wasn't enough memory to create the field. Out of memory situations could be caused by memory fragmentation.

See Also

FrmValidatePtr(), WinValidateHandle(), CtlValidatePointer(), FrmRemoveObject()

FldPaste Function ^TOP^

Purpose

Replaces 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.

Returns

Nothing.

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 ^TOP^

Purpose

Updates 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.
redraw
If true, redraws the field.

Returns

Nothing.

Comments

Word wrapping information is always kept current as the field is updated. This function invalidates the window region containing the field so that it is redrawn.

Call this function when you change the field width or the 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.

FldReleaseFocus Function ^TOP^

Purpose

Turns the blinking insertion point off, resets the pinlet input mode, and resets the undo state.

Declared In

Field.h

Prototype

void FldReleaseFocus (
   FieldType *fldP
)

Parameters

fldP
Pointer to a field.

Returns

Nothing.

Comments

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 user interface element, such as a gadget or a table that uses custom drawing functions, you must call FldReleaseFocus() when the focus moves away from the field.

See Also

FldGrabFocus()

FldReleaseStorage Function ^TOP^

Purpose

Releases the text field's lock on the schema database row with which it is associated.

Declared In

Field.h

Prototype

status_t FldReleaseStorage (
   FieldType *fldP
)

Parameters

fldP
Pointer to a field.

Returns

errNone upon success, one of the Database Manager errors if the database cannot be released or sysErrParamErr if the field does not point to a schema database column.

Comments

Use this function to release the field's lock on a database row. You need to do so when you need to make a change to a value in a different column than the one with which the field is associated or if you need to make some other change to the row (such as changing its category membership).


WARNING! Call FldReturnStorage() to reassociate the field with the row before calling any other Field function. Otherwise the application will crash. Do not change the data in the field's column in between calls to FldReleaseStorage() and FldReturnStorage(). Doing so also causes an application crash.

See Also

FldGetTextColumn(), FldSetTextColumn()

FldReplaceText Function ^TOP^

Purpose

Completely replaces the contents of the field's text pointer with the specified text.

Declared In

Field.h

Prototype

void FldReplaceText (
   FieldType *fldP,
   const char *textP
)

Parameters

fldP
Pointer to a field.
textP
New text that the field should display. The field makes a copy of this text.

Returns

Nothing.

Comments

This function replaces the contents of the field with the specified text, and recalculates the word wrapping information.

The keyboard dialog that displays on devices that do not have a dynamic input area uses this function to replace the field with the contents of the field in the dialog.

FldReturnStorage Function ^TOP^

Purpose

Reassociates a field with its schema database column after FldReleaseStorage() has been called.

Declared In

Field.h

Prototype

status_t FldReturnStorage (
   FieldType *fldP
)

Parameters

fldP
Pointer to a field.

Returns

errNone upon success, one of the Database Manager errors if the Database Manager cannot obtain the value of the text field's column, or sysErrParamErr if the text field is not associated with a schema database.

Comments

Call this function to reassociate a field with a schema database column after you've called FldReleaseStorage() to make a change to some other value in the database row. The field assumes that the value for its column has not changed. If it has changed, the application could crash.

See Also

FldGetTextColumn(), FldSetTextColumn()

FldScrollable Function ^TOP^

Purpose

Returns 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.
direction
The direction to test. See WinDirectionType.

Returns

true if the field is scrollable in the specified direction; false otherwise.

See Also

FldScrollField()

FldScrollField Function ^TOP^

Purpose

Scrolls a field up or down by the number of lines specified.

Declared In

Field.h

Prototype

void FldScrollField (
   FieldType *fldP,
   uint32_t linesToScroll,
   WinDirectionType direction
)

Parameters

fldP
Pointer to a field.
linesToScroll
Number of lines to scroll.
direction
The direction to scroll. See WinDirectionType.

Returns

Nothing.

Comments

This function can't scroll horizontally, that is, right or left.

The field is redrawn if it's scrolled; however, the scroll bar is not updated.

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.

Example

The following example calls this function and then uses SclSetScrollBar() to update the scroll bar:


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); 

See Also

FldSetScrollPosition()

FldSendChangeNotification Function ^TOP^

Purpose

Sends a fldChangedEvent to the event queue.

Declared In

Field.h

Prototype

void FldSendChangeNotification (
   const FieldType *fldP
)

Parameters

fldP
Pointer to a field.

Returns

Nothing.

Comments

This function is used internally by the field code. You normally never call it in application code.

FldSendHeightChangeNotification Function ^TOP^

Purpose

Sends a fldHeightChangedEvent to the event queue.

Declared In

Field.h

Prototype

void FldSendHeightChangeNotification (
   const FieldType *fldP,
   size_t pos,
   int32_t numLines
)

Parameters

fldP
Pointer to a field.
pos
Character position of the insertion point.
numLines
New number of lines in the field.

Returns

Nothing.

Comments

This function is used internally by the field code. You normally never call it in application code.

FldSetAttributes Function ^TOP^

Purpose

Sets the attributes of a field.

Declared In

Field.h

Prototype

void FldSetAttributes (
   FieldType *fldP,
   const FieldAttrType *attrP
)

Parameters

fldP
Pointer to a field.
attrP
Pointer to the attributes. See FieldAttrType.

Returns

Nothing.

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 some other actions causes the field to be redrawn.

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:

  1. Call FldGetAttributes() to retrieve the attributes.
  2. Set the specific flags that you want to modify.
  3. 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.

FldSetBounds Function ^TOP^

Purpose

Changes 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.
rP
Pointer to a RectangleType structure that contains the new bounds of the display.

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 will be resized if the number of visible lines is changed.

Make sure that rP 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 ^TOP^

Purpose

Sets whether the field has been modified.

Declared In

Field.h

Prototype

void FldSetDirty (
   FieldType *fldP,
   Boolean dirty
)

Parameters

fldP
Pointer to a field.
dirty
true if the text is modified.

Returns

Nothing.

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

FldDirty()

FldSetFont Function ^TOP^

Purpose

Sets the font used by the field, updates the word-wrapping information, and draws the field if the field is visible.

Declared In

Field.h

Prototype

void FldSetFont (
   FieldType *fldP,
   FontID fontID
)

Parameters

fldP
Pointer to a field.
fontID
ID of new font.

Returns

Nothing.

Comments

If the form that contains the field uses an update-based window, this function invalidates the window region containing the field. The field is redrawn during the next drawing update cycle.

See Also

FldGetFont(), FieldAttrType

FldSetInsertionPoint Function ^TOP^

Purpose

Sets the location of the insertion point based on a specified string position.

Declared In

Field.h

Prototype

void FldSetInsertionPoint (
   FieldType *fldP,
   size_t pos
)

Parameters

fldP
Pointer to a field.
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

Nothing.

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.

See Also

TxtCharBounds()

FldSetInsPtPosition Function ^TOP^

Purpose

Sets the location of the insertion point for a given string position.

Declared In

Field.h

Prototype

void FldSetInsPtPosition (
   FieldType *fldP,
   size_t pos
)

Parameters

fldP
Pointer to a field.
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

Nothing.

Comments

If the position is beyond the visible text, the field is scrolled until the position is visible.

See Also

FldGetInsPtPosition(), TxtCharBounds()

FldSetMaxChars Function ^TOP^

Purpose

Sets the maximum number of bytes the field accepts.

Declared In

Field.h

Prototype

void FldSetMaxChars (
   FieldType *fldP,
   size_t maxChars
)

Parameters

fldP
Pointer to a field.
maxChars
Maximum size in bytes of the characters the user may enter. You may specify any value up to maxFieldTextLen.

Returns

Nothing.

Comments

Line feed characters are counted when the length of characters is determined.

See Also

FldGetMaxChars()

FldSetMaxVisibleLines Function ^TOP^

Purpose

Sets the maximum number of visible lines for a dynamically sized field.

Declared In

Field.h

Prototype

void FldSetMaxVisibleLines (
   FieldType *fldP,
   uint8_t maxLines
)

Parameters

fldP
Pointer to a field.
maxLines
Maximum number of lines to which the field will visually grow.

Returns

Nothing.

Comments

This function is intended for dynamically sized fields, which are fields for which the application is sent fldHeightChangedEvents so that the application can expand or contract the visible number of lines as the text that the field contains grows and shrinks. Note that this dynamic sizing is independent of the form resizing. A field might grow and shrink as its form grows and shrinks but not be considered a dynamically sized field. Dynamically sized fields are ones whose size is determined by the amount of text they display.

FldSetScrollPosition Function ^TOP^

Purpose

Scrolls the field such that the character at the indicated offset is the first character on the first visible line. Redraws the field if necessary.

Declared In

Field.h

Prototype

void FldSetScrollPosition (
   FieldType *fldP,
   size_t pos
)

Parameters

fldP
Pointer to a field.
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

Nothing.

Comments

This function scrolls the field but does not update the field's scroll bar. You should update the scroll bar 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 ^TOP^

Purpose

Sets the current selection in a field and highlight the selection if the field is visible.

Declared In

Field.h

Prototype

void FldSetSelection (
   FieldType *fldP,
   size_t startPosition,
   size_t endPosition
)

Parameters

fldP
Pointer to a field.
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

Nothing.

Comments

To cancel a selection, set both startPosition and endPosition to the same value. If startPosition equals endPosition, then the current selection is unhighlighted.

On debug ROMs, this function displays a fatal error message if startPosition or endPosition point to an intra-character boundary. On release ROMs, 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 (that is, the start of a character).

See Also

TxtCharBounds()

FldSetText Function ^TOP^

Purpose

Sets the text value of the field without updating the display.

Declared In

Field.h

Prototype

void FldSetText (
   FieldType *fldP,
   MemHandle textHandle,
   size_t offset,
   size_t size
)

Parameters

fldP
Pointer to a field.
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

Nothing.

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 non-schema 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 block. The string should be between 0 and size - 1 bytes in length. The field does not make a copy of the memory block 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. To update the display after calling this function, you must call WinInvalidateRect() with the window region that displays the field. Do not call FldDrawField() directly unless your code is handling a frmUpdateEvent.

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.

See Also

FldSetTextPtr(), FldSetTextHandle(), FldSetTextColumn()

FldSetTextAllocatedSize Function ^TOP^

Purpose

Sets 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,
   size_t allocatedSize
)

Parameters

fldP
Pointer to a field.
allocatedSize
Number of bytes to allocate for the text.

Returns

Nothing.

Comments

This function generally is not used. It does not resize the field's allocated memory for the text string. It merely sets a value that is computed and maintained internally by the field, so you should not have to call FldSetTextAllocatedSize() directly.

See Also

FldGetTextAllocatedSize(), FldCompactText()

FldSetTextColumn Function ^TOP^

Purpose

Sets the field to modify a specific column within a schema database record.

Declared In

Field.h

Prototype

void FldSetTextColumn (
   FieldType *fldP,
   DmOpenRef database,
   uint32_t cursor,
   uint32_t position,
   uint32_t columnID,
   size_t offset
)

Parameters

fldP
Pointer to a field.
database
Open schema database where the record is located.
cursor
Database cursor ID, that is, the ID of the currently selected set of records. Use DbCursorOpen() to create a cursor.
position
Position of the database row within the cursor set.
columnID
ID of the column that the field should modify.
offset
Offset into the column's data at which the text begins.

Returns

Nothing.

Comments

This function allows applications to perform editing in place in memory. You can use it to point the field to a string within a column of a schema database record so that you can edit that string directly using field routines.

The column that you pass to this function is assumed to contain a null-terminated string starting at offset bytes in the memory block. The string should be between 0 and size - 1 bytes in length. The field does not make a copy of the memory block or the string data; instead, it stores the database information 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 FldSetTextColumn() twice with the same string (but a different offset) to set up a first name field and a last name field.

FldSetTextColumn() updates the word-wrapping information and places the insertion point after the last visible character, but it does not update the display. To update the display after calling this function, you must call WinInvalidateRect() with the window region that displays the field. Do not call FldDrawField() directly unless your code is handling a frmUpdateEvent.

When you use this function, the field holds a lock on the database row that it is currently displaying. If you need to change some other value in the row (such as the value in another column or the row's category membership), you must release the lock before you can do so. Call FldReleaseStorage() to release the lock. Then make your change. Then call FldReturnStorage() to reassociate the field with its column before the form redraws.

See Also

FldGetTextColumn(), FldSetText()

FldSetTextHandle Function ^TOP^

Purpose

Sets 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.
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

Nothing.

Comments

This function differs from FldSetText() in that it uses the entire memory block 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 block. 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 WinInvalidateRect() with the window region that displays the field. Do not call FldDrawField() directly unless your code is handling a frmUpdateEvent.

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().

When the form containing this field is closed, all memory associated with the field is freed including the text handle and its associated text string if they are in the dynamic heap. Text handles and text strings that are in the storage heap are not freed. If your text handle is in the dynamic heap and 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.

Example

The following example shows how to free the old memory associated with the field.


/* get the old text handle */ 
oldTxtH = FldGetTextHandle(fldP); 
  
/* change the text and update the display */ 
FldSetTextHandle(fldP, txtH); 
FldGetBounds(fldP, &rect); 
WinInvalidateRectangle(FrmGetWindowHandle(frmP), rect); 
  
/* free the old text handle */ 
if (oldTxtH != NULL)  
  MemHandleFree(oldTxtH); 

See Also

FldSetTextPtr(), FldSetText()

FldSetTextPtr Function ^TOP^

Purpose

Sets 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.
textP
Pointer to a null-terminated string.

Returns

Nothing.

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. To do so, call WinInvalidateRect() with the window region that displays the field. Do not call FldDrawField() directly unless your code is handling a frmUpdateEvent.

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.

This function may display an error message if passed an editable text field.

See Also

FldSetTextHandle(), FldGetTextPtr()

FldSetUsable Function ^TOP^

Purpose

Sets a field to usable or unusable.

Declared In

Field.h

Prototype

void FldSetUsable (
   FieldType *fldP,
   Boolean usable
)

Parameters

fldP
Pointer to a field.
usable
true to set usable; false to set nonusable.

Returns

Nothing.

Comments

An unusable field doesn't display or accept input.

Use FrmHideObject() and FrmShowObject() instead of using this function.

See Also

FldEraseField(), FldDrawField(), FieldAttrType

FldUndo Function ^TOP^

Purpose

Undoes the last change made to the field, if any. Changes include typing, backspaces, delete, paste, and cut.

Declared In

Field.h

Prototype

void FldUndo (
   FieldType *fldP
)

Parameters

fldP
Pointer to a field.

Returns

Nothing.

See Also

FldPaste(), FldCut(), FldDelete(), FldInsert()

FldWordWrap Function ^TOP^

Purpose

Given a string and a width, returns the number of bytes of characters that can be displayed using the current font.

Declared In

Field.h

Prototype

size_t FldWordWrap (
   const char *chars,
   Coord maxWidth
)

Parameters

chars
Pointer to a null-terminated string.
maxWidth
Maximum line width in standard coordinates.

Returns

The length in bytes of the characters that can be displayed.

See Also

FntWordWrap()