API Guide Home (Online version only)

HtmlLib68K.h

Go to the documentation of this file.

/*
    HtmlLib68K.h
    Copyright(c) 1996-2002 ACCESS CO., LTD.
    All rights are reserved by ACCESS CO., LTD., whether the whole or
    part of the source code including any modifications.
*/

 /** @defgroup HtmlLib HTML Library
 * 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.
 * 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.
 *
 * @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.
 *
 * @{
 * @}   
 */
 /**
 @ingroup HtmlLib
 */
 
/**
*                                                                                                                                         
* @file HtmlLib68K.h                                                                                                          
*                                                                         
* @brief Public 68K include file for HTML shared library.
*                                                                       
*/

#ifndef HTMLLIb68K_H__
#define HTMLLIb68K_H__

#include <PalmTypes.h>
#include <LibTraps.h>

#include <HtmlLibTrap.h>

#include <ErrorBase.h>

#define htmlErrorClass  (appErrorClass)

/**
 * @name HtmlLib error codes
 *
 */
 /*@{*/
/************************************************************
 * HtmlLib error codes
 *************************************************************/
#define htmlErrInUse            (htmlErrorClass | 1)
#define htmlErrOutOfMemory      (htmlErrorClass | 2)
#define htmlErrInvalidParam     (htmlErrorClass | 3)        
#define htmlErrNotFound         (htmlErrorClass | 4)
#define htmlErrNotInitialized   (htmlErrorClass | 5)
#define htmlErrCantOpen         (htmlErrorClass | 6)
/*@}*/

#define htmlLibProgressEvent    (0x7000)

/************************************************************
 * HtmlLib l
 *************************************************************/

#define HtmlLibID       'AsHL'
#define HtmlLibDBType   'libr'
#define HtmlLibName     "HtmlLibrary"


/* 
 * Typedef
 */

/** 
 * @name Typedef
 */
/*@{*/
typedef UInt8 HtmlDisplayMode;
typedef UInt16 HtmlProgressStatus;
typedef UInt32 HtmlSubmitFormMethod;
typedef Int8 HtmlScrollDirection;
typedef Int8 HtmlScrollbarMode;


/* HtmlFocusTargetType */
#define htmlTargetImage             0x01
#define htmlTargetEmbed             0x02
#define htmlTargetIFrame            0x03
#define htmlTargetElement           0x04
#define htmlTargetInputText         0x05
#define htmlTargetInputPassword     0x06
#define htmlTargetInputCheckbox     0x07
#define htmlTargetInputRadio        0x08
#define htmlTargetInputSubmit       0x09
#define htmlTargetInputReset        0x0a
#define htmlTargetInputFile         0x0b
#define htmlTargetInputButton       0x0c
#define htmlTargetInputTextarea     0x0d
#define htmlTargetInputSelect       0x0e

typedef UInt16 HtmlFocusTargetType;

/** 
 * @name Callback Functions
 */
/*@{*/


/** 
 *Should be defined (to handle a link selection) and set as the function to be called when a link (url) is selected.
 */
typedef void HtmlLibLinkSelCallback(MemHandle htmlLibH, Char *url, void *cbData);

/** 
 *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.
 * 
 * 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. 
 */
typedef Boolean HtmlLibScanPhoneNumberCallback(MemHandle htmlLibH, Char *buffer, Int32 length, Int32 *patternStart, Int32 *patternEnd);

/** 
 *Should be defined and set as the function to be called when rendering a page requires additional content.
 *
 * HtmlLib calls this callback function with the appropriate arguments (where the url is the url of the additional content the library requires).
 */
typedef void HtmlLibInclusionCallback(MemHandle htmlLibH, Char *url, void *cbData);

/**
 * @note Forms are not supported; thus, use this at your own risk.
 * 
 *Should be defined and set as the function to be called when a submit is activated.
 *
 * HtmlLib calls this callback function with the appropriate arguments. The following is an example (included in the sample code):
 *
 * @code
 *
 * void HtmlSubmitFormCallback(MemHandle htmlLibH, Char *url, HtmlSubmitFormMethod method, Char *query, void *cbData) 
 * {
 *   FrmCustomAlert(SubmitFormAlert, url, 
 *      (method == htmlHttpMethodPost ? "Post" : "Get"), query);
 * }
 *
 * @endcode
 *
 */
typedef void HtmlLibSubmitFormCallback(MemHandle htmlLibH, Char *url, HtmlSubmitFormMethod method, Char *query, void *cbData);

typedef Boolean NewControlProc(UInt16 id, 
    UInt16 style, const Char *textP, 
    Coord x, Coord y, Coord width, Coord height, 
    UInt16 font, UInt8 group, Boolean leftAnchor); /**< @see HtmlLibFormWidgetProc*/

typedef Err NewListProc(UInt16 id, 
                    Coord x, Coord y, Coord width, Coord height, 
                    UInt16 font, Int16 visibleItems, Int16 triggerId); /**< @see HtmlLibFormWidgetProc*/

typedef Boolean NewFieldProc(UInt16 id, 
    Coord x, Coord y, Coord width, Coord height, 
    UInt16 font, UInt32 maxChars, UInt16 editable, UInt16 underlined, 
    UInt16 singleLine, UInt16 dynamicSize, UInt16 justification, 
    UInt16 autoShift, UInt16 hasScrollBar, UInt16 numeric);  /**< @see HtmlLibFormWidgetProc*/

typedef void DeleteObjectProc(UInt16 index); /**< @see HtmlLibFormWidgetProc*/

/** @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.
*
* @see HtmlLibSetFormWidgetProc
*/
typedef struct {
    NewControlProc *newControlProc;
    NewListProc *newListProc;
    NewFieldProc *newFieldProc;
    DeleteObjectProc *deleteObjectProc;
} HtmlLibFormWidgetProc;
/*@}*/

/* HtmlLibFocusTargetInfo */
typedef struct {
    HtmlFocusTargetType type;
    RectangleType bounds; /* in window coordinate */
    UInt16 formObjectID;  /* set only for form object */
} HtmlLibFocusTargetInfo;


/* HtmlDisplayMode */
/** @name HtmlDisplayMode */
/*@{*/
#define htmlHandheldDisplayMode 0x01
#define htmlFaithfulDisplayMode 0x02
/*@}*/


/* HtmlProgressStatus */
/** @name HtmlProgressStatus */
/*@{*/
#define htmlProgressDone        0x0001
#define htmlProgressBusy        0x0002
#define htmlProgressOutOfMemory 0x0003
#define htmlProgressError       0x0004
/*@}*/


/* HtmlSubmitFormMethod */
/** @name HtmlSubmitFormMethod */
/*@{*/
#define htmlHttpMethodGet   0x00000001
#define htmlHttpMethodPost  0x00000002
/*@}*/


/* HtmlDirections */
/** @name HtmlDirections */
/*@{*/
#define htmlDirLeft         0x01
#define htmlDirRight        0x02
#define htmlDirUp           0x03
#define htmlDirDown         0x04
/*@}*/


/* HtmlScrollMode */
/** @name HtmlScrollMode */
/*@{*/
#define htmlNormalScrollbarMode 0x01
#define htmlNoPageScrollbarMode 0x02
/*@}*/


/*@}*/
/* 
 * API
 */

/** Standard library open routine.
 *
 * @param refun IN: the library reference number
 *
 * @return Error code.
 */
Err HtmlLibOpen(UInt16 refnum)
        SYS_TRAP(kHtmlLibTrapOpen);

/** Standard library close routine.
 *
 * @param refun IN: the library reference number
 *
 * @return Error code.
 */ 
Err HtmlLibClose(UInt16 refnum)
        SYS_TRAP(kHtmlLibTrapClose);

/** Standard library sleep routine.
 *
 * @param refun IN: the library reference number
 *
 * @return Error code.
 */ 
Err HtmlLibSleep(UInt16 refnum)
        SYS_TRAP(kHtmlLibTrapSleep);

/** Standard library wake routine.
 *
 * @param refun IN: the library reference number
 *
 * @return Error code.
 */ 
Err HtmlLibWake(UInt16 refnum)
        SYS_TRAP(kHtmlLibTrapWake);

/** Html Library initialization function.
 * Initializes the library, after the library has been loaded. 
 *
 * @param   refNum      IN: the library reference number
 * @param   bounds      IN: the screen area the library will draw the rendered content (bounds within 160 x 160 grid)
 * @param    errP       IN: error code if library fails to initialize. The error code can be one of
 * (htmlErrInUse, htmlErrOutOfMemory, htmlErrInvalidParam, htmlErrInUse, htmlErrCantOpen)
 *
 * @return A memory handle to the HTML library context.
 */
MemHandle HtmlLibInitialize(UInt16 refnum, RectangleType bounds, Err *errP)
        SYS_TRAP(kHtmlLibTrapInitialize);

MemHandle HtmlLibInitializeWithHeapSize(UInt16 refnum, RectangleType bounds, Err *errP, UInt32 heapMinSize, UInt32 heapDesiredSize, UInt32 *heapActualSizeP)
        SYS_TRAP(kHtmlLibTrapInitializeWithHeapSize);

/** Finalizes the library when you are done using it 
 * @note  If you need to use the library again after it has been finalized, you will need to re-initialize it.  
 *
 * @param refNum  IN: the library reference number
 * @param htmlLibH IN: the memory handle returned by HtmlLibInitialize
 */ 
void HtmlLibFinalize(UInt16 refnum, MemHandle htmllibH)
        SYS_TRAP(kHtmlLibTrapFinalize);

/** Resize the screen area.
 *
 * @param refNum IN: the library reference number
 * @param htmlLibH IN: the memory handle returned by HtmlLibInitialize
 * @param newBounds IN: the new bounds of the screen area (bounds within 160 x 160 grid)
 *
 * @return errNone if resize is successful, otherwise returns an error code (errInvalidParam)
 */
void HtmlLibResizeScreen(UInt16 refnum, MemHandle htmlLibH, RectangleType newBounds)
        SYS_TRAP(kHtmlLibTrapResizeScreen);

/** Sets the display mode (faithful rendering, which corresponds to Blazer's Wide Page Mode, or handheld wrapped, which corresponds to Blazer's Optimized Mode).
 *
 * @param refNum IN: the library reference number
 * @param htmlLibH IN: the memory handle returned by HtmlLibInitialize
 * @param mode IN: display mode (htmlFaithfulDisplayMode or htmlHandheldDisplayMode)
 *
 */
void HtmlLibSetDisplayMode(UInt16 refnum, MemHandle htmlLibH, HtmlDisplayMode mode)
        SYS_TRAP(kHtmlLibTrapSetDisplayMode);

/** Specify the function that you want the library to call when a link is followed. 
 *
 * @param refNum  IN: the library reference number
 * @param htmlLibH  IN: the memory handle returned by HtmlLibInitialize
 * @param callback IN: a pointer to the function you want called when a link is followed. 
 * @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.
 * 
 * @note  The callback function should be in the following form:
 *   void HtmlLinkSelCallback(MemHandle htmlLibH, Char *url, void *cbData);
 * The library will call this function, supplying the appropriate arguments (where the url is the url of the link which was selected).
 * @see HtmlLibLinkSelCallback
 */
void HtmlLibSetLinkSelectionCallback(UInt16 refnum, MemHandle htmlLibH, HtmlLibLinkSelCallback *callback, void *cbData)
        SYS_TRAP(kHtmlLibTrapSetLinkSelectionCallback);

/** Specify the function that you want the library to call to determine whether some string of numbers contains a phone number.
 * 
 * @param refNum IN: the library reference number
 * @param htmlLibH IN: the memory handle returned by HtmlLibInitialize
 * @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. 
 *
 * @note  The callback function should be in the following form:
 * Boolean HtmlLibScanPhoneNumberCallback(MemHandle htmlLibH, Char   *buffer, Int32 length, Int32 *patternStart, Int32 *patternEnd);
 *
 * @see HtmlLibScanPhoneNumberCallback
 */
void HtmlLibSetScanPhoneNumberCallback(UInt16 refnum, MemHandle htmlLibH, HtmlLibScanPhoneNumberCallback *callback)
        SYS_TRAP(kHtmlLibTrapSetScanPhoneNumberCallback);

/** 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). 
 *
 * @param refNum IN: the library reference number 
 * @param htmlLibH IN: the memory handle returned by HtmlLibInitialize
 * @param callback IN: a pointer to the function you want called when rendering a page that requires additional content. 
 * @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.
 *
 * @note: The callback function should be in the following form:
 * void HtmlLibInclusionCallback(MemHandle htmlLibH, Char *url, void *cbData);
 *
 * HtmlLib calls this callback function with the appropriate arguments (where the url is the url of the additional content the library requires).
 *
 * @see HtmlLibInclusionCallback
 *
 */     
void HtmlLibSetInclusionCallback(UInt16 refnum, MemHandle htmlLibH, HtmlLibInclusionCallback *callback, void *cbData)
        SYS_TRAP(kHtmlLibTrapSetInclusionCallback);

/** @note:  Forms are not supported; thus, use this at your own risk.
 *
 * This functions lets you specify the function that you want the library to call when a "submit" is activated.
 *
 * @param refNum IN: the library reference number
 * @param htmlLibH IN: the memory handle returned by HtmlLibInitialize
 * @param callback IN: a pointer to the function you want called when a "submit" is activated
 * @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.
 *
 * @note  The callback function should be in the following form:
 *
 * HtmlLibSubmitFormCallback(MemHandle htmlLibH, Char *url, HtmlSubmitFormMethod method, Char *query, void *cbData);
 *
 * HtmlLib calls this callback function with the appropriate arguments. 
 *
 * @see HtmlLibSubmitFormCallback
 *
 */
void HtmlLibSetSubmitFormCallback(UInt16 refnum, MemHandle htmlLibH, HtmlLibSubmitFormCallback *callback, void *cbData)
        SYS_TRAP(kHtmlLibTrapSetSubmitFormCallback);

/** Applications should call this function to allow HTML library to process content and draw to screen. 
 * @note The Html Library will run only if you call this! 
 *
 *@param refNum IN: the library reference number
 *@param htmlLibH IN:  the memory handle returned by HtmlLibInitialize
 *@param stayTime IN: maximum time (in milliseconds) for HTML library to do processing. (At least 1300 is recommend.) 
 *
 *@return Status - htmlProgressDone, htmlProgressBusy, htmlProgressOutOfMemory, and other error codes.
 */     
UInt16 HtmlLibProgress(UInt16 refnum, MemHandle htmlLibH, Int32 stayTime)
        SYS_TRAP(kHtmlLibTrapProgress);

/** 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.
 *
 *@param refNum IN: the library reference number
 *@param htmlLibH IN: the memory handle returned by HtmlLibInitialize
 *@param eventP IN: the event you would like the library to handle
 *
 *@return True if the library considers this event handled.
 */
Boolean HtmlLibNotifyUIEvent(UInt16 refnum, MemHandle htmlLibH, EventType *eventP)
        SYS_TRAP(kHtmlLibTrapNotifyUIEvent);

/** Applications should call this function to find a given text string on the page.  Page will automatically scroll to show search result.
 *
 *@param refNum IN: the library reference number
 *@param htmlLibH IN: the memory handle returned by HtmlLibInitialize
 *@param searchString IN: the given text string we are looking for on the page
 *@param wrapSearch IN: true if you would like to wrap search  
 *
 *@return Error code (errNone, htmlErrNotFound).
 */
Err HtmlLibFindText(UInt16 refnum, MemHandle htmlLibH, Char *searchString, Boolean wrapSearch)
        SYS_TRAP(kHtmlLibTrapFindText);


/** Applications should use this function to retrieve the current selected text.  Caller application must free the pointer returned in selectedText using MemPtrFree.
 *
 * @param refNum IN: the library reference number
 * @param htmlLibH IN: the memory handle returned by HtmlLibInitialize
 * @param selectedText IN: the selected text that we are retrieving
 *
 * @return This function returns false if no current selection, otherwise returns true.
 */
Boolean HtmlLibGetTextSelection(UInt16 refnum, MemHandle htmlLibH, Char **selectedText)
        SYS_TRAP(kHtmlLibTrapGetTextSelection);



/** This function clears the rendering screen.  It must be called before content object is destroyed.
 *
 *
 * @param refNum IN: the library reference number
 * @param htmlLibH IN: the memory handle returned by HtmlLibInitialize
 */
void HtmlLibClearScreen(UInt16 refnum, MemHandle htmlLibH)
        SYS_TRAP(kHtmlLibTrapClearScreen);
        
        

/** This function aborts rendering of the current content.
 *
 * @param refNum IN: the library reference number
 * @param contentH IN: Memory Handle of the current content, returned by HtmlLibCreateContentObject
 *
 */     
void HtmlLibAbortRenderData(UInt16 refnum, MemHandle htmlLibH)
        SYS_TRAP(kHtmlLibTrapAbortRenderData);



/** Creates a content object (structure in memory that contains content to be rendered).
 *
 * @param refNum IN: the library reference number
 * @param htmlLibH IN: the memory handle returned by HtmlLibInitialize
 *
 * @return This function returns the memory handle of a content data object.
 */
MemHandle HtmlLibCreateContentObject(UInt16 refnum, MemHandle htmlLibH)
        SYS_TRAP(kHtmlLibTrapCreateContentObject);



/** This function destroys the content data object created by HtmlLibCreateContentObject. 
 *
 * @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.
 * @param refNum IN: the library reference number
 * @param contentH IN: Memory Handle returned by HtmlLibCreateContentObject
 *
 */
void HtmlLibDestroyContentObject(UInt16 refnum, MemHandle contentH)
        SYS_TRAP(kHtmlLibTrapDestroyContentObject);
        
        
        
/** 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.
 * @note  There is a limit of 64K of text data per content object (and not just per call of HtmlLibAddTextData).
 *
 * @param refNum IN: the library reference number
 * @param contentH IN: Memory Handle returned by HtmlLibCreateContentObject
 * @param url IN: url of the page you are adding to (unique, to make sure nothing is written over)
 * @param mimeType IN: mime type of the text (such as "text/plain", "text/html")
 * @param charset IN: the character set (such as "us-ascii")
 * @param data IN: a reference to the text data to be added
 * @param dataLen IN: length of the data
 *
 * @return This function returns an error code (returns errNone if successful).
 */     
Err HtmlLibAddTextData(UInt16 refnum, MemHandle contentH, Char *url, Char *mimeType, Char *charset, void *data, Int32 dataLen)
        SYS_TRAP(kHtmlLibTrapAddTextData);
        
        
        
/** This function adds images to HtmlLib. (You can use this to respond to Inclusion callback - please see section 2.1 Image Rendering).
 *
 * @param refNum IN: the library reference number
 * @param contentH IN: Memory Handle returned by HtmlLibCreateContentObject
 * @param url IN: url of the image
 * @param mimeType IN: mime type of the image (for example, "image/jpeg")
 * @param data IN: image data
 * @param dataLen IN: image data size
 *
 * @return Error code.
 *
 */     
Err HtmlLibAddImageData(UInt16 refnum, MemHandle contentH, Char *url, Char *mimeType, void *data, Int32 dataLen)
        SYS_TRAP(kHtmlLibTrapAddImageData);
        
        
        
/** 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.
 *
 * @param refNum IN: the library reference number
 * @param contentH IN: Memory Handle returned by HtmlLibCreateContentObject that contains the text data to be rendered
 *
 */     
void HtmlLibRenderData(UInt16 refnum, MemHandle contentH)
        SYS_TRAP(kHtmlLibTrapRenderData);
        
        
        
/** This redraws the HtmlLib rendering screen (for example, when application receives a frmUpdate event).
 *
 * @param refNum IN: the library reference number
 * @param htmlLibH IN: the memory handle returned by HtmlLibInitialize
 *
 */     
void HtmlLibRedrawScreen(UInt16 refnum, MemHandle htmlLibH)
        SYS_TRAP(kHtmlLibTrapRedrawScreen);
        
        

/** 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.
 * For example (after defining RenderScroll0ScrollBar and RenderScroll1ScrollBar):
 *
 * @code
 *  UInt16 scrollbars[2] = {RenderScroll0ScrollBar, RenderScroll1ScrollBar};
 *  HtmlLibSetScrollbars(gRefNum, gHtmlLibH, scrollbars, 2);
 * @endcode
 *
 * @param refNum IN: the library reference number
 * @param htmlLibH IN: the memory handle returned by HtmlLibInitialize
 * @param scrollbars IN: array of scrollbars
 * @param size IN: size of the array of scrollbars
 *
 */     
void HtmlLibSetScrollbars(UInt16 refnum, MemHandle htmlLibH, UInt16 *scrollbars, UInt16 size)
        SYS_TRAP(kHtmlLibTrapSetScrollbars);



/** This function obtains the current scroll position in pixels from the top of the page.
 *
 * @param refNum IN: the library reference number
 * @param htmlLibH IN: the memory handle returned by HtmlLibInitialize
 * @param valueP IN: at function's return, this contains the position in pixels from the top of the page 
 *
 * @return Error code.
 *
 */
Err HtmlLibGetVScrollPosition(UInt16 refnum, MemHandle htmlLibH, Int16 *valueP)
        SYS_TRAP(kHtmlLibTrapGetVScrollPosition);
        
        
        

/** 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.
 *
 * @param refNum IN: the library reference number
 * @param htmlLibH IN: the memory handle returned by HtmlLibInitialize
 * @param newPosition IN: the position in pixels from the top of the page 
 *
 * @return Error code.
 *
 */     
Err HtmlLibSetVScrollPosition(UInt16 refnum, MemHandle htmlLibH, Int16 newPosition)
        SYS_TRAP(kHtmlLibTrapSetVScrollPosition);



/** This function lets you know whether scrolling is possible in the indicated direction.
 *  
 * @param refNum IN: the library reference number
 * @param htmlLibH IN: the memory handle returned by HtmlLibInitialize
 * @param direction IN: htmlDirLeft, htmlDirRight, htmlDirUp, htmlDirDown
 *
 * @return Function outputs true if scrolling in the indicated direction is possible.
 *
 */
Boolean HtmlLibCanScroll(UInt16 refnum, MemHandle htmlLibH, HtmlScrollDirection direction)
        SYS_TRAP(kHtmlLibTrapCanScroll);




/** 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.
 *
 * @param refNum IN: the library reference number
 * @param htmlLibH IN: the memory handle returned by HtmlLibInitialize
 * @param mode  IN: scrollbar mode (htmlNormalScrollbarMode to enable scrolling or htmlNoPageScrollbarMode for no scrolling)
 *
 * @return Error code. (htmlErrNotInitialized, htmlErrInUse)
 *
 */
Err HtmlLibSetScrollbarMode(UInt16 refnum, MemHandle htmlLibH, HtmlScrollbarMode mode)
        SYS_TRAP(kHtmlLibTrapSetScrollbarMode);


/** This function will control the size of the font used by HtmlLib.  
 *
 * @param refNum IN: the library reference number
 * @param htmlLibH IN: htmlLib handle
 * @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).
 * 
 * @return Error code.
 *
 */
Err HtmlLibSetBiggerFont(UInt16 refnum, MemHandle htmlLibH, Boolean value)
        SYS_TRAP(kHtmlLibTrapSetBiggerFont);


/** This function reinitializes the focus to point to nothing.   
 *
 * @param refNum IN: the library reference number
 * @param htmlLibH IN: htmlLib handle
 * 
 * @return True if the focus was reset to point to nothing.
 *
 */
Boolean HtmlLibResetFocusInfo(UInt16 refnum, MemHandle htmlLibH)
        SYS_TRAP(kHtmlLibTrapResetFocusInfo);


/** This function sets the focus according to the condition flags passed in.  
 *
 * @param refNum IN: the library reference number
 * @param htmlLibH IN: htmlLib handle
 * @param flag - Enables (true) or Disables (false) focus handling
 * @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.
 *
 */
void HtmlLibSetFocusStatus(UInt16 refnum, MemHandle htmlLibH, Boolean flag, Boolean reset_focus)
        SYS_TRAP(kHtmlLibTrapSetFocusStatus);

/* 68K only */

/**  This function sets the function pointers of some necessary form widget creation/deletion routines. 
 *The following is sufficient for most purposes (and included in the sample application):
 *
 * @code
 *
 *  static HtmlLibFormWidgetProc *widgetProc = NULL;
 *
 *  widgetProc = MemPtrNew(sizeof(HtmlLibFormWidgetProc));
 *  if (widgetProc) {
 *      //functions defined in sample code
 *      widgetProc->newControlProc = RendererNewControlProc;
 *      widgetProc->newFieldProc = RendererNewFieldProc;             
 *      widgetProc->newListProc = RendererNewListProc;
 *      widgetProc->deleteObjectProc = RendererDeleteObjectProc;
 *  }
 *
 *  HtmlLibSetFormWidgetProc(refNum, htmlLibH, widgetProc);
 *
 * @endcode
 *
 * A standard example of the necessary form widget creation/deletion routines are provided below, and can be found in the sample code. 
 *
 * @code
 *
 * static Boolean
 * RendererNewControlProc(UInt16 ID, 
 *     UInt16 style, const Char *textP, 
 *     Coord x, Coord y, Coord width, Coord height, 
 *     UInt16 font, UInt8 group, Boolean leftAnchor)
 *
 *  {
 *     ControlType *ctlP;
 *     FormType *formP = FrmGetActiveForm();
 *     ctlP = CtlNewControl((void**)&formP, ID, style, textP, x, y, width, height, font, group, leftAnchor);
 *     if (ctlP) {
 *         return true;
 *     }
 *     return false;
 *  }
 *
 *  static Boolean
 *  RendererNewFieldProc(UInt16 id, 
 *         Coord x, Coord y, Coord width, Coord height, 
 *     UInt16 font, UInt32 maxChars, UInt16 editable, UInt16 underlined, 
 *     UInt16 singleLine, UInt16 dynamicSize, UInt16 justification, 
 *     UInt16 autoShift, UInt16 hasScrollBar, UInt16 numeric)
 *
 *  {
 *     FieldType *fieldP;
 *     FormType *formP = FrmGetActiveForm();
 *     fieldP = FldNewField((void**)&formP, id, x, y, width, height, (FontID)font,
 *                     maxChars, (Boolean)editable, (Boolean)underlined, (Boolean)singleLine,
 *                     (Boolean)dynamicSize, (JustificationType)justification, (Boolean)autoShift, 
 *                     (Boolean)hasScrollBar, (Boolean)numeric);
 *     if (fieldP) {
 *         return true;
 *     }
 *     return false;
 *  }
 *
 *  static Err 
 *  RendererNewListProc(UInt16 id, 
 *     Coord x, Coord y, Coord width, Coord height, 
 *     UInt16 font, Int16 visibleItems, Int16 triggerId)
 *  {
 *     FormType *formP = FrmGetActiveForm();
 *     return LstNewList((void**)&formP, id, x, y, width, height, font,
 *                         visibleItems, triggerId);
 *  }
 *
 *  static void
 *  RendererDeleteObjectProc(UInt16 index)
 *  {
 *     FormType *formP = FrmGetActiveForm();
 *     FrmRemoveObject(&formP, index);
 *  }
 *
 * @endcode
 *
 * 
 * @param refNum IN: HTML library reference number
 * @param htmlLibH IN: htmlLib handle
 * @param proc IN: function pointers of form widget creation/deletion routines.
 *
 */
void HtmlLibSetFormWidgetProc(UInt16 refnum, MemHandle htmlLibH, HtmlLibFormWidgetProc *proc)
        SYS_TRAP(kHtmlLibTrapSetFormWidgetProc);

Boolean HtmlLibGetTargetInfo(UInt16 refnum, MemHandle htmlLibH,  HtmlLibFocusTargetInfo *htmlTargetInfo)
        SYS_TRAP(kHtmlLibTrapGetTargetInfo);

Err HtmlLibSetImageMemoryLimit(UInt16 renum, MemHandle htmlLibH, Int32 limit)
        SYS_TRAP(kHtmlLibTrapSetImageMemoryLimit);

#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