8 Fields

This chapter provides the following information about field objects:

• Field Data Structures
  
  
• Field Resources
  
  
• Field Functions
  

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.

Field Data Structures

FieldAttrType

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.

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;

Field Descriptions

FieldPtr

The FieldPtr type defines a pointer to a FieldType structure.

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

The FieldType structure represents a field.

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.

Field Descriptions

LineInfoPtr

The LineInfoPtr type defines a pointer to the LineInfoType.

typedef LineInfoType* LineInfoPtr;

LineInfoType

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.

typedef struct {

    UInt16 start;
    UInt16 length;
} LineInfoType;

Field Descriptions

Field Resources

The Field Resource (tFLD) represents a field on screen.

Field Functions

FldCalcFieldHeight

Purpose

Determine the height of a field for a string.

Prototype

UInt16 FldCalcFieldHeight (const Char* chars, UInt16 maxWidth)

Parameters

-> chars

Pointer to a null-terminated string.

-> maxWidth

Maximum line width in pixels.

Result

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

FldWordWrap

FldCompactText

Purpose

Compact the memory block that contains the field's text to release any unused space.

Prototype

void FldCompactText (FieldType* fldP)

Parameters

-> fldP

Pointer to a field object (FieldType structure).

Result

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

Purpose

Copy the current selection to the text clipboard.

Prototype

void FldCopy (const FieldType* fldP)

Parameters

-> fldP

Pointer to a field object (FieldType structure).

Result

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

Purpose

Copy the current selection to the text clipboard, delete the selection from the field, and redraw the field.

Prototype

void FldCut (FieldType* fldP)

Parameters

-> fldP

Pointer to a field object (FieldType structure).

Result

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

Purpose

Delete the specified range of characters from the field and redraw the field.

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.

Result

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.

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

Purpose

Return true if the field has been modified since the text value was set.

Prototype

Boolean FldDirty (const FieldType* fldP)

Parameters

-> fldP

Pointer to a field object (FieldType structure).

Result

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

Purpose

Draw the text of the field.

Prototype

void FldDrawField (FieldType* fldP)

Parameters

-> fldP

Pointer to a field object (FieldType structure).

Result

Returns nothing.

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

FldEraseField

Purpose

Erase the text of a field and turn off the insertion point if it's in the field.

Prototype

void FldEraseField (FieldType* fldP)

Parameters

-> fldP

Pointer to a field object (FieldType structure).

Result

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.

This function sets the visible attribute to false. (See FieldAttrType.)

See Also

FldDrawField

FldFreeMemory

Purpose

Release the handle-based memory allocated to the field's text and the associated word-wrapping information.

Prototype

void FldFreeMemory (FieldType* fldP)

Parameters

-> fldP

Pointer to a field object (FieldType structure).

Result

Returns nothing. May raise a fatal error message if the text associated with the field is actually a record in a database.

Comments

This function releases

• The memory allocated to the text of a field--the memory block that the textHandle member of the FieldType data structure points to.
  

  If the field's textHandle is NULL but there is a text 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 the FieldType 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

Purpose

Return the attributes of a field.

Prototype

void FldGetAttributes (const FieldType* fldP, FieldAttrPtr attrP)

Parameters

-> fldP

Pointer to a FieldType structure.

<- attrP

Pointer to the FieldAttrType structure.

Result

Returns the field's attributes in the attrP parameter.

See Also

FldSetAttributes

FldGetBounds

Purpose

Return the current bounds of a field.

Prototype

void FldGetBounds (const FieldType* fldP, RectanglePtr rect)

Parameters

-> fldP

Pointer to a field object (FieldType structure).

<- rect

Pointer to a RectangleType structure.

Result

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

Purpose

Return the ID of the font used to draw the text of a field.

Prototype

FontID FldGetFont (const FieldType* fldP)

Parameters

-> fldP

Pointer to a field object (FieldType structure).

Result

Returns the ID of the font.

See Also

FldSetFont

FldGetInsPtPosition

Purpose

Return the insertion point position within the string.

Prototype

UInt16 FldGetInsPtPosition (const FieldType* fldP)

Parameters

-> fldP

Pointer to a field object (FieldType structure).

Result

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

FldGetMaxChars

Purpose

Return the maximum number of bytes the field accepts.

Prototype

UInt16 FldGetMaxChars (const FieldType* fldP)

Parameters

-> fldP

Pointer to a field object (FieldType structure).

Result

Returns the maximum length in bytes of characters the user is allowed to enter. This is the maxChars field in FieldType.

See Also

FldSetMaxChars

FldGetNumberOfBlankLines

Purpose

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

Prototype

UInt16 FldGetNumberOfBlankLines (const FieldType* fldP)

Parameters

-> fldP

Pointer to a FieldType structure.

Result

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

Purpose

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

Prototype

UInt16 FldGetScrollPosition (const FieldType* fldP)

Parameters

-> fldP

Pointer to a field object (FieldType structure).

Result

Returns the offset of the first visible character.

See Also

FldSetScrollPosition, LineInfoType

FldGetScrollValues

Purpose

Return the values necessary to update a scroll bar.

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.

Result

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

FldSetScrollPosition

FldGetSelection

Purpose

Return the current selection of a field.

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.

Result

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

FldGetTextAllocatedSize

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.

Prototype

UInt16 FldGetTextAllocatedSize (const FieldType* fldP)

Parameters

-> fldP

Pointer to a field object.

Result

Returns the number of bytes allocated for the field's text. This is the textBlockSize field in FieldType.

See Also

FldSetTextAllocatedSize

FldGetTextHandle

Purpose

Return a handle to the block that contains the text string of a field.

Prototype

MemHandle FldGetTextHandle (const FieldType* fldP)

Parameters

-> fldP

Pointer to a field object (FieldType structure).

Result

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

Purpose

Return the height in pixels of the number of lines that are not empty.

Prototype

UInt16 FldGetTextHeight (const FieldType* fldP)

Parameters

-> fldP

Pointer to a field object (FieldType structure).

Result

Returns the height in pixels of the number of 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.

See Also

FldCalcFieldHeight

FldGetTextLength

Purpose

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

Prototype

UInt16 FldGetTextLength (const FieldType* fldP)

Parameters

-> fldP

Pointer to a field object (FieldType structure).

Result

Returns the length in bytes of a field's text, not including the terminating null character. This is the textLen field of FieldType.

FldGetTextPtr

Purpose

Return a locked pointer to the field's text string.

Prototype

Char* FldGetTextPtr (FieldType* fldP)

Parameters

-> fldP

Pointer to a field object (FieldType structure).

Result

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.

See Also

FldSetTextPtr, FldGetTextHandle

FldGetVisibleLines

Purpose

Return the number of lines that can be displayed within the visible bounds of the field.

Prototype

UInt16 FldGetVisibleLines (const FieldType* fldP)

Parameters

-> fldP

Pointer to a field object (FieldType structure).

Result

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

Purpose

Turn the insertion point on (if the specified field is visible) and position the blinking insertion point in the field.

Prototype

void FldGrabFocus (FieldType* fldP)

Parameters

-> fldP

Pointer to a field object (FieldType structure).

Result

Returns nothing.

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

Purpose

Handles events that affect the field, including the following: keyDownEvent, penDownEvent, and fldEnterEvent.

Prototype

Boolean FldHandleEvent (FieldType* fldP, EventType* eventP)

Parameters

-> fldP

Pointer to a field object (FieldType structure).

-> eventP

Pointer to an event (EventType data structure).

Result

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

Purpose

Replace the current selection if any with the specified string and redraw the field.

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.

Result

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

Purpose

Cause a dynamically resizable field to expand its height to make its text fully visible.

Prototype

Boolean FldMakeFullyVisible (FieldType* fldP)

Parameters

-> fldP

Pointer to a field object (FieldType structure).

Result

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.

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

TblHandleEvent

FldNewField

Purpose

Create a new field object dynamically and install it in the specified form.

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. Pass false to create a field that cannot be edited.

-> underlined

Pass noUnderline for no underline, or grayUnderline to have the field underline the text it displays. On Palm OS® version 3.1 and higher, pass solidUnderline 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 or rightAlign to specify left justification or right justification, respectively. The centerAlign 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.

Result

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

Purpose

Replace the current selection in the field, if any, with the contents of the text clipboard.

Prototype

void FldPaste (FieldType* fldP)

Parameters

-> fldP

Pointer to a field object (FieldType structure).

Result

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

Purpose

Update the structure that contains the word-wrapping information for each visible line.

Prototype

void FldRecalculateField (FieldType* fldP, Boolean redraw)

Parameters

-> fldP

Pointer to a field object (FieldType structure).

-> redraw

If true, redraws the field. Currently, this parameter must be set to true to update the word-wrapping information.

Result

Returns nothing.

Comments

If necessary, this function reallocates the memory block that contains the displayed lines information, the LineInfoType structure pointed to by the lines member of the FieldType data structure.

Call this function if the field's data structure is modified in a way that invalidates the visual appearance of the field (for example, if you update a field's text with FldSetTextPtr). However, many of the field functions, such as FldSetTextHandle, FldInsert, and FldDelete, recalculate the word-wrapping information for you.

FldReleaseFocus

Purpose

Turn the blinking insertion point off if the field is visible and has the current focus, reset the Graffiti state, and reset the undo state.

Prototype

void FldReleaseFocus (FieldType* fldP)

Parameters

-> fldP

Pointer to a field object (FieldType structure).

Result

Returns nothing.

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

FldGrabFocus

FldScrollable

Purpose

Return true if the field is scrollable in the specified direction.

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 in Window.h. It is an enum defining the constants up and down.

Result

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

See Also

FldScrollField

FldScrollField

Purpose

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

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 in Window.h. It is an enum defining the constants up and down.

Result

Returns nothing.

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 == up)
    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

Purpose

Send a fldChangedEvent to the event queue.

Prototype

void FldSendChangeNotification (const FieldType* fldP)

Parameters

-> fldP

Pointer to a field object.

Result

Returns nothing.

Comments

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

FldSendHeightChangeNotification

Purpose

Send a fldHeightChangedEvent to the event queue.

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.

Result

Returns nothing.

Comments

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

FldSetAttributes

Purpose

Set the attributes of a field.

Prototype

void FldSetAttributes (FieldType* fldP, const FieldAttrPtr attrP)

Parameters

-> fldP

Pointer to a FieldType structure.

-> attrP

Pointer to the attributes.

Result

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 you call FldDrawField.

You usually do not have to modify field attributes at runtime, so you rarely need to call this function.

See Also

FldGetAttributes, FieldAttrType

FldSetBounds

Purpose

Change the position or size of a field.

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.

Result

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

Purpose

Set whether the field has been modified.

Prototype

void FldSetDirty (FieldType* fldP, Boolean dirty)

Parameters

-> fldP

Pointer to a field object (FieldType structure).

-> dirty

true if the text is modified.

Result

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

Purpose

Set the font used by the field, update the word-wrapping information, and draw the field if the field is visible.

Prototype

void FldSetFont (FieldType* fldP, FontID fontID)

Parameters

-> fldP

Pointer to a field object (FieldType structure).

-> fontID

ID of new font.

Result

Returns nothing.

See Also

FldGetFont, FieldAttrType

FldSetInsertionPoint

Purpose

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

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

Result

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.

Compatibility

Implemented only if 2.0 New Feature Set is present.

See Also

TxtCharBounds

FldSetInsPtPosition

Purpose

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

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

Result

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

Purpose

Set the maximum number of bytes the field accepts (the maxChars value).

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.

Result

Returns nothing.

Comments

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

See Also

FldGetMaxChars

FldSetScrollPosition

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.

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

Result

Returns nothing.

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

Purpose

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

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.

Result

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.

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

TxtCharBounds

FldSetText

Purpose

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

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

Allocated size of text string, not the string length.

Result

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 database record so that you can edit that string directly using field routines.

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.

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

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.

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.

Result

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

Purpose

Set the text value of a field to the string associated with the specified handle. Does not update the display.

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.

Result

Returns nothing.

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.

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, FldSetText

FldSetTextPtr

Purpose

Set a noneditable field's text to point to the specified text string.

Prototype

void FldSetTextPtr (FieldType* fldP, Char* textP)

Parameters

-> fldP

Pointer to a field object (FieldType structure).

-> textP

Pointer to a null-terminated string.

Result

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.

See Also

FldSetTextHandle, FldGetTextPtr

FldSetUsable

Purpose

Set a field to usable or nonusable.

Prototype

void FldSetUsable (FieldType* fldP, Boolean usable)

Parameters

fldP

Pointer to a FieldType structure.

usable

true to set usable; false to set nonusable.

Result

Returns nothing.

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

Purpose

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

Prototype

void FldUndo (FieldType* fldP)

Parameters

fldP

Pointer to the field (FieldType structure) that has the focus.

Result

Returns nothing.

See Also

FldPaste, FldCut, FldDelete, FldInsert

FldWordWrap

Purpose

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

Prototype

UInt16 FldWordWrap (const Char* chars, Int16 maxWidth)

Parameters

-> chars

Pointer to a null-terminated string.

-> maxWidth

Maximum line width in pixels.

Result

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

See Also

FntWordWrap