API Guide Home
(Online version only)

Header Files » Incs » 68k » libraries » smarttextengine

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:

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

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