API Guide Home (Online version only) |

# palmOneVMFontLib.h

Go to the documentation of this file.

    00001 /******************************************************************************
    00002  * Copyright (c) 2004 palmOne, Inc. or its subsidiaries.
    00003  * All rights reserved.
    00004  *****************************************************************************/
    00005 /**
    00006  * @ingroup Versamail
    00007  */
    00008
    00009 /**
    00010  * @file    palmOneVMFontLib.h
    00011  * @version 1.0
    00012  *
    00013  * @brief Defines APIs and structures for the Palm VersaMail Font Picker / Font Manager
    00014  * Service which lets users get / set font characteristics.
    00015  */
    00016
    00017 #ifndef __PALMONEVMFONTLIBRARY_H__
    00018 #define __PALMONEVMFONTLIBRARY_H__
    00019
    00020 #include <PalmTypes.h>
    00021 #include <Font.h>
    00022 #include <DataMgr.h>
    00023 #include <LibTraps.h>
    00024 #include <Common/Libraries/VMFont/VMFontLibCommon.h>
    00025
    00026 #ifdef BUILDING_VMFONTLIB
    00027 #define VMFONTLIB_TRAP( trapNum )
    00028 #else
    00029 #define VMFONTLIB_TRAP( trapNum )  SYS_TRAP( trapNum )
    00030 #endif
    00031
    00032
    00033 /********************************************************************
    00034  * Prototypes
    00035  ********************************************************************/
    00036 #ifdef __cplusplus
    00037 extern "C" {
    00038 #endif
    00039
    00040 /**
    00041  * Opens the Font Picker library. Does Initialization of library.
    00042  *
    00043  * @brief This function should be called prior to calling the other Font
    00044  *        Picker functions.
    00045  *
    00046  * @param   libRefNum:      IN: Reference number of the Font Picker library.
    00047  * @param   clientContextP: OUT: pointer to variable for returning client context.
    00048  *                          The client context is used to maintain client-specific
    00049  *                          data for multiple client support.The value returned here
    00050  *                          will be used as a parameter for other library functions
    00051  *                          which require a client context.
    00052  *
    00053  * @retval  Err The error code returned from the library. If this is errNone, the
    00054  *          function was sucessful.
    00055  *
    00056  * @code
    00057  * UInt16 fontPickerLibRefNum = 0;
    00058  * UInt32 context;
    00059  * err = SysLibFind(fontPickerLibName, &fontPickerLibRefNum);
    00060  * if( err == sysErrLibNotFound )
    00061  * {
    00062  *     err = SysLibLoad(fontPickerType, fontPickerCreatorID, &fontPickerLibRefNum);
    00063  *         if( !err ) {
    00064  *             err = VMFontOpen(fontPickerLibRefNum, &context);
    00065  *         }
    00066  * } @endcode
    00067  *
    00068  * @see VMFontClose
    00069  */
    00070
    00071 extern Err VMFontOpen( UInt16 libRefNum, UInt32 *clientContextP )
    00072                 VMFONTLIB_TRAP( sysLibTrapOpen );
    00073
    00074
    00075 /**
    00076  * Closes the Font Picker library and perform cleanup.
    00077  *
    00078  * @brief This function should be called after your application has
    00079  *        finished with the Font Picker library.
    00080  *
    00081  * @param   libRefNum:      IN: Reference number of the Font Picker library.
    00082  * @param   clientContext:  IN: Library's client context number got during open.
    00083  *
    00084  * @retval  Err The error code returned from the library. If this is errNone, the
    00085  *          function was sucessful.
    00086  *
    00087  * @code
    00088  * err = VMFontClose(fontPickerLibRefNum, context); @endcode
    00089  *
    00090  * @see VMFontOpen
    00091  */
    00092
    00093 extern Err VMFontClose( UInt16 libRefNum, UInt32 clientContext )
    00094                 VMFONTLIB_TRAP( sysLibTrapClose );
    00095
    00096
    00097
    00098 /**
    00099  * Get the Font Library Version
    00100  *
    00101  * @param   libRefNum:      IN: Reference number of the Font Picker library.
    00102  * @param   versionP:       OUT: Pointer to the version number
    00103  *
    00104  * @retval  Err Always errNone
    00105  *
    00106  */
    00107
    00108 extern Err VMFontVersion( UInt16 libRefNum, UInt32 *versionP )
    00109                 VMFONTLIB_TRAP( flTrapAPIVersion );
    00110
    00111 /**
    00112  * Get the font ID based on the given font characteristics.
    00113  * The returned font ID is NOT guaranteed to be always available.
    00114  * Therefore to avoid any error, please make sure that VMFontExists
    00115  * is used whenever a font is needed.
    00116  *
    00117  * @param   libRefNum:      IN: Reference number of the Font Picker library.
    00118  * @param   fontP:          IN: the font characteristics.
    00119  *
    00120  * @retval  UInt8 The defined font ID
    00121  *
    00122  * @code
    00123  * // get the font ID for gill Sans MT 9 pt Italic
    00124  * VMFontPtr fontP = (VMFontPtr) MemPtrNew (sizeof (VMFontType));
    00125  * fontP->face = gillSans;
    00126  * fontP->size = size6;
    00127  * fontP->style = italic;
    00128  * UInt8 myFontID = stdFont;
    00129  * if (VMFontExists( theRefNum, fontP ))
    00130  *  {    myFontID = VMFontGetFont( theRefNum, fontP );   } @endcode
    00131  *
    00132  * @see VMFontExists
    00133  */
    00134
    00135 extern UInt8 VMFontGetFont(UInt16 libRefNum, const VMFontPtr fontP)
    00136     VMFONTLIB_TRAP(flTrapAPIGetFont);
    00137
    00138 /**
    00139  * Get the Font characteristics based on a saved FontID
    00140  *
    00141  * @param   libRefNum:      IN: Reference number of the Font Picker library.
    00142  * @param   targetP:        IN: the font characteristics.
    00143  * @param   fontID:         IN: the font ID passed in.
    00144  *
    00145  * @retval  UInt8 The defined font ID
    00146  *
    00147  * @code
    00148  * UInt8 myOldID;
    00149  * UInt8 myFontID;
    00150  * MemHandle handle;
    00151  * VMFontPtr fontP;
    00152  *
    00153  * handle = MemHandleNew(sizeof(VMFontType));
    00154  * fontP = (VMFontPtr) MemHandleLock(handle);
    00155  *
    00156  * myOldID = GetFontIDFromPrefs(); // assume that we have a funct to get the old ID
    00157  * myFontID = VMFontGetFontByID( gRefNum, fontP, myOldID );
    00158  * @endcode
    00159  *
    00160  *
    00161  */
    00162
    00163 extern UInt8 VMFontGetFontByID(UInt16 libRefNum, VMFontPtr targetP, UInt8 fontID)
    00164     VMFONTLIB_TRAP(flTrapAPIGetFontByID);
    00165
    00166 /**
    00167  * Check to see if the specified font exists in the database.
    00168  *
    00169  * @param   libRefNum:      IN: Reference number of the Font Picker library.
    00170  * @param   fontP:          IN: the font characteristics we want to check.
    00171  *
    00172  * @retval  Boolean True if the font exists in the database, false otherwise.
    00173  *
    00174  * @code
    00175  * MemHandle handle;
    00176  * VMFontPtr fontP;
    00177  * Boolean exists = false;
    00178  *
    00179  * handle = MemHandleNew(sizeof( VMFontType ));
    00180  * fontP = (VMFontPtr) MemHandleLock(handle);
    00181  *
    00182  * fontP->face = segoe;
    00183  * fontP->size = size6;
    00184  * fontP->style = bold;
    00185  *
    00186  * exists = VMFontExists( gRefNum, fontP );
    00187  *
    00188  * MemHandleUnlock(handle);
    00189  * MemHandleFree(handle);
    00190  * @endcode
    00191  *
    00192  * @see VMFontGetFont
    00193  */
    00194
    00195 extern Boolean VMFontExists(UInt16 libRefNum, const VMFontPtr fontP)
    00196     VMFONTLIB_TRAP(flTrapAPIFontExists);
    00197
    00198 /**
    00199  * Given a font characteristics (defined as VMFontPtr), get the
    00200  * human-readable font description of that font in the form of
    00201  * "<NAME> <SIZE> <STYLE>", e.g. "Gill Sans MT 9 Bold".
    00202  *
    00203  * @param   libRefNum:      IN: Reference number of the Font Picker library.
    00204  * @param   fontP:          IN: the font characteristics we want to check.
    00205  * @param   stringP:        OUT: Pointer to output string buffer.
    00206  *
    00207  * @retval  Nothing
    00208  *
    00209  */
    00210 extern void VMFontToString(UInt16 libRefNum, const VMFontPtr fontP, char *stringP)
    00211     VMFONTLIB_TRAP(flTrapAPIFontToString);
    00212
    00213
    00214 /**
    00215  * Given a font face, find out how many size/styles were associated with it.
    00216  *
    00217  * @param   libRefNum:      IN: Reference number of the Font Picker library.
    00218  * @param   face:           IN: the font face we need details about.
    00219  * @param   sizeP:          OUT: contains total sizes for the font face
    00220  * @param   styleP:         OUT: contains total styles for the font face
    00221  *
    00222  * @retval  Nothing
    00223  *
    00224  */
    00225 extern void VMFontCountStyleAndSize(UInt16 libRefNum, VMFontFace face, Int8 *sizeP, Int8 *styleP)
    00226     VMFONTLIB_TRAP(flTrapAPIFontCountStyleAndSize);
    00227
    00228 // Font Picker functions
    00229
    00230 /**
    00231  * Initialize the font picker UI internal data structure.
    00232  * Please note that it is very important that this function
    00233  * is called before any Font picker specific functions are called.
    00234  *
    00235  * @param   libRefNum:      IN: Reference number of the Font Picker library.
    00236  *
    00237  * @retval  Nothing
    00238  *
    00239  */
    00240
    00241 extern void InitFontUI(UInt16 libRefNum)
    00242     VMFONTLIB_TRAP(flTrapAPIInitFontUI);
    00243
    00244 /**
    00245  * Popup the font picker dialog, and let the user pick a font from the
    00246  * list.  Once the user taps OK, the selected font id will be copied
    00247  * into the target parameter.
    00248  *
    00249  * @param   libRefNum:      IN:  Reference number of the Font Picker library.
    00250  * @param   fontIDP:        OUT: fontID that user has selected.
    00251  * @param   oldFontID :     IN:  The font picker will use this font to pre populate the font list.
    00252  *                               This is very useful when you have a previously saved font in
    00253  *                               the preference that you want to use when popping up the dialog.
    00254  *                               If no saved preference is used, then you can always pass in
    00255  *                               stdFont as the argument.
    00256  *
    00257  *
    00258  * @retval Boolean True if user tapped OK false if user selected cancel
    00259  */
    00260
    00261 extern Boolean DoFontDialog(UInt16 libRefNum, UInt8 *fontIDP, UInt8 oldFontID)
    00262     VMFONTLIB_TRAP(flTrapAPIDoFontDialog);
    00263
    00264
    00265 /**
    00266  * Clear the interal cache of the font library
    00267  * @param libRefNum: IN: library reference number.
    00268  */
    00269 extern void VMFontClearCache(UInt16 libRefNum)
    00270     VMFONTLIB_TRAP(flTrapAPIClearCache);
    00271
    00272 /**
    00273  * Define the UI rules, e.g.: hide style picker, do not show the style picker,
    00274  * show only small fonts, etc.
    00275  *
    00276  * @brief                   Currently the only controllable UI components are
    00277  *
    00278  *                          Components visibility controls
    00279  *                          - Font face picker: true/false
    00280  *                          - Font style picker: true/false
    00281  *                          - Font size picker: true/false
    00282  *                          List items controls
    00283  *                          - Font Size: allSize, smallFonts, largeFonts
    00284  *                          - Font Style: allStyle, plainOnly
    00285  *
    00286  * @param   libRefNum:      IN:Reference number of the Font Picker library.
    00287  * @param   fontRules:      IN:fontRules that need to be applied
    00288  *
    00289  * @retval  Nothing
    00290  *
    00291  * @code
    00292  *
    00293  * VMFontUIRules rules;
    00294  * UInt8 myFontID;
    00295  * UInt8 oldFontID;
    00296  *
    00297  * // let's hide style drop down list, and only display small fonts
    00298  * //(size 6 if available and size 9 fonts)
    00299  * rules.fontFaceVisible = true;
    00300  * rules.fontSizeVisible = true;
    00301  * rules.fontStyleVisible = true;
    00302  * rules.sizeRule = smallFonts;
    00303  * rules.styleRule = allStyle;
    00304  *
    00305  * InitFontUI( libRefNum );
    00306  * SetFontUIRules( libRefNum, rules ); // apply the rules
    00307  * if  (DoFontDialog( libRefNum, &myFontID, oldFontID ))
    00308  * {
    00309  *    // do something with the font
    00310  * }
    00311  * else
    00312  * {
    00313  *    // handle the case when user cancels out of the font picker UI
    00314  * }
    00315  * @endcode
    00316  */
    00317
    00318 extern void SetFontUIRules(UInt16 libRefNum, VMFontUIRules fontRules)
    00319     VMFONTLIB_TRAP(flTrapAPISetFontUIRules);
    00320
    00321 #ifdef __cplusplus
    00322 }
    00323 #endif
    00324
    00325 #endif

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