API Guide Home (Online version only) |

# SmartTextEngine.h File Reference

## Detailed Description

Public 68K include file for Smart Text Engine shared library.

The Smart Text Engine (STE) Library can be used to enable hyperlink in your application and display icon as defined in the Resource Header file.

It will enable user to tap on:

- Phone number to dial using the phone application
- URL to browse
- Email to send an email by launching the default email application

The calling application should always load this library with SysLibLoad() before use, even if it is already open by another application(ie, SysLibFind() returns a valid refnum). When the application is done with the library, it should be unloaded with SysLibRemove(). We do this because there is no good way to synchronize loading and unloading of libraries among multiple applications. It also greatly simplifies internal synchronization.

        Err LoadSmartTextEngine(UInt16* refNumP, Boolean* libLoadedP)
            {
            Err error = 0;

            // Routine is pointless without this parameter
            if (!refNumP)
                return memErrInvalidParam;

            // always load the library, so we have our own instance of the engine
            error = SysLibLoad(sysFileTLibrary, hsFileCSmartTextEngine, refNumP);
            if (error)
                return error;
            *libLoadedP = true;

            return error;
            }

Definition in file SmartTextEngine.h.

Include dependency graph for SmartTextEngine.h:

Go to the source code of this file.

## Functions

- STEErr STEOpen (UInt16 refNum)
- STEErr STEClose (UInt16 refNum)
- STEErr STEGetAPIVersion (UInt16 refNum, UInt32 *majVerP, UInt32 *minVerP)
- STEErr STEInitializeEngine (UInt16 refNum, UInt16 *engineRefNum, RectangleType *listBounds, UInt16 scrollBarID, UInt32 flags, UInt8 phoneNumberColor, UInt8 urlColor, UInt8 emailColor)
- STEErr STEResetEngine (UInt16 refNum, UInt16 engineRefNum)
- STEErr STEReinitializeEngine (UInt16 refNum, UInt16 engineRefNum)
- void STEAppendTextToEngine (UInt16 refNum, UInt16 engineRefNum, Char *textP, Boolean renderImmediate)
- void STERemoveLastRecordFromEngine (UInt16 refNum, UInt16 engineRefNum)
- void STERenderList (UInt16 refNum, UInt16 engineRefNum)
- void STERerenderList (UInt16 refNum, UInt16 engineRefNum)
- Boolean STEHandleEvent (UInt16 refNum, UInt16 engineRefNum, EventPtr eventP)
- Boolean STEHandleSclRepeatEvent (UInt16 refNum, UInt16 engineRefNum, EventPtr eventP)
- Boolean STEHandlePenDownEvent (UInt16 refNum, UInt16 engineRefNum, EventPtr eventP)
- Boolean STEHandlePenMoveEvent (UInt16 refNum, UInt16 engineRefNum, EventPtr eventP)
- Boolean STEHandlePenUpEvent (UInt16 refNum, UInt16 engineRefNum, EventPtr eventP)
- Boolean STEHandleKeyDownEvent (UInt16 refNum, UInt16 engineRefNum, EventPtr eventP)
- UInt16 STEGetScroll (UInt16 refNum, UInt16 engineRefNum)
- void STESetScroll (UInt16 refNum, UInt16 engineRefNum, UInt16 scrollValue)
- UInt16 STEGetScrollPct (UInt16 refNum, UInt16 engineRefNum)
- void STESetScrollPct (UInt16 refNum, UInt16 engineRefNum, UInt16 scrollPct)
- void STESetScrollToRecordNum (UInt16 refNum, UInt16 engineRefNum, UInt16 recordNum)
- void STESetFlags (UInt16 refNum, UInt16 engineRefNum, UInt32 flagsToSet, UInt32 flagsToClear)
- UInt32 STEGetFlags (UInt16 refNum, UInt16 engineRefNum)
- UInt16 STEGetNumLines (UInt16 refNum, UInt16 engineRefNum)
- UInt16 STEGetNumRecords (UInt16 refNum, UInt16 engineRefNum)
- Boolean STEHasHotRectSelection (UInt16 refNum, UInt16 engineRefNum)
- Boolean STEHasMessageSelection (UInt16 refNum, UInt16 engineRefNum)
- Boolean STEHasTextSelection (UInt16 refNum, UInt16 engineRefNum)
- void STEClearCurrentSelection (UInt16 refNum, UInt16 engineRefNum)
- UInt16 STESetCurrentTextSelection (UInt16 refNum, UInt16 engineRefNum, UInt16 messageNumber, UInt32 startLocation, UInt32 selectionLength)
- void STEGetCurrentTextSelection (UInt16 refNum, UInt16 engineRefNum, UInt16 *messageNumber, UInt16 *startLocation, UInt16 *selectionLength)
- Char * STEGetSelectedText (UInt16 refNum, UInt16 engineRefNum)
- void STECopySelectionToClipboard (UInt16 refNum, UInt16 engineRefNum)
- void STEGetLastTapInfo (UInt16 refNum, UInt16 engineRefNum, UInt16 *messageNumber, UInt16 *tapLocation)
- void STESetCustomHyperlinkCallback (UInt16 refNum, UInt16 engineRefNum, STECallbackType callback, Boolean armCallback)
- void STEQuickRender (UInt16 refNum, RectangleType *listBounds, UInt32 flags, UInt8 phoneNumberColor, UInt8 urlColor, UInt8 emailColor, Char *msgP)
- ParsedInfoList * STEGetParsedInformation (UInt16 refNum, Char *textP, UInt16 msgNumber, Boolean replaceLineFeeds, UInt32 flags)
- void STEAppendParsedInfo (UInt16 refNum, MemHandle destParsedInfoH, ParsedInfoList *sourceParsedInfoP)

## Function Documentation

void STEAppendParsedInfo | ( | UInt16 | refNum,
|  | MemHandle | destParsedInfoH,
|  | ParsedInfoList * | sourceParsedInfoP |
| ) |  |  |

This routine append a ParsedInfoList to another ParsedInfoList.

This does NOT require the STE to be initialized. This is used internally by the STE. You probably will not use this function.

Parameters:

  | refNum,: | IN: The STE refNum
  | destParsedInfoH,: | IN: A handle to the destination parsed info list
  | sourceParsedInfoP,: | IN: The source parsed info list.

Return values:

  | - |

void STEAppendTextToEngine | ( | UInt16 | refNum,
|  | UInt16 | engineRefNum,
|  | Char * | textP,
|  | Boolean | renderImmediate |
| ) |  |  |

Function that is used to add text to the STE. Each text string that is appended is called a record. Record numbers are 1 based, meaning the first record is record 1.

Parameters:

  | refNum,: | IN: The STE refNum
  | engineRefNum,: | IN: The STE engine refNum
  | textP,: | IN: The text to append to the STE, including any STE delimiters
  | renderImmediate,: | IN: If true, the text will be displayed immediately. If false, it will not be displayed until STERenderList is called.

Return values:

  | - |

void STEClearCurrentSelection | ( | UInt16 | refNum,
|  | UInt16 | engineRefNum |
| ) |  |  |

This routine clears any currently selected text or hot rect.

Parameters:

  | refNum,: | IN: The STE refNum
  | engineRefNum,: | IN: The STE engine refNum

Return values:

  | - |

STEErr STEClose | ( | UInt16 | refNum | ) |

Standard library close routine. Library should always be unloaded with SysLibRemove() after STEClose() is called. See note at top of file.

Parameters:

  | refNum,: | IN: Library reference number

Return values:

  | STEErr | Error Code or zero if no error occurs

void STECopySelectionToClipboard | ( | UInt16 | refNum,
|  | UInt16 | engineRefNum |
| ) |  |  |

This routine copies the selected text to the system's clipboard.

Parameters:

  | refNum,: | IN: The STE refNum
  | engineRefNum,: | IN: The STE engine refNum

Return values:

  | - |

STEErr STEGetAPIVersion | ( | UInt16 | refNum,
|  | UInt32 * | majVerP,
|  | UInt32 * | minVerP |
| ) |  |  |

Get Library API Version number.

Parameters:

  | refNum,: | IN: Library reference number
  | majVerP,: | OUT: Major version number
  | minVerP,: | OUT: Minor version number

Return values:

  | STEErr | Error Code or zero if no error occurs

void STEGetCurrentTextSelection | ( | UInt16 | refNum,
|  | UInt16 | engineRefNum,
|  | UInt16 * | messageNumber,
|  | UInt16 * | startLocation,
|  | UInt16 * | selectionLength |
| ) |  |  |

This routine will select the specified text selection. The display will be updated to show the selected text as highlighted.

Parameters:

  | refNum,: | IN: The STE refNum
  | engineRefNum,: | IN: The STE engine refNum
  | messageNumber,: | OUT: The record number of the start the selection
  | startLocation,: | OUT: The byte offset of the start the text selection
  | selectionLength,: | OUT: The number of bytes in the text selection

Return values:

  | - |

UInt32 STEGetFlags | ( | UInt16 | refNum,
|  | UInt16 | engineRefNum |
| ) |  |  |

This routine returns the current STE flags

Parameters:

  | refNum,: | IN: The STE refNum
  | engineRefNum,: | IN: The STE engine refNum

Return values:

  | UInt32 | The STE flags

void STEGetLastTapInfo | ( | UInt16 | refNum,
|  | UInt16 | engineRefNum,
|  | UInt16 * | messageNumber,
|  | UInt16 * | tapLocation |
| ) |  |  |

This routine returns the location of the last tap. If the user drags the stylus, it is not a tap.

Parameters:

  | refNum,: | IN: The STE refNum
  | engineRefNum,: | IN: The STE engine refNum
  | messageNumber,: | OUT: The record number of the text that was tapped
  | tapLocation,: | OUT: The number of bytes offset from the start of the text to the location tapped

Return values:

  | - |

UInt16 STEGetNumLines | ( | UInt16 | refNum,
|  | UInt16 | engineRefNum |
| ) |  |  |

This routine returns the number of lines in the STE.

Parameters:

  | refNum,: | IN: The STE refNum
  | engineRefNum,: | IN: The STE engine refNum

Return values:

  | UInt16 | Number of lines in the STE

UInt16 STEGetNumRecords | ( | UInt16 | refNum,
|  | UInt16 | engineRefNum |
| ) |  |  |

This routine returns the number of records in the STE.

Parameters:

  | refNum,: | IN: The STE refNum
  | engineRefNum,: | IN: The STE engine refNum

Return values:

  | UInt16 | Number of records in the STE

ParsedInfoList* STEGetParsedInformation | ( | UInt16 | refNum,
|  | Char * | textP,
|  | UInt16 | msgNumber,
|  | Boolean | replaceLineFeeds,
|  | UInt32 | flags |
| ) |  |  |

This routine will parse the text string for URLs, email addresses, and/or phone numbers.

This does NOT require the STE to be initialized.

Parameters:

  | refNum,: | IN: The STE refNum
  | textP,: | IN: The text string to parse
  | msgNumber,: | IN: The message number of this text string (Used internally by the STE)
  | replaceLineFeeds,: | IN: If true, any line feed will be replaced with a space, but a parsed item will be create that specifies a line feed to be at that location
  | flags,: | IN: The flags indicating what type of item to parse out

Return values:

  | ParsedInfoList* | A parsed info list that has each of the parsed items found in the text string.

UInt16 STEGetScroll | ( | UInt16 | refNum,
|  | UInt16 | engineRefNum |
| ) |  |  |

This routine returns the current scroll position of the STE's scroll bar.

Parameters:

  | refNum,: | IN: The STE refNum
  | engineRefNum,: | IN: The STE engine refNum

Return values:

  | UInt16 | The position of the scroll bar.

UInt16 STEGetScrollPct | ( | UInt16 | refNum,
|  | UInt16 | engineRefNum |
| ) |  |  |

This routine returns the current scroll position of the STE's scroll bar as a percentage of the entire scroll bar.

Parameters:

  | refNum,: | IN: The STE refNum
  | engineRefNum,: | IN: The STE engine refNum

Return values:

  | UInt16 | The position of the scroll bar in percentage.

Char* STEGetSelectedText | ( | UInt16 | refNum,
|  | UInt16 | engineRefNum |
| ) |  |  |

This routine returns a copy of the actual text that is currently selected.

Parameters:

  | refNum,: | IN: The STE refNum
  | engineRefNum,: | IN: The STE engine refNum

Return values:

  | Char* | Returns a copy of the current text selection. This must be freed by the caller.

Boolean STEHandleEvent | ( | UInt16 | refNum,
|  | UInt16 | engineRefNum,
|  | EventPtr | eventP |
| ) |  |  |

This routine should be called in the form's event handler. If there is no special handling of events, then this routine can be used to handle all the different events that can affect the STE.

Parameters:

  | refNum,: | IN: The STE refNum
  | engineRefNum,: | IN: The STE engine refNum
  | eventP,: | IN: A pointer to the event record.

Return values:

  | Boolean | True if handled, False if not handled

Boolean STEHandleKeyDownEvent | ( | UInt16 | refNum,
|  | UInt16 | engineRefNum,
|  | EventPtr | eventP |
| ) |  |  |

This routine handles only the keyDown event. This routine should be used if there is special handling of the events by the application before (or after) the STE handles the event.

Parameters:

  | refNum,: | IN: The STE refNum
  | engineRefNum,: | IN: The STE engine refNum
  | eventP,: | IN: A pointer to the event record.

Return values:

  | Boolean | True if handled, False if not handled

Boolean STEHandlePenDownEvent | ( | UInt16 | refNum,
|  | UInt16 | engineRefNum,
|  | EventPtr | eventP |
| ) |  |  |

This routine handles only the penDown event. This routine should be used if there is special handling of the events by the application before (or after) the STE handles the event.

Parameters:

  | refNum,: | IN: The STE refNum
  | engineRefNum,: | IN: The STE engine refNum
  | eventP,: | IN: A pointer to the event record.

Return values:

  | Boolean | True if handled, False if not handled

Boolean STEHandlePenMoveEvent | ( | UInt16 | refNum,
|  | UInt16 | engineRefNum,
|  | EventPtr | eventP |
| ) |  |  |

This routine handles only the penMove event. This routine should be used if there is special handling of the events by the application before (or after) the STE handles the event.

Parameters:

  | refNum,: | IN: The STE refNum
  | engineRefNum,: | IN: The STE engine refNum
  | eventP,: | IN: A pointer to the event record.

Return values:

  | Boolean | True if handled, False if not handled

Boolean STEHandlePenUpEvent | ( | UInt16 | refNum,
|  | UInt16 | engineRefNum,
|  | EventPtr | eventP |
| ) |  |  |

This routine handles only the penUp event. This routine should be used if there is special handling of the events by the application before (or after) the STE handles the event.

Parameters:

  | refNum,: | IN: The STE refNum
  | engineRefNum,: | IN: The STE engine refNum
  | eventP,: | IN: A pointer to the event record.

Return values:

  | Boolean | True if handled, False if not handled

Boolean STEHandleSclRepeatEvent | ( | UInt16 | refNum,
|  | UInt16 | engineRefNum,
|  | EventPtr | eventP |
| ) |  |  |

This routine handles only the sclRepeat event. This routine should be used if there is special handling of the events by the application before (or after) the STE handles the event.

Parameters:

  | refNum,: | IN: The STE refNum
  | engineRefNum,: | IN: The STE engine refNum
  | eventP,: | IN: A pointer to the event record.

Return values:

  | Boolean | True if handled, False if not handled

Boolean STEHasHotRectSelection | ( | UInt16 | refNum,
|  | UInt16 | engineRefNum |
| ) |  |  |

This routine checks if there is a current hot rect selection. A hot rect is a hyperlink that has been selected with the keyboard.

Parameters:

  | refNum,: | IN: The STE refNum
  | engineRefNum,: | IN: The STE engine refNum

Return values:

  | Boolean | True if there is a current hot rect selected

Boolean STEHasMessageSelection | ( | UInt16 | refNum,
|  | UInt16 | engineRefNum |
| ) |  |  |

This routine checks if there is a current message selected.

Parameters:

  | refNum,: | IN: The STE refNum
  | engineRefNum,: | IN: The STE engine refNum

Return values:

  | Boolean | True if there is a current message selected

Boolean STEHasTextSelection | ( | UInt16 | refNum,
|  | UInt16 | engineRefNum |
| ) |  |  |

This routine checks if there is any text currently selected.

Parameters:

  | refNum,: | IN: The STE refNum
  | engineRefNum,: | IN: The STE engine refNum

Return values:

  | Boolean | True if there is any text selected

STEErr STEInitializeEngine | ( | UInt16 | refNum,
|  | UInt16 * | engineRefNum,
|  | RectangleType * | listBounds,
|  | UInt16 | scrollBarID,
|  | UInt32 | flags,
|  | UInt8 | phoneNumberColor,
|  | UInt8 | urlColor,
|  | UInt8 | emailColor |
| ) |  |  |

Styled Text Engine initialization function Before most of the STE can be used, it must be initialized. This function will return an engineRefNum which is to be used in the STE functions that require the STE to be initialized.

There are some functions that do not require the STE to be initialized. They are noted below.

Parameters:

  | refNum,: | IN: The STE refNum
  | engineRefNum,: | OUT: The STE engine refNum to be used in subsequent calls to the STE
  | listBounds,: | IN: The bounds of the STE list that will be displayed
  | scrollBarID,: | IN: The ID of the scroll used by the STE list. If this is 0, the list will not scroll. If there is more text than can be displayed, an ellipsis will be appended to the end.
  | flags,: | IN: The flags for the STE
  | phoneNumberColor,: | IN: The color of the phone number hyperlinks
  | urlColor,: | IN: The color of the URL hyperlinks
  | emailColor,: | IN: The color of the email hyperlinks

Return values:

  | STEErr | Error Code or zero if no error occurs

STEErr STEOpen | ( | UInt16 | refNum | ) |

Standard library open routine. Library should always be loaded with SysLibLoad()(not SysLibFind()) before calling STEOpen(). See note at top of file.

Parameters:

  | refNum,: | IN: Library reference number

Return values:

  | STEErr | Error Code or zero if no error occurs

void STEQuickRender | ( | UInt16 | refNum,
|  | RectangleType * | listBounds,
|  | UInt32 | flags,
|  | UInt8 | phoneNumberColor,
|  | UInt8 | urlColor,
|  | UInt8 | emailColor,
|  | Char * | msgP |
| ) |  |  |

This routine will render the specified text as a "one shot deal". The text will not respond to any events, and hyperlinks do not work. This can be used to display rich text with graphics easily in your application.

This does NOT require the STE to be initialized.

Parameters:

  | refNum,: | IN: The STE refNum
  | listBounds,: | IN: The bounds of the STE list that will be displayed
  | flags,: | IN: The flags for the STE
  | phoneNumberColor,: | IN: The color of the phone number hyperlinks
  | urlColor,: | IN: The color of the URL hyperlinks
  | emailColor,: | IN: The color of the email hyperlinks
  | msgP,: | IN: The text to display

Return values:

  | - |

STEErr STEReinitializeEngine | ( | UInt16 | refNum,
|  | UInt16 | engineRefNum |
| ) |  |  |

Initializes the STE to the initial state right after initializing it. This frees up any text that has been entered into the STE.

Parameters:

  | refNum,: | IN: The STE refNum
  | engineRefNum,: | IN: The STE engine refNum

Return values:

  | STEErr | Error Code or zero if no error occurs

void STERemoveLastRecordFromEngine | ( | UInt16 | refNum,
|  | UInt16 | engineRefNum |
| ) |  |  |

Removes the last text that was appended to the engine. You must call STERenderList to update the display after removing the text.

Parameters:

  | refNum,: | IN: The STE refNum
  | engineRefNum,: | IN: The STE engine refNum

Return values:

  | - |

void STERenderList | ( | UInt16 | refNum,
|  | UInt16 | engineRefNum |
| ) |  |  |

Renders the text that is currently in the STE.

Parameters:

  | refNum,: | IN: The STE refNum
  | engineRefNum,: | IN: The STE engine refNum

Return values:

  | - |

void STERerenderList | ( | UInt16 | refNum,
|  | UInt16 | engineRefNum |
| ) |  |  |

Rerenders the text that is currently in the STE. This routine should be used if a change is made that can change the formatting (i.e. font size).

Parameters:

  | refNum,: | IN: The STE refNum
  | engineRefNum,: | IN: The STE engine refNum

Return values:

  | - |

STEErr STEResetEngine | ( | UInt16 | refNum,
|  | UInt16 | engineRefNum |
| ) |  |  |

Frees up the STE engine refNum. For each STEInitializeEngine, there must be a corresponding STEResetEngine.

Parameters:

  | refNum,: | IN: The STE refNum
  | engineRefNum,: | IN: The STE engine refNum

Return values:

  | STEErr | Error Code or zero if no error occurs

UInt16 STESetCurrentTextSelection | ( | UInt16 | refNum,
|  | UInt16 | engineRefNum,
|  | UInt16 | messageNumber,
|  | UInt32 | startLocation,
|  | UInt32 | selectionLength |
| ) |  |  |

This routine will select the specified text selection. The display will be updated to show the selected text as highlighted.

Parameters:

  | refNum,: | IN: The STE refNum
  | engineRefNum,: | IN: The STE engine refNum
  | messageNumber,: | IN: The record number to start the selection
  | startLocation,: | IN: The byte offset to start the text selection
  | selectionLength,: | IN: The number of bytes in the text selection

Return values:

  | UInt16 | Returns the line number of the topmost line of the selection

void STESetCustomHyperlinkCallback | ( | UInt16 | refNum,
|  | UInt16 | engineRefNum,
|  | STECallbackType | callback,
|  | Boolean | armCallback |
| ) |  |  |

This routine sets the procedure to call as a result of tapping a custom hyperlink

Parameters:

  | refNum,: | IN: The STE refNum
  | engineRefNum,: | IN: The STE engine refNum
  | callback,: | IN: The routine to call
  | armCallback,: | IN: True if the callback routine is ARM code, false if it is 68K code

Return values:

  | - |

void STESetFlags | ( | UInt16 | refNum,
|  | UInt16 | engineRefNum,
|  | UInt32 | flagsToSet,
|  | UInt32 | flagsToClear |
| ) |  |  |

This routine sets the STE flags

Parameters:

  | refNum,: | IN: The STE refNum
  | engineRefNum,: | IN: The STE engine refNum
  | flagsToSet,: | IN: Bitmap representing the flags to set
  | flagsToClear,: | IN: Bitmap representing the flags to clear

Return values:

  | - |

void STESetScroll | ( | UInt16 | refNum,
|  | UInt16 | engineRefNum,
|  | UInt16 | scrollValue |
| ) |  |  |

This routine sets the current scroll position of the STE's scroll bar.

Parameters:

  | refNum,: | IN: The STE refNum
  | engineRefNum,: | IN: The STE engine refNum
  | scrollValue,: | IN: The position to set the scroll bar

Return values:

  | - |

void STESetScrollPct | ( | UInt16 | refNum,
|  | UInt16 | engineRefNum,
|  | UInt16 | scrollPct |
| ) |  |  |

This routine sets the current scroll position percentage of the STE's scroll bar.

Parameters:

  | refNum,: | IN: The STE refNum
  | engineRefNum,: | IN: The STE engine refNum
  | scrollPct,: | IN: The position to set the scroll bar in percentage

Return values:

  | - |

void STESetScrollToRecordNum | ( | UInt16 | refNum,
|  | UInt16 | engineRefNum,
|  | UInt16 | recordNum |
| ) |  |  |

This routine sets the current scroll bar position so that the specified record appears at the top of the list.

Parameters:

  | refNum,: | IN: The STE refNum
  | engineRefNum,: | IN: The STE engine refNum
  | recordNum,: | IN: The record number to display at the top of the list.

Return values:

  | - |

Top | Palm Developer Network © 2004-2008, Palm, Inc. All rights reserved. Generated on Fri Jun 13 10:08:04 2008 for Palm API Guide