API Guide Home (Online version only) |

# HtmlLib68K.h

Go to the documentation of this file.

    00001 /*
    00002     HtmlLib68K.h
    00003     Copyright(c) 1996-2002 ACCESS CO., LTD.
    00004     All rights are reserved by ACCESS CO., LTD., whether the whole or
    00005     part of the source code including any modifications.
    00006 */
    00007
    00008  /** @defgroup HtmlLib HTML Library
    00009  * The HTML Library helps applications render data. Please note that there is a limit of 64K of text data for a single content data object, so it is recommended that you do appropriate checks when adding text data for rendering, especially when adding text data repeatedly.
    00010  * Additionally, the caller application is required to provide a set of form widget creation functions to the Html Library for dynamic UI creation. Please see the HtmlLibSetFormWidgetProc routine for details.
    00011  *
    00012  * @note It is important to be aware that this library modifies the active form pointer, so make sure to NOT cache the form pointer, but re-get it before use.
    00013  *
    00014  * @{
    00015  * @}
    00016  */
    00017  /**
    00018  @ingroup HtmlLib
    00019  */
    00020
    00021 /**
    00022 *
    00023 * @file HtmlLib68K.h
    00024 *
    00025 * @brief Public 68K include file for HTML shared library.
    00026 *
    00027 */
    00028
    00029 #ifndef HTMLLIb68K_H__
    00030 #define HTMLLIb68K_H__
    00031
    00032 #include <PalmTypes.h>
    00033 #include <LibTraps.h>
    00034
    00035 #include <HtmlLibTrap.h>
    00036
    00037 #include <ErrorBase.h>
    00038
    00039 #define htmlErrorClass  (appErrorClass)
    00040
    00041 /**
    00042  * @name HtmlLib error codes
    00043  *
    00044  */
    00045  /*@{*/
    00046 /************************************************************
    00047  * HtmlLib error codes
    00048  *************************************************************/
    00049 #define htmlErrInUse            (htmlErrorClass | 1)
    00050 #define htmlErrOutOfMemory      (htmlErrorClass | 2)
    00051 #define htmlErrInvalidParam     (htmlErrorClass | 3)
    00052 #define htmlErrNotFound         (htmlErrorClass | 4)
    00053 #define htmlErrNotInitialized   (htmlErrorClass | 5)
    00054 #define htmlErrCantOpen         (htmlErrorClass | 6)
    00055 /*@}*/
    00056
    00057 #define htmlLibProgressEvent    (0x7000)
    00058
    00059 /************************************************************
    00060  * HtmlLib l
    00061  *************************************************************/
    00062
    00063 #define HtmlLibID       'AsHL'
    00064 #define HtmlLibDBType   'libr'
    00065 #define HtmlLibName     "HtmlLibrary"
    00066
    00067
    00068 /*
    00069  * Typedef
    00070  */
    00071
    00072 /**
    00073  * @name Typedef
    00074  */
    00075 /*@{*/
    00076 typedef UInt8 HtmlDisplayMode;
    00077 typedef UInt16 HtmlProgressStatus;
    00078 typedef UInt32 HtmlSubmitFormMethod;
    00079 typedef Int8 HtmlScrollDirection;
    00080 typedef Int8 HtmlScrollbarMode;
    00081
    00082
    00083 /* HtmlFocusTargetType */
    00084 #define htmlTargetImage             0x01
    00085 #define htmlTargetEmbed             0x02
    00086 #define htmlTargetIFrame            0x03
    00087 #define htmlTargetElement           0x04
    00088 #define htmlTargetInputText         0x05
    00089 #define htmlTargetInputPassword     0x06
    00090 #define htmlTargetInputCheckbox     0x07
    00091 #define htmlTargetInputRadio        0x08
    00092 #define htmlTargetInputSubmit       0x09
    00093 #define htmlTargetInputReset        0x0a
    00094 #define htmlTargetInputFile         0x0b
    00095 #define htmlTargetInputButton       0x0c
    00096 #define htmlTargetInputTextarea     0x0d
    00097 #define htmlTargetInputSelect       0x0e
    00098
    00099 typedef UInt16 HtmlFocusTargetType;
    00100
    00101 /**
    00102  * @name Callback Functions
    00103  */
    00104 /*@{*/
    00105
    00106
    00107 /**
    00108  *Should be defined (to handle a link selection) and set as the function to be called when a link (url) is selected.
    00109  */
    00110 typedef void HtmlLibLinkSelCallback(MemHandle htmlLibH, Char *url, void *cbData);
    00111
    00112 /**
    00113  *Should be defined and set as the function to be called when it's necessary to determine if a string of numbers contains a phone number.
    00114  *
    00115  * Here, buffer contains the string of numbers that are being checked, and this is passed in by the library when the library calls this function. Length is the buffer's length, also passed in by the library. The last two arguments (patternStart and patternEnd) should get set in this callback function if the string of numbers passed in is determined to be a phone number (and thus the return value of the function is to be true). Now, patternStart is the place in the buffer that the phone number starts, and patternEnd is the place in the buffer that the pattern ends. For example, if the entire contents of the buffer passed in happened to be a phone number, then the start would be 0 and the end would be "length - 1", and the return value would be true. However, if what was passed in was not determined to be a phone number, then the return value of the callback function should be false, and the last two arguments do not need to be set.
    00116  */
    00117 typedef Boolean HtmlLibScanPhoneNumberCallback(MemHandle htmlLibH, Char *buffer, Int32 length, Int32 *patternStart, Int32 *patternEnd);
    00118
    00119 /**
    00120  *Should be defined and set as the function to be called when rendering a page requires additional content.
    00121  *
    00122  * HtmlLib calls this callback function with the appropriate arguments (where the url is the url of the additional content the library requires).
    00123  */
    00124 typedef void HtmlLibInclusionCallback(MemHandle htmlLibH, Char *url, void *cbData);
    00125
    00126 /**
    00127  * @note Forms are not supported; thus, use this at your own risk.
    00128  *
    00129  *Should be defined and set as the function to be called when a submit is activated.
    00130  *
    00131  * HtmlLib calls this callback function with the appropriate arguments. The following is an example (included in the sample code):
    00132  *
    00133  * @code
    00134  *
    00135  * void HtmlSubmitFormCallback(MemHandle htmlLibH, Char *url, HtmlSubmitFormMethod method, Char *query, void *cbData)
    00136  * {
    00137  *   FrmCustomAlert(SubmitFormAlert, url,
    00138  *      (method == htmlHttpMethodPost ? "Post" : "Get"), query);
    00139  * }
    00140  *
    00141  * @endcode
    00142  *
    00143  */
    00144 typedef void HtmlLibSubmitFormCallback(MemHandle htmlLibH, Char *url, HtmlSubmitFormMethod method, Char *query, void *cbData);
    00145
    00146 typedef Boolean NewControlProc(UInt16 id,
    00147     UInt16 style, const Char *textP,
    00148     Coord x, Coord y, Coord width, Coord height,
    00149     UInt16 font, UInt8 group, Boolean leftAnchor); /**< @see HtmlLibFormWidgetProc*/
    00150
    00151 typedef Err NewListProc(UInt16 id,
    00152                     Coord x, Coord y, Coord width, Coord height,
    00153                     UInt16 font, Int16 visibleItems, Int16 triggerId); /**< @see HtmlLibFormWidgetProc*/
    00154
    00155 typedef Boolean NewFieldProc(UInt16 id,
    00156     Coord x, Coord y, Coord width, Coord height,
    00157     UInt16 font, UInt32 maxChars, UInt16 editable, UInt16 underlined,
    00158     UInt16 singleLine, UInt16 dynamicSize, UInt16 justification,
    00159     UInt16 autoShift, UInt16 hasScrollBar, UInt16 numeric);  /**< @see HtmlLibFormWidgetProc*/
    00160
    00161 typedef void DeleteObjectProc(UInt16 index); /**< @see HtmlLibFormWidgetProc*/
    00162
    00163 /** @brief The following are necessary form widget creation/deletion routines that need to get set using HtmlLibSetFormWidgetProc. Please see sample code after looking at HtmlLibSetFormWidgetProc.
    00164 *
    00165 * @see HtmlLibSetFormWidgetProc
    00166 */
    00167 typedef struct {
    00168     NewControlProc *newControlProc;
    00169     NewListProc *newListProc;
    00170     NewFieldProc *newFieldProc;
    00171     DeleteObjectProc *deleteObjectProc;
    00172 } HtmlLibFormWidgetProc;
    00173 /*@}*/
    00174
    00175 /* HtmlLibFocusTargetInfo */
    00176 typedef struct {
    00177     HtmlFocusTargetType type;
    00178     RectangleType bounds; /* in window coordinate */
    00179     UInt16 formObjectID;  /* set only for form object */
    00180 } HtmlLibFocusTargetInfo;
    00181
    00182
    00183 /* HtmlDisplayMode */
    00184 /** @name HtmlDisplayMode */
    00185 /*@{*/
    00186 #define htmlHandheldDisplayMode 0x01
    00187 #define htmlFaithfulDisplayMode 0x02
    00188 /*@}*/
    00189
    00190
    00191 /* HtmlProgressStatus */
    00192 /** @name HtmlProgressStatus */
    00193 /*@{*/
    00194 #define htmlProgressDone        0x0001
    00195 #define htmlProgressBusy        0x0002
    00196 #define htmlProgressOutOfMemory 0x0003
    00197 #define htmlProgressError       0x0004
    00198 /*@}*/
    00199
    00200
    00201 /* HtmlSubmitFormMethod */
    00202 /** @name HtmlSubmitFormMethod */
    00203 /*@{*/
    00204 #define htmlHttpMethodGet   0x00000001
    00205 #define htmlHttpMethodPost  0x00000002
    00206 /*@}*/
    00207
    00208
    00209 /* HtmlDirections */
    00210 /** @name HtmlDirections */
    00211 /*@{*/
    00212 #define htmlDirLeft         0x01
    00213 #define htmlDirRight        0x02
    00214 #define htmlDirUp           0x03
    00215 #define htmlDirDown         0x04
    00216 /*@}*/
    00217
    00218
    00219 /* HtmlScrollMode */
    00220 /** @name HtmlScrollMode */
    00221 /*@{*/
    00222 #define htmlNormalScrollbarMode 0x01
    00223 #define htmlNoPageScrollbarMode 0x02
    00224 /*@}*/
    00225
    00226
    00227 /*@}*/
    00228 /*
    00229  * API
    00230  */
    00231
    00232 /** Standard library open routine.
    00233  *
    00234  * @param refun IN: the library reference number
    00235  *
    00236  * @return Error code.
    00237  */
    00238 Err HtmlLibOpen(UInt16 refnum)
    00239         SYS_TRAP(kHtmlLibTrapOpen);
    00240
    00241 /** Standard library close routine.
    00242  *
    00243  * @param refun IN: the library reference number
    00244  *
    00245  * @return Error code.
    00246  */
    00247 Err HtmlLibClose(UInt16 refnum)
    00248         SYS_TRAP(kHtmlLibTrapClose);
    00249
    00250 /** Standard library sleep routine.
    00251  *
    00252  * @param refun IN: the library reference number
    00253  *
    00254  * @return Error code.
    00255  */
    00256 Err HtmlLibSleep(UInt16 refnum)
    00257         SYS_TRAP(kHtmlLibTrapSleep);
    00258
    00259 /** Standard library wake routine.
    00260  *
    00261  * @param refun IN: the library reference number
    00262  *
    00263  * @return Error code.
    00264  */
    00265 Err HtmlLibWake(UInt16 refnum)
    00266         SYS_TRAP(kHtmlLibTrapWake);
    00267
    00268 /** Html Library initialization function.
    00269  * Initializes the library, after the library has been loaded.
    00270  *
    00271  * @param   refNum      IN: the library reference number
    00272  * @param   bounds      IN: the screen area the library will draw the rendered content (bounds within 160 x 160 grid)
    00273  * @param    errP       IN: error code if library fails to initialize. The error code can be one of
    00274  * (htmlErrInUse, htmlErrOutOfMemory, htmlErrInvalidParam, htmlErrInUse, htmlErrCantOpen)
    00275  *
    00276  * @return A memory handle to the HTML library context.
    00277  */
    00278 MemHandle HtmlLibInitialize(UInt16 refnum, RectangleType bounds, Err *errP)
    00279         SYS_TRAP(kHtmlLibTrapInitialize);
    00280
    00281 MemHandle HtmlLibInitializeWithHeapSize(UInt16 refnum, RectangleType bounds, Err *errP, UInt32 heapMinSize, UInt32 heapDesiredSize, UInt32 *heapActualSizeP)
    00282         SYS_TRAP(kHtmlLibTrapInitializeWithHeapSize);
    00283
    00284 /** Finalizes the library when you are done using it
    00285  * @note  If you need to use the library again after it has been finalized, you will need to re-initialize it.
    00286  *
    00287  * @param refNum  IN: the library reference number
    00288  * @param htmlLibH IN: the memory handle returned by HtmlLibInitialize
    00289  */
    00290 void HtmlLibFinalize(UInt16 refnum, MemHandle htmllibH)
    00291         SYS_TRAP(kHtmlLibTrapFinalize);
    00292
    00293 /** Resize the screen area.
    00294  *
    00295  * @param refNum IN: the library reference number
    00296  * @param htmlLibH IN: the memory handle returned by HtmlLibInitialize
    00297  * @param newBounds IN: the new bounds of the screen area (bounds within 160 x 160 grid)
    00298  *
    00299  * @return errNone if resize is successful, otherwise returns an error code (errInvalidParam)
    00300  */
    00301 void HtmlLibResizeScreen(UInt16 refnum, MemHandle htmlLibH, RectangleType newBounds)
    00302         SYS_TRAP(kHtmlLibTrapResizeScreen);
    00303
    00304 /** Sets the display mode (faithful rendering, which corresponds to Blazer's Wide Page Mode, or handheld wrapped, which corresponds to Blazer's Optimized Mode).
    00305  *
    00306  * @param refNum IN: the library reference number
    00307  * @param htmlLibH IN: the memory handle returned by HtmlLibInitialize
    00308  * @param mode IN: display mode (htmlFaithfulDisplayMode or htmlHandheldDisplayMode)
    00309  *
    00310  */
    00311 void HtmlLibSetDisplayMode(UInt16 refnum, MemHandle htmlLibH, HtmlDisplayMode mode)
    00312         SYS_TRAP(kHtmlLibTrapSetDisplayMode);
    00313
    00314 /** Specify the function that you want the library to call when a link is followed.
    00315  *
    00316  * @param refNum  IN: the library reference number
    00317  * @param htmlLibH  IN: the memory handle returned by HtmlLibInitialize
    00318  * @param callback IN: a pointer to the function you want called when a link is followed.
    00319  * @param cbData I/O: the library does nothing with this parameter except pass it on as one of the arguments to your callback function. To not take advantage of this feature, just pass in NULL.
    00320  *
    00321  * @note  The callback function should be in the following form:
    00322  *   void HtmlLinkSelCallback(MemHandle htmlLibH, Char *url, void *cbData);
    00323  * The library will call this function, supplying the appropriate arguments (where the url is the url of the link which was selected).
    00324  * @see HtmlLibLinkSelCallback
    00325  */
    00326 void HtmlLibSetLinkSelectionCallback(UInt16 refnum, MemHandle htmlLibH, HtmlLibLinkSelCallback *callback, void *cbData)
    00327         SYS_TRAP(kHtmlLibTrapSetLinkSelectionCallback);
    00328
    00329 /** Specify the function that you want the library to call to determine whether some string of numbers contains a phone number.
    00330  *
    00331  * @param refNum IN: the library reference number
    00332  * @param htmlLibH IN: the memory handle returned by HtmlLibInitialize
    00333  * @param callback IN: a pointer to the function that HtmlLib will call to determine whether a string of numbers is a phone number, and should be handled as such.
    00334  *
    00335  * @note  The callback function should be in the following form:
    00336  * Boolean HtmlLibScanPhoneNumberCallback(MemHandle htmlLibH, Char   *buffer, Int32 length, Int32 *patternStart, Int32 *patternEnd);
    00337  *
    00338  * @see HtmlLibScanPhoneNumberCallback
    00339  */
    00340 void HtmlLibSetScanPhoneNumberCallback(UInt16 refnum, MemHandle htmlLibH, HtmlLibScanPhoneNumberCallback *callback)
    00341         SYS_TRAP(kHtmlLibTrapSetScanPhoneNumberCallback);
    00342
    00343 /** Specify the function that you want the library to call when rendering a page requires additional content (an image that hasn't been added, an external style sheet, etc).
    00344  *
    00345  * @param refNum IN: the library reference number
    00346  * @param htmlLibH IN: the memory handle returned by HtmlLibInitialize
    00347  * @param callback IN: a pointer to the function you want called when rendering a page that requires additional content.
    00348  * @param cbData I/O: the library does nothing with this parameter except pass it on as one of the arguments to your callback function. To not take advantage of this feature, just pass in NULL.
    00349  *
    00350  * @note: The callback function should be in the following form:
    00351  * void HtmlLibInclusionCallback(MemHandle htmlLibH, Char *url, void *cbData);
    00352  *
    00353  * HtmlLib calls this callback function with the appropriate arguments (where the url is the url of the additional content the library requires).
    00354  *
    00355  * @see HtmlLibInclusionCallback
    00356  *
    00357  */
    00358 void HtmlLibSetInclusionCallback(UInt16 refnum, MemHandle htmlLibH, HtmlLibInclusionCallback *callback, void *cbData)
    00359         SYS_TRAP(kHtmlLibTrapSetInclusionCallback);
    00360
    00361 /** @note:  Forms are not supported; thus, use this at your own risk.
    00362  *
    00363  * This functions lets you specify the function that you want the library to call when a "submit" is activated.
    00364  *
    00365  * @param refNum IN: the library reference number
    00366  * @param htmlLibH IN: the memory handle returned by HtmlLibInitialize
    00367  * @param callback IN: a pointer to the function you want called when a "submit" is activated
    00368  * @param cbData I/O: the library does nothing with this parameter except pass it on as one of the arguments to your callback function. To not take advantage of this feature, just pass in NULL.
    00369  *
    00370  * @note  The callback function should be in the following form:
    00371  *
    00372  * HtmlLibSubmitFormCallback(MemHandle htmlLibH, Char *url, HtmlSubmitFormMethod method, Char *query, void *cbData);
    00373  *
    00374  * HtmlLib calls this callback function with the appropriate arguments.
    00375  *
    00376  * @see HtmlLibSubmitFormCallback
    00377  *
    00378  */
    00379 void HtmlLibSetSubmitFormCallback(UInt16 refnum, MemHandle htmlLibH, HtmlLibSubmitFormCallback *callback, void *cbData)
    00380         SYS_TRAP(kHtmlLibTrapSetSubmitFormCallback);
    00381
    00382 /** Applications should call this function to allow HTML library to process content and draw to screen.
    00383  * @note The Html Library will run only if you call this!
    00384  *
    00385  *@param refNum IN: the library reference number
    00386  *@param htmlLibH IN:  the memory handle returned by HtmlLibInitialize
    00387  *@param stayTime IN: maximum time (in milliseconds) for HTML library to do processing. (At least 1300 is recommend.)
    00388  *
    00389  *@return Status - htmlProgressDone, htmlProgressBusy, htmlProgressOutOfMemory, and other error codes.
    00390  */
    00391 UInt16 HtmlLibProgress(UInt16 refnum, MemHandle htmlLibH, Int32 stayTime)
    00392         SYS_TRAP(kHtmlLibTrapProgress);
    00393
    00394 /** Applications should call this function to notify HTML library of a UI event (any event that your application gets that the library should handle, such as a screen tap, or a key press). It is worth noting that you may create your own events and call this function for the library to handle it. By the same token, you can filter which events to pass to this function - you do not have to pass through every event.
    00395  *
    00396  *@param refNum IN: the library reference number
    00397  *@param htmlLibH IN: the memory handle returned by HtmlLibInitialize
    00398  *@param eventP IN: the event you would like the library to handle
    00399  *
    00400  *@return True if the library considers this event handled.
    00401  */
    00402 Boolean HtmlLibNotifyUIEvent(UInt16 refnum, MemHandle htmlLibH, EventType *eventP)
    00403         SYS_TRAP(kHtmlLibTrapNotifyUIEvent);
    00404
    00405 /** Applications should call this function to find a given text string on the page.  Page will automatically scroll to show search result.
    00406  *
    00407  *@param refNum IN: the library reference number
    00408  *@param htmlLibH IN: the memory handle returned by HtmlLibInitialize
    00409  *@param searchString IN: the given text string we are looking for on the page
    00410  *@param wrapSearch IN: true if you would like to wrap search
    00411  *
    00412  *@return Error code (errNone, htmlErrNotFound).
    00413  */
    00414 Err HtmlLibFindText(UInt16 refnum, MemHandle htmlLibH, Char *searchString, Boolean wrapSearch)
    00415         SYS_TRAP(kHtmlLibTrapFindText);
    00416
    00417
    00418 /** Applications should use this function to retrieve the current selected text.  Caller application must free the pointer returned in selectedText using MemPtrFree.
    00419  *
    00420  * @param refNum IN: the library reference number
    00421  * @param htmlLibH IN: the memory handle returned by HtmlLibInitialize
    00422  * @param selectedText IN: the selected text that we are retrieving
    00423  *
    00424  * @return This function returns false if no current selection, otherwise returns true.
    00425  */
    00426 Boolean HtmlLibGetTextSelection(UInt16 refnum, MemHandle htmlLibH, Char **selectedText)
    00427         SYS_TRAP(kHtmlLibTrapGetTextSelection);
    00428
    00429
    00430
    00431 /** This function clears the rendering screen.  It must be called before content object is destroyed.
    00432  *
    00433  *
    00434  * @param refNum IN: the library reference number
    00435  * @param htmlLibH IN: the memory handle returned by HtmlLibInitialize
    00436  */
    00437 void HtmlLibClearScreen(UInt16 refnum, MemHandle htmlLibH)
    00438         SYS_TRAP(kHtmlLibTrapClearScreen);
    00439
    00440
    00441
    00442 /** This function aborts rendering of the current content.
    00443  *
    00444  * @param refNum IN: the library reference number
    00445  * @param contentH IN: Memory Handle of the current content, returned by HtmlLibCreateContentObject
    00446  *
    00447  */
    00448 void HtmlLibAbortRenderData(UInt16 refnum, MemHandle htmlLibH)
    00449         SYS_TRAP(kHtmlLibTrapAbortRenderData);
    00450
    00451
    00452
    00453 /** Creates a content object (structure in memory that contains content to be rendered).
    00454  *
    00455  * @param refNum IN: the library reference number
    00456  * @param htmlLibH IN: the memory handle returned by HtmlLibInitialize
    00457  *
    00458  * @return This function returns the memory handle of a content data object.
    00459  */
    00460 MemHandle HtmlLibCreateContentObject(UInt16 refnum, MemHandle htmlLibH)
    00461         SYS_TRAP(kHtmlLibTrapCreateContentObject);
    00462
    00463
    00464
    00465 /** This function destroys the content data object created by HtmlLibCreateContentObject.
    00466  *
    00467  * @note  Be cautious when destroying a content object - make sure it is not busy doing something else, like rendering data. You can use HtmlLibProgress to check for the status (busy or not), or you can call HtmlLibAbortRenderData first.
    00468  * @param refNum IN: the library reference number
    00469  * @param contentH IN: Memory Handle returned by HtmlLibCreateContentObject
    00470  *
    00471  */
    00472 void HtmlLibDestroyContentObject(UInt16 refnum, MemHandle contentH)
    00473         SYS_TRAP(kHtmlLibTrapDestroyContentObject);
    00474
    00475
    00476
    00477 /** This function adds text data to the content data object created by HtmlLibCreateContentObject. Application should call HtmlLibRenderData when it has finished adding text data, for the data to be rendered.
    00478  * @note  There is a limit of 64K of text data per content object (and not just per call of HtmlLibAddTextData).
    00479  *
    00480  * @param refNum IN: the library reference number
    00481  * @param contentH IN: Memory Handle returned by HtmlLibCreateContentObject
    00482  * @param url IN: url of the page you are adding to (unique, to make sure nothing is written over)
    00483  * @param mimeType IN: mime type of the text (such as "text/plain", "text/html")
    00484  * @param charset IN: the character set (such as "us-ascii")
    00485  * @param data IN: a reference to the text data to be added
    00486  * @param dataLen IN: length of the data
    00487  *
    00488  * @return This function returns an error code (returns errNone if successful).
    00489  */
    00490 Err HtmlLibAddTextData(UInt16 refnum, MemHandle contentH, Char *url, Char *mimeType, Char *charset, void *data, Int32 dataLen)
    00491         SYS_TRAP(kHtmlLibTrapAddTextData);
    00492
    00493
    00494
    00495 /** This function adds images to HtmlLib. (You can use this to respond to Inclusion callback - please see section 2.1 Image Rendering).
    00496  *
    00497  * @param refNum IN: the library reference number
    00498  * @param contentH IN: Memory Handle returned by HtmlLibCreateContentObject
    00499  * @param url IN: url of the image
    00500  * @param mimeType IN: mime type of the image (for example, "image/jpeg")
    00501  * @param data IN: image data
    00502  * @param dataLen IN: image data size
    00503  *
    00504  * @return Error code.
    00505  *
    00506  */
    00507 Err HtmlLibAddImageData(UInt16 refnum, MemHandle contentH, Char *url, Char *mimeType, void *data, Int32 dataLen)
    00508         SYS_TRAP(kHtmlLibTrapAddImageData);
    00509
    00510
    00511
    00512 /** Applications should call this function after adding text data by HtmlLibAddTextData (or image data by HtmlLibAddImageData, see section 2.1 Image Rendering) to have HTML library start rendering the content.
    00513  *
    00514  * @param refNum IN: the library reference number
    00515  * @param contentH IN: Memory Handle returned by HtmlLibCreateContentObject that contains the text data to be rendered
    00516  *
    00517  */
    00518 void HtmlLibRenderData(UInt16 refnum, MemHandle contentH)
    00519         SYS_TRAP(kHtmlLibTrapRenderData);
    00520
    00521
    00522
    00523 /** This redraws the HtmlLib rendering screen (for example, when application receives a frmUpdate event).
    00524  *
    00525  * @param refNum IN: the library reference number
    00526  * @param htmlLibH IN: the memory handle returned by HtmlLibInitialize
    00527  *
    00528  */
    00529 void HtmlLibRedrawScreen(UInt16 refnum, MemHandle htmlLibH)
    00530         SYS_TRAP(kHtmlLibTrapRedrawScreen);
    00531
    00532
    00533
    00534 /** This function passes an array of scrollbars to HtmlLib. Html library will not display any scrollbar if application does not call this function (scrollbars cannot be added dynamically).  Application is recommended to pass no less than 4 (or at the very least 2) scrollbars, and up to 9 scrollbars.
    00535  * For example (after defining RenderScroll0ScrollBar and RenderScroll1ScrollBar):
    00536  *
    00537  * @code
    00538  *  UInt16 scrollbars[2] = {RenderScroll0ScrollBar, RenderScroll1ScrollBar};
    00539  *  HtmlLibSetScrollbars(gRefNum, gHtmlLibH, scrollbars, 2);
    00540  * @endcode
    00541  *
    00542  * @param refNum IN: the library reference number
    00543  * @param htmlLibH IN: the memory handle returned by HtmlLibInitialize
    00544  * @param scrollbars IN: array of scrollbars
    00545  * @param size IN: size of the array of scrollbars
    00546  *
    00547  */
    00548 void HtmlLibSetScrollbars(UInt16 refnum, MemHandle htmlLibH, UInt16 *scrollbars, UInt16 size)
    00549         SYS_TRAP(kHtmlLibTrapSetScrollbars);
    00550
    00551
    00552
    00553 /** This function obtains the current scroll position in pixels from the top of the page.
    00554  *
    00555  * @param refNum IN: the library reference number
    00556  * @param htmlLibH IN: the memory handle returned by HtmlLibInitialize
    00557  * @param valueP IN: at function's return, this contains the position in pixels from the top of the page
    00558  *
    00559  * @return Error code.
    00560  *
    00561  */
    00562 Err HtmlLibGetVScrollPosition(UInt16 refnum, MemHandle htmlLibH, Int16 *valueP)
    00563         SYS_TRAP(kHtmlLibTrapGetVScrollPosition);
    00564
    00565
    00566
    00567
    00568 /** This function sets the current scroll position in pixels from the top of the page. If the total page height of the current page is less than this, this scrolls the page to the bottom.
    00569  *
    00570  * @param refNum IN: the library reference number
    00571  * @param htmlLibH IN: the memory handle returned by HtmlLibInitialize
    00572  * @param newPosition IN: the position in pixels from the top of the page
    00573  *
    00574  * @return Error code.
    00575  *
    00576  */
    00577 Err HtmlLibSetVScrollPosition(UInt16 refnum, MemHandle htmlLibH, Int16 newPosition)
    00578         SYS_TRAP(kHtmlLibTrapSetVScrollPosition);
    00579
    00580
    00581
    00582 /** This function lets you know whether scrolling is possible in the indicated direction.
    00583  *
    00584  * @param refNum IN: the library reference number
    00585  * @param htmlLibH IN: the memory handle returned by HtmlLibInitialize
    00586  * @param direction IN: htmlDirLeft, htmlDirRight, htmlDirUp, htmlDirDown
    00587  *
    00588  * @return Function outputs true if scrolling in the indicated direction is possible.
    00589  *
    00590  */
    00591 Boolean HtmlLibCanScroll(UInt16 refnum, MemHandle htmlLibH, HtmlScrollDirection direction)
    00592         SYS_TRAP(kHtmlLibTrapCanScroll);
    00593
    00594
    00595
    00596
    00597 /** This function sets the page's scrollbar mode, without affecting the scrollbars of a textarea. A reason to use htmlNoPageScrollbarMode and not htmlNormalScrollbarMode is if you would like to use your own scrollbars, and use HtmlLib(Set/Get)VScrollPosition to do so.
    00598  *
    00599  * @param refNum IN: the library reference number
    00600  * @param htmlLibH IN: the memory handle returned by HtmlLibInitialize
    00601  * @param mode  IN: scrollbar mode (htmlNormalScrollbarMode to enable scrolling or htmlNoPageScrollbarMode for no scrolling)
    00602  *
    00603  * @return Error code. (htmlErrNotInitialized, htmlErrInUse)
    00604  *
    00605  */
    00606 Err HtmlLibSetScrollbarMode(UInt16 refnum, MemHandle htmlLibH, HtmlScrollbarMode mode)
    00607         SYS_TRAP(kHtmlLibTrapSetScrollbarMode);
    00608
    00609
    00610 /** This function will control the size of the font used by HtmlLib.
    00611  *
    00612  * @param refNum IN: the library reference number
    00613  * @param htmlLibH IN: htmlLib handle
    00614  * @param value IN: true if you would like bigger font (bigger font corresponds to the  Large font option in Blazer), and false otherwise (false would correspond to the Small font option in Blazer).
    00615  *
    00616  * @return Error code.
    00617  *
    00618  */
    00619 Err HtmlLibSetBiggerFont(UInt16 refnum, MemHandle htmlLibH, Boolean value)
    00620         SYS_TRAP(kHtmlLibTrapSetBiggerFont);
    00621
    00622
    00623 /** This function reinitializes the focus to point to nothing.
    00624  *
    00625  * @param refNum IN: the library reference number
    00626  * @param htmlLibH IN: htmlLib handle
    00627  *
    00628  * @return True if the focus was reset to point to nothing.
    00629  *
    00630  */
    00631 Boolean HtmlLibResetFocusInfo(UInt16 refnum, MemHandle htmlLibH)
    00632         SYS_TRAP(kHtmlLibTrapResetFocusInfo);
    00633
    00634
    00635 /** This function sets the focus according to the condition flags passed in.
    00636  *
    00637  * @param refNum IN: the library reference number
    00638  * @param htmlLibH IN: htmlLib handle
    00639  * @param flag - Enables (true) or Disables (false) focus handling
    00640  * @param reset_focus - if flag is true: if reset_focus is true, then the code tries to set the next focus onto the next target in the event focus walk chain. If false, it again sets the focus to the current event target.
    00641  *
    00642  */
    00643 void HtmlLibSetFocusStatus(UInt16 refnum, MemHandle htmlLibH, Boolean flag, Boolean reset_focus)
    00644         SYS_TRAP(kHtmlLibTrapSetFocusStatus);
    00645
    00646 /* 68K only */
    00647
    00648 /**  This function sets the function pointers of some necessary form widget creation/deletion routines.
    00649  *The following is sufficient for most purposes (and included in the sample application):
    00650  *
    00651  * @code
    00652  *
    00653  *  static HtmlLibFormWidgetProc *widgetProc = NULL;
    00654  *
    00655  *  widgetProc = MemPtrNew(sizeof(HtmlLibFormWidgetProc));
    00656  *  if (widgetProc) {
    00657  *      //functions defined in sample code
    00658  *      widgetProc->newControlProc = RendererNewControlProc;
    00659  *      widgetProc->newFieldProc = RendererNewFieldProc;
    00660  *      widgetProc->newListProc = RendererNewListProc;
    00661  *      widgetProc->deleteObjectProc = RendererDeleteObjectProc;
    00662  *  }
    00663  *
    00664  *  HtmlLibSetFormWidgetProc(refNum, htmlLibH, widgetProc);
    00665  *
    00666  * @endcode
    00667  *
    00668  * A standard example of the necessary form widget creation/deletion routines are provided below, and can be found in the sample code.
    00669  *
    00670  * @code
    00671  *
    00672  * static Boolean
    00673  * RendererNewControlProc(UInt16 ID,
    00674  *     UInt16 style, const Char *textP,
    00675  *     Coord x, Coord y, Coord width, Coord height,
    00676  *     UInt16 font, UInt8 group, Boolean leftAnchor)
    00677  *
    00678  *  {
    00679  *     ControlType *ctlP;
    00680  *     FormType *formP = FrmGetActiveForm();
    00681  *     ctlP = CtlNewControl((void**)&formP, ID, style, textP, x, y, width, height, font, group, leftAnchor);
    00682  *     if (ctlP) {
    00683  *         return true;
    00684  *     }
    00685  *     return false;
    00686  *  }
    00687  *
    00688  *  static Boolean
    00689  *  RendererNewFieldProc(UInt16 id,
    00690  *         Coord x, Coord y, Coord width, Coord height,
    00691  *     UInt16 font, UInt32 maxChars, UInt16 editable, UInt16 underlined,
    00692  *     UInt16 singleLine, UInt16 dynamicSize, UInt16 justification,
    00693  *     UInt16 autoShift, UInt16 hasScrollBar, UInt16 numeric)
    00694  *
    00695  *  {
    00696  *     FieldType *fieldP;
    00697  *     FormType *formP = FrmGetActiveForm();
    00698  *     fieldP = FldNewField((void**)&formP, id, x, y, width, height, (FontID)font,
    00699  *                     maxChars, (Boolean)editable, (Boolean)underlined, (Boolean)singleLine,
    00700  *                     (Boolean)dynamicSize, (JustificationType)justification, (Boolean)autoShift,
    00701  *                     (Boolean)hasScrollBar, (Boolean)numeric);
    00702  *     if (fieldP) {
    00703  *         return true;
    00704  *     }
    00705  *     return false;
    00706  *  }
    00707  *
    00708  *  static Err
    00709  *  RendererNewListProc(UInt16 id,
    00710  *     Coord x, Coord y, Coord width, Coord height,
    00711  *     UInt16 font, Int16 visibleItems, Int16 triggerId)
    00712  *  {
    00713  *     FormType *formP = FrmGetActiveForm();
    00714  *     return LstNewList((void**)&formP, id, x, y, width, height, font,
    00715  *                         visibleItems, triggerId);
    00716  *  }
    00717  *
    00718  *  static void
    00719  *  RendererDeleteObjectProc(UInt16 index)
    00720  *  {
    00721  *     FormType *formP = FrmGetActiveForm();
    00722  *     FrmRemoveObject(&formP, index);
    00723  *  }
    00724  *
    00725  * @endcode
    00726  *
    00727  *
    00728  * @param refNum IN: HTML library reference number
    00729  * @param htmlLibH IN: htmlLib handle
    00730  * @param proc IN: function pointers of form widget creation/deletion routines.
    00731  *
    00732  */
    00733 void HtmlLibSetFormWidgetProc(UInt16 refnum, MemHandle htmlLibH, HtmlLibFormWidgetProc *proc)
    00734         SYS_TRAP(kHtmlLibTrapSetFormWidgetProc);
    00735
    00736 Boolean HtmlLibGetTargetInfo(UInt16 refnum, MemHandle htmlLibH,  HtmlLibFocusTargetInfo *htmlTargetInfo)
    00737         SYS_TRAP(kHtmlLibTrapGetTargetInfo);
    00738
    00739 Err HtmlLibSetImageMemoryLimit(UInt16 renum, MemHandle htmlLibH, Int32 limit)
    00740         SYS_TRAP(kHtmlLibTrapSetImageMemoryLimit);
    00741
    00742 #endif /* HTMLLIb68K_H__ */

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