(Online version only)
|
API Guide Home (Online version only) |
|
00001 /****************************************************************************** 00002 * Copyright (c) 2004 palmOne, Inc. or its subsidiaries. 00003 * All rights reserved. 00004 *****************************************************************************/ 00005 /** 00006 * @defgroup STE Smart Text Engine Library 00007 * 00008 * @{ 00009 * @} 00010 */ 00011 00012 /** 00013 * 00014 * @file SmartTextEngine.h 00015 * @brief Public 68K include file for Smart Text Engine shared library. 00016 * 00017 * The Smart Text Engine (STE) Library can be used to enable hyperlink 00018 * in your application and display icon as defined in the Resource Header file. 00019 * 00020 * It will enable user to tap on: 00021 * - Phone number to dial using the phone application 00022 * - URL to browse 00023 * - Email to send an email by launching the default email application 00024 * 00025 * The calling application should always load this library with 00026 * SysLibLoad() before use, even if it is already open by another 00027 * application(ie, SysLibFind() returns a valid refnum). When 00028 * the application is done with the library, it should be 00029 * unloaded with SysLibRemove(). We do this because there is 00030 * no good way to synchronize loading and unloading of libraries 00031 * among multiple applications. It also greatly simplifies internal 00032 * synchronization. 00033 * 00034 * @code 00035 * Err LoadSmartTextEngine(UInt16* refNumP, Boolean* libLoadedP) 00036 * { 00037 * Err error = 0; 00038 * 00039 * // Routine is pointless without this parameter 00040 * if (!refNumP) 00041 * return memErrInvalidParam; 00042 * 00043 * // always load the library, so we have our own instance of the engine 00044 * error = SysLibLoad(sysFileTLibrary, hsFileCSmartTextEngine, refNumP); 00045 * if (error) 00046 * return error; 00047 * *libLoadedP = true; 00048 * 00049 * return error; 00050 * } 00051 * @endcode 00052 */ 00053 00054 #ifndef __SMARTTEXTENGINE68K_H__ 00055 #define __SMARTTEXTENGINE68K_H__ 00056 00057 #include <PalmTypes.h> 00058 #include <LibTraps.h> 00059 00060 #include "SmartTextEngineTraps.h" 00061 #include "SmartTextEngineDef.h" 00062 #include "SmartTextEngineErrors.h" 00063 00064 00065 #ifdef __cplusplus 00066 extern "C" { 00067 #endif 00068 00069 00070 /// Standard library open routine. 00071 /// Library should always be loaded with SysLibLoad()(not SysLibFind()) 00072 /// before calling STEOpen(). See note at top of file. 00073 /// 00074 /// @param refNum: IN: Library reference number 00075 /// @retval STEErr Error Code or zero if no error occurs 00076 extern STEErr STEOpen(UInt16 refNum) 00077 SYS_TRAP(sysLibTrapOpen); 00078 00079 /// Standard library close routine. 00080 /// Library should always be unloaded with SysLibRemove() after 00081 /// STEClose() is called. See note at top of file. 00082 /// 00083 /// @param refNum: IN: Library reference number 00084 /// @retval STEErr Error Code or zero if no error occurs 00085 extern STEErr STEClose(UInt16 refNum) 00086 SYS_TRAP(sysLibTrapClose); 00087 00088 00089 /// Get Library API Version number. 00090 /// 00091 /// @param refNum: IN: Library reference number 00092 /// @param majVerP: OUT: Major version number 00093 /// @param minVerP: OUT: Minor version number 00094 /// @retval STEErr Error Code or zero if no error occurs 00095 extern STEErr STEGetAPIVersion(UInt16 refNum, UInt32* majVerP, UInt32* minVerP) 00096 SYS_TRAP(STETrapGetAPIVersion); 00097 00098 /// Styled Text Engine initialization function 00099 /// Before most of the STE can be used, it must be initialized. This function will return 00100 /// an engineRefNum which is to be used in the STE functions that require the STE 00101 /// to be initialized. 00102 /// 00103 /// There are some functions that do not require the STE to be initialized. They are noted below. 00104 /// 00105 /// @param refNum: IN: The STE refNum 00106 /// @param engineRefNum: OUT: The STE engine refNum to be used in subsequent calls to the STE 00107 /// @param listBounds: IN: The bounds of the STE list that will be displayed 00108 /// @param scrollBarID: IN: The ID of the scroll used by the STE list. If this is 0, the list will not 00109 /// scroll. If there is more text than can be displayed, an ellipsis will be 00110 /// appended to the end. 00111 /// @param flags: IN: The flags for the STE 00112 /// @param phoneNumberColor: IN: The color of the phone number hyperlinks 00113 /// @param urlColor: IN: The color of the URL hyperlinks 00114 /// @param emailColor: IN: The color of the email hyperlinks 00115 /// @retval STEErr Error Code or zero if no error occurs 00116 extern STEErr STEInitializeEngine(UInt16 refNum, UInt16* engineRefNum, RectangleType* listBounds, UInt16 scrollBarID, UInt32 flags, 00117 UInt8 phoneNumberColor, UInt8 urlColor, UInt8 emailColor) 00118 SYS_TRAP(STETrapInitializeEngine); 00119 00120 ///Frees up the STE engine refNum. For each STEInitializeEngine, there must be a corresponding 00121 ///STEResetEngine. 00122 /// 00123 ///@param refNum: IN: The STE refNum 00124 ///@param engineRefNum: IN: The STE engine refNum 00125 ///@retval STEErr Error Code or zero if no error occurs 00126 extern STEErr STEResetEngine(UInt16 refNum, UInt16 engineRefNum) 00127 SYS_TRAP(STETrapResetEngine); 00128 00129 ///Initializes the STE to the initial state right after initializing it. This frees up any text that 00130 ///has been entered into the STE. 00131 /// 00132 ///@param refNum: IN: The STE refNum 00133 ///@param engineRefNum: IN: The STE engine refNum 00134 ///@retval STEErr Error Code or zero if no error occurs 00135 extern STEErr STEReinitializeEngine(UInt16 refNum, UInt16 engineRefNum) 00136 SYS_TRAP(STETrapReinitializeEngine); 00137 00138 ///Function that is used to add text to the STE. Each text string that is appended 00139 ///is called a record. Record numbers are 1 based, meaning the first record is record 1. 00140 /// 00141 ///@param refNum: IN: The STE refNum 00142 ///@param engineRefNum: IN: The STE engine refNum 00143 ///@param textP: IN: The text to append to the STE, including any STE delimiters 00144 ///@param renderImmediate: IN: If true, the text will be displayed immediately. If false, it 00145 /// will not be displayed until STERenderList is called. 00146 ///@retval - 00147 extern void STEAppendTextToEngine(UInt16 refNum, UInt16 engineRefNum, Char* textP, Boolean renderImmediate) 00148 SYS_TRAP(STETrapAppendTextToEngine); 00149 00150 ///Removes the last text that was appended to the engine. 00151 ///You must call STERenderList to update the display after removing the text. 00152 /// 00153 ///@param refNum: IN: The STE refNum 00154 ///@param engineRefNum: IN: The STE engine refNum 00155 ///@retval - 00156 extern void STERemoveLastRecordFromEngine(UInt16 refNum, UInt16 engineRefNum) 00157 SYS_TRAP(STETrapRemoveLastRecordFromEngine); 00158 00159 ///Renders the text that is currently in the STE. 00160 /// 00161 ///@param refNum: IN: The STE refNum 00162 ///@param engineRefNum: IN: The STE engine refNum 00163 ///@retval - 00164 extern void STERenderList(UInt16 refNum, UInt16 engineRefNum) 00165 SYS_TRAP(STETrapRenderList); 00166 00167 ///Rerenders the text that is currently in the STE. This routine should be used if a change is made 00168 ///that can change the formatting (i.e. font size). 00169 /// 00170 ///@param refNum: IN: The STE refNum 00171 ///@param engineRefNum: IN: The STE engine refNum 00172 ///@retval - 00173 extern void STERerenderList(UInt16 refNum, UInt16 engineRefNum) 00174 SYS_TRAP(STETrapRerenderList); 00175 00176 00177 ///This routine should be called in the form's event handler. If there is no special handling of 00178 ///events, then this routine can be used to handle all the different events that can affect the STE. 00179 /// 00180 ///@param refNum: IN: The STE refNum 00181 ///@param engineRefNum: IN: The STE engine refNum 00182 ///@param eventP: IN: A pointer to the event record. 00183 ///@retval Boolean True if handled, False if not handled 00184 extern Boolean STEHandleEvent(UInt16 refNum, UInt16 engineRefNum, EventPtr eventP) 00185 SYS_TRAP(STETrapHandleEvent); 00186 00187 ///This routine handles only the sclRepeat event. This routine should be used if there is special 00188 ///handling of the events by the application before (or after) the STE handles the event. 00189 /// 00190 ///@param refNum: IN: The STE refNum 00191 ///@param engineRefNum: IN: The STE engine refNum 00192 ///@param eventP: IN: A pointer to the event record. 00193 ///@retval Boolean True if handled, False if not handled 00194 extern Boolean STEHandleSclRepeatEvent(UInt16 refNum, UInt16 engineRefNum, EventPtr eventP) 00195 SYS_TRAP(STETrapHandleSclRepeatEvent); 00196 00197 ///This routine handles only the penDown event. This routine should be used if there is special 00198 ///handling of the events by the application before (or after) the STE handles the event. 00199 /// 00200 ///@param refNum: IN: The STE refNum 00201 ///@param engineRefNum: IN: The STE engine refNum 00202 ///@param eventP: IN: A pointer to the event record. 00203 ///@retval Boolean True if handled, False if not handled 00204 extern Boolean STEHandlePenDownEvent(UInt16 refNum, UInt16 engineRefNum, EventPtr eventP) 00205 SYS_TRAP(STETrapHandlePenDownEvent); 00206 00207 ///This routine handles only the penMove event. This routine should be used if there is special 00208 ///handling of the events by the application before (or after) the STE handles the event. 00209 /// 00210 ///@param refNum: IN: The STE refNum 00211 ///@param engineRefNum: IN: The STE engine refNum 00212 ///@param eventP: IN: A pointer to the event record. 00213 ///@retval Boolean True if handled, False if not handled 00214 extern Boolean STEHandlePenMoveEvent(UInt16 refNum, UInt16 engineRefNum, EventPtr eventP) 00215 SYS_TRAP(STETrapHandlePenMoveEvent); 00216 00217 ///This routine handles only the penUp event. This routine should be used if there is special 00218 ///handling of the events by the application before (or after) the STE handles the event. 00219 /// 00220 ///@param refNum: IN: The STE refNum 00221 ///@param engineRefNum: IN: The STE engine refNum 00222 ///@param eventP: IN: A pointer to the event record. 00223 ///@retval Boolean True if handled, False if not handled 00224 extern Boolean STEHandlePenUpEvent(UInt16 refNum, UInt16 engineRefNum, EventPtr eventP) 00225 SYS_TRAP(STETrapHandlePenUpEvent); 00226 00227 ///This routine handles only the keyDown event. This routine should be used if there is special 00228 ///handling of the events by the application before (or after) the STE handles the event. 00229 /// 00230 ///@param refNum: IN: The STE refNum 00231 ///@param engineRefNum: IN: The STE engine refNum 00232 ///@param eventP: IN: A pointer to the event record. 00233 ///@retval Boolean True if handled, False if not handled 00234 extern Boolean STEHandleKeyDownEvent(UInt16 refNum, UInt16 engineRefNum, EventPtr eventP) 00235 SYS_TRAP(STETrapHandleKeyDownEvent); 00236 00237 ///This routine returns the current scroll position of the STE's scroll bar. 00238 /// 00239 ///@param refNum: IN: The STE refNum 00240 ///@param engineRefNum: IN: The STE engine refNum 00241 ///@retval UInt16 The position of the scroll bar. 00242 extern UInt16 STEGetScroll(UInt16 refNum, UInt16 engineRefNum) 00243 SYS_TRAP(STETrapGetScroll); 00244 00245 ///This routine sets the current scroll position of the STE's scroll bar. 00246 /// 00247 ///@param refNum: IN: The STE refNum 00248 ///@param engineRefNum: IN: The STE engine refNum 00249 ///@param scrollValue: IN: The position to set the scroll bar 00250 ///@retval - 00251 extern void STESetScroll(UInt16 refNum, UInt16 engineRefNum, UInt16 scrollValue) 00252 SYS_TRAP(STETrapSetScroll); 00253 00254 ///This routine returns the current scroll position of the STE's scroll bar as a percentage 00255 ///of the entire scroll bar. 00256 /// 00257 ///@param refNum: IN: The STE refNum 00258 ///@param engineRefNum: IN: The STE engine refNum 00259 ///@retval UInt16 The position of the scroll bar in percentage. 00260 extern UInt16 STEGetScrollPct(UInt16 refNum, UInt16 engineRefNum) 00261 SYS_TRAP(STETrapGetScrollPct); 00262 00263 ///This routine sets the current scroll position percentage of the STE's scroll bar. 00264 /// 00265 ///@param refNum: IN: The STE refNum 00266 ///@param engineRefNum: IN: The STE engine refNum 00267 ///@param scrollPct: IN: The position to set the scroll bar in percentage 00268 ///@retval - 00269 extern void STESetScrollPct(UInt16 refNum, UInt16 engineRefNum, UInt16 scrollPct) 00270 SYS_TRAP(STETrapSetScrollPct); 00271 00272 ///This routine sets the current scroll bar position so that the specified record 00273 ///appears at the top of the list. 00274 /// 00275 ///@param refNum: IN: The STE refNum 00276 ///@param engineRefNum: IN: The STE engine refNum 00277 ///@param recordNum: IN: The record number to display at the top of the list. 00278 ///@retval - 00279 extern void STESetScrollToRecordNum(UInt16 refNum, UInt16 engineRefNum, UInt16 recordNum) 00280 SYS_TRAP(STETrapSetScrollToRecordNum); 00281 00282 ///This routine sets the STE flags 00283 /// 00284 ///@param refNum: IN: The STE refNum 00285 ///@param engineRefNum: IN: The STE engine refNum 00286 ///@param flagsToSet: IN: Bitmap representing the flags to set 00287 ///@param flagsToClear: IN: Bitmap representing the flags to clear 00288 ///@retval - 00289 extern void STESetFlags(UInt16 refNum, UInt16 engineRefNum, UInt32 flagsToSet, UInt32 flagsToClear) 00290 SYS_TRAP(STETrapSetFlags); 00291 00292 ///This routine returns the current STE flags 00293 /// 00294 ///@param refNum: IN: The STE refNum 00295 ///@param engineRefNum: IN: The STE engine refNum 00296 ///@retval UInt32 The STE flags 00297 extern UInt32 STEGetFlags(UInt16 refNum, UInt16 engineRefNum) 00298 SYS_TRAP(STETrapGetFlags); 00299 00300 ///This routine returns the number of lines in the STE. 00301 /// 00302 ///@param refNum: IN: The STE refNum 00303 ///@param engineRefNum: IN: The STE engine refNum 00304 ///@retval UInt16 Number of lines in the STE 00305 extern UInt16 STEGetNumLines(UInt16 refNum, UInt16 engineRefNum) 00306 SYS_TRAP(STETrapGetNumLines); 00307 00308 ///This routine returns the number of records in the STE. 00309 /// 00310 ///@param refNum: IN: The STE refNum 00311 ///@param engineRefNum: IN: The STE engine refNum 00312 ///@retval UInt16 Number of records in the STE 00313 extern UInt16 STEGetNumRecords(UInt16 refNum, UInt16 engineRefNum) 00314 SYS_TRAP(STETrapGetNumRecords); 00315 00316 ///This routine checks if there is a current hot rect selection. A hot rect 00317 ///is a hyperlink that has been selected with the keyboard. 00318 /// 00319 ///@param refNum: IN: The STE refNum 00320 ///@param engineRefNum: IN: The STE engine refNum 00321 ///@retval Boolean True if there is a current hot rect selected 00322 extern Boolean STEHasHotRectSelection(UInt16 refNum, UInt16 engineRefNum) 00323 SYS_TRAP(STETrapHasHotRectSelection); 00324 00325 ///This routine checks if there is a current message selected. 00326 /// 00327 ///@param refNum: IN: The STE refNum 00328 ///@param engineRefNum: IN: The STE engine refNum 00329 ///@retval Boolean True if there is a current message selected 00330 extern Boolean STEHasMessageSelection(UInt16 refNum, UInt16 engineRefNum) 00331 SYS_TRAP(STETrapHasMessageSelection); 00332 00333 ///This routine checks if there is any text currently selected. 00334 /// 00335 ///@param refNum: IN: The STE refNum 00336 ///@param engineRefNum: IN: The STE engine refNum 00337 ///@retval Boolean True if there is any text selected 00338 extern Boolean STEHasTextSelection(UInt16 refNum, UInt16 engineRefNum) 00339 SYS_TRAP(STETrapHasTextSelection); 00340 00341 ///This routine clears any currently selected text or hot rect. 00342 /// 00343 ///@param refNum: IN: The STE refNum 00344 ///@param engineRefNum: IN: The STE engine refNum 00345 ///@retval - 00346 extern void STEClearCurrentSelection(UInt16 refNum, UInt16 engineRefNum) 00347 SYS_TRAP(STETrapClearCurrentSelection); 00348 00349 ///This routine will select the specified text selection. The display will be updated 00350 ///to show the selected text as highlighted. 00351 /// 00352 ///@param refNum: IN: The STE refNum 00353 ///@param engineRefNum: IN: The STE engine refNum 00354 ///@param messageNumber: IN: The record number to start the selection 00355 ///@param startLocation: IN: The byte offset to start the text selection 00356 ///@param selectionLength: IN: The number of bytes in the text selection 00357 ///@retval UInt16 Returns the line number of the topmost line of the selection 00358 extern UInt16 STESetCurrentTextSelection(UInt16 refNum, UInt16 engineRefNum, UInt16 messageNumber, UInt32 startLocation, UInt32 selectionLength) 00359 SYS_TRAP(STETrapSetCurrentTextSelection); 00360 00361 ///This routine will select the specified text selection. The display will be updated 00362 ///to show the selected text as highlighted. 00363 /// 00364 ///@param refNum: IN: The STE refNum 00365 ///@param engineRefNum: IN: The STE engine refNum 00366 ///@param messageNumber: OUT: The record number of the start the selection 00367 ///@param startLocation: OUT: The byte offset of the start the text selection 00368 ///@param selectionLength: OUT: The number of bytes in the text selection 00369 ///@retval - 00370 extern void STEGetCurrentTextSelection(UInt16 refNum, UInt16 engineRefNum, UInt16* messageNumber, UInt16* startLocation, UInt16* selectionLength) 00371 SYS_TRAP(STETrapGetCurrentTextSelection); 00372 00373 ///This routine returns a copy of the actual text that is currently selected. 00374 /// 00375 ///@param refNum: IN: The STE refNum 00376 ///@param engineRefNum: IN: The STE engine refNum 00377 ///@retval Char* Returns a copy of the current text selection. This must be freed by the caller. 00378 extern Char* STEGetSelectedText(UInt16 refNum, UInt16 engineRefNum) 00379 SYS_TRAP(STETrapGetSelectedText); 00380 00381 ///This routine copies the selected text to the system's clipboard. 00382 /// 00383 ///@param refNum: IN: The STE refNum 00384 ///@param engineRefNum: IN: The STE engine refNum 00385 ///@retval - 00386 extern void STECopySelectionToClipboard(UInt16 refNum, UInt16 engineRefNum) 00387 SYS_TRAP(STETrapCopySelectionToClipboard); 00388 00389 ///This routine returns the location of the last tap. If the user drags the stylus, it is not a tap. 00390 /// 00391 ///@param refNum: IN: The STE refNum 00392 ///@param engineRefNum: IN: The STE engine refNum 00393 ///@param messageNumber: OUT: The record number of the text that was tapped 00394 ///@param tapLocation: OUT: The number of bytes offset from the start of the text to the location tapped 00395 ///@retval - 00396 extern void STEGetLastTapInfo(UInt16 refNum, UInt16 engineRefNum, UInt16* messageNumber, UInt16* tapLocation) 00397 SYS_TRAP(STETrapGetLastTapInfo); 00398 00399 ///This routine sets the procedure to call as a result of tapping a custom hyperlink 00400 /// 00401 ///@param refNum: IN: The STE refNum 00402 ///@param engineRefNum: IN: The STE engine refNum 00403 ///@param callback: IN: The routine to call 00404 ///@param armCallback: IN: True if the callback routine is ARM code, false if it is 68K code 00405 ///@retval - 00406 extern void STESetCustomHyperlinkCallback(UInt16 refNum, UInt16 engineRefNum, STECallbackType callback, Boolean armCallback) 00407 SYS_TRAP(STETrapSetCustomHyperlinkCallback); 00408 00409 ///This routine will render the specified text as a "one shot deal". The text will 00410 ///not respond to any events, and hyperlinks do not work. This can be used to display 00411 ///rich text with graphics easily in your application. 00412 /// 00413 ///This does NOT require the STE to be initialized. 00414 /// 00415 ///@param refNum: IN: The STE refNum 00416 ///@param listBounds: IN: The bounds of the STE list that will be displayed 00417 ///@param flags: IN: The flags for the STE 00418 ///@param phoneNumberColor: IN: The color of the phone number hyperlinks 00419 ///@param urlColor: IN: The color of the URL hyperlinks 00420 ///@param emailColor: IN: The color of the email hyperlinks 00421 ///@param msgP: IN: The text to display 00422 ///@retval - 00423 extern void STEQuickRender(UInt16 refNum, RectangleType* listBounds, UInt32 flags, 00424 UInt8 phoneNumberColor, UInt8 urlColor, UInt8 emailColor, Char* msgP) 00425 SYS_TRAP(STETrapQuickRender); 00426 00427 ///This routine will parse the text string for URLs, email addresses, and/or phone numbers. 00428 /// 00429 ///This does NOT require the STE to be initialized. 00430 /// 00431 ///@param refNum: IN: The STE refNum 00432 ///@param textP: IN: The text string to parse 00433 ///@param msgNumber: IN: The message number of this text string (Used internally by the STE) 00434 ///@param replaceLineFeeds: IN: If true, any line feed will be replaced with a space, but a parsed item will be create 00435 /// that specifies a line feed to be at that location 00436 ///@param flags: IN: The flags indicating what type of item to parse out 00437 ///@retval ParsedInfoList* A parsed info list that has each of the parsed items found in the text string. 00438 extern ParsedInfoList* STEGetParsedInformation(UInt16 refNum, Char* textP, UInt16 msgNumber, Boolean replaceLineFeeds, UInt32 flags) 00439 SYS_TRAP(STETrapGetParsedInformation); 00440 00441 00442 ///This routine append a ParsedInfoList to another ParsedInfoList. 00443 /// 00444 ///This does NOT require the STE to be initialized. 00445 ///This is used internally by the STE. You probably will not use this function. 00446 /// 00447 ///@param refNum: IN: The STE refNum 00448 ///@param destParsedInfoH: IN: A handle to the destination parsed info list 00449 ///@param sourceParsedInfoP: IN: The source parsed info list. 00450 ///@retval - 00451 extern void STEAppendParsedInfo(UInt16 refNum, MemHandle destParsedInfoH, ParsedInfoList* sourceParsedInfoP) 00452 SYS_TRAP(STETrapAppendParsedInfo); 00453 00454 00455 00456 #ifdef __cplusplus 00457 } 00458 #endif 00459 00460 00461 00462 00463 #endif //__SMARTTEXTENGINE68K_H__
| Top | Palm Developer Network © 2004-2008, Palm, Inc. All rights reserved. Generated on Fri Jun 13 10:06:55 2008 for Palm API Guide |