API Guide Home (Online version only) |

# palmOneVMFontLib.h File Reference

## Detailed Description

Defines APIs and structures for the Palm VersaMail Font Picker / Font Manager Service which lets users get / set font characteristics.

Version:
  1.0

Definition in file palmOneVMFontLib.h.

Include dependency graph for palmOneVMFontLib.h:

Go to the source code of this file.

## Defines

- #define VMFONTLIB_TRAP(trapNum) SYS_TRAP( trapNum )

## Functions

- Err VMFontOpen (UInt16 libRefNum, UInt32 *clientContextP)
    This function should be called prior to calling the other Font Picker functions.
- Err VMFontClose (UInt16 libRefNum, UInt32 clientContext)
    This function should be called after your application has finished with the Font Picker library.
- Err VMFontVersion (UInt16 libRefNum, UInt32 *versionP)
- UInt8 VMFontGetFont (UInt16 libRefNum, const VMFontPtr fontP)
- UInt8 VMFontGetFontByID (UInt16 libRefNum, VMFontPtr targetP, UInt8 fontID)
- Boolean VMFontExists (UInt16 libRefNum, const VMFontPtr fontP)
- void VMFontToString (UInt16 libRefNum, const VMFontPtr fontP, char *stringP)
- void VMFontCountStyleAndSize (UInt16 libRefNum, VMFontFace face, Int8 *sizeP, Int8 *styleP)
- void InitFontUI (UInt16 libRefNum)
- Boolean DoFontDialog (UInt16 libRefNum, UInt8 *fontIDP, UInt8 oldFontID)
- void VMFontClearCache (UInt16 libRefNum)
- void SetFontUIRules (UInt16 libRefNum, VMFontUIRules fontRules)
    Currently the only controllable UI components are.

## Define Documentation

#define VMFONTLIB_TRAP | ( | trapNum |  | ) | SYS_TRAP( trapNum )

Definition at line 29 of file palmOneVMFontLib.h.

## Function Documentation

Boolean DoFontDialog | ( | UInt16 | libRefNum,
|  | UInt8 * | fontIDP,
|  | UInt8 | oldFontID |
| ) |  |  |

Popup the font picker dialog, and let the user pick a font from the list. Once the user taps OK, the selected font id will be copied into the target parameter.

Parameters:

  | libRefNum,: | IN: Reference number of the Font Picker library.
  | fontIDP,: | OUT: fontID that user has selected.
  | oldFontID | : IN: The font picker will use this font to pre populate the font list. This is very useful when you have a previously saved font in the preference that you want to use when popping up the dialog. If no saved preference is used, then you can always pass in stdFont as the argument.

Return values:

  | Boolean | True if user tapped OK false if user selected cancel

void InitFontUI | ( | UInt16 | libRefNum | ) |

Initialize the font picker UI internal data structure. Please note that it is very important that this function is called before any Font picker specific functions are called.

Parameters:

  | libRefNum,: | IN: Reference number of the Font Picker library.

Return values:

  | Nothing |

void SetFontUIRules | ( | UInt16 | libRefNum,
|  | VMFontUIRules | fontRules |
| ) |  |  |

Currently the only controllable UI components are.

Define the UI rules, e.g.: hide style picker, do not show the style picker, show only small fonts, etc.

Components visibility controls

- Font face picker: true/false
- Font style picker: true/false
- Font size picker: true/false List items controls
- Font Size: allSize, smallFonts, largeFonts
- Font Style: allStyle, plainOnly

Parameters:

  | libRefNum,: | IN:Reference number of the Font Picker library.
  | fontRules,: | IN:fontRules that need to be applied

Return values:

  | Nothing |
       VMFontUIRules rules;
       UInt8 myFontID;
       UInt8 oldFontID;

       // let's hide style drop down list, and only display small fonts
       //(size 6 if available and size 9 fonts)
       rules.fontFaceVisible = true;
       rules.fontSizeVisible = true;
       rules.fontStyleVisible = true;
       rules.sizeRule = smallFonts;
       rules.styleRule = allStyle;

       InitFontUI( libRefNum );
       SetFontUIRules( libRefNum, rules ); // apply the rules
       if  (DoFontDialog( libRefNum, &myFontID, oldFontID ))
       {
          // do something with the font
       }
       else
       {
          // handle the case when user cancels out of the font picker UI
       }

void VMFontClearCache | ( | UInt16 | libRefNum | ) |

Clear the interal cache of the font library

Parameters:

  | libRefNum,: | IN: library reference number.

Err VMFontClose | ( | UInt16 | libRefNum,
|  | UInt32 | clientContext |
| ) |  |  |

This function should be called after your application has finished with the Font Picker library.

Closes the Font Picker library and perform cleanup.

Parameters:

  | libRefNum,: | IN: Reference number of the Font Picker library.
  | clientContext,: | IN: Library's client context number got during open.

Return values:

  | Err | The error code returned from the library. If this is errNone, the function was sucessful.

     err = VMFontClose(fontPickerLibRefNum, context);

See also:
  VMFontOpen

void VMFontCountStyleAndSize | ( | UInt16 | libRefNum,
|  | VMFontFace | face,
|  | Int8 * | sizeP,
|  | Int8 * | styleP |
| ) |  |  |

Given a font face, find out how many size/styles were associated with it.

Parameters:

  | libRefNum,: | IN: Reference number of the Font Picker library.
  | face,: | IN: the font face we need details about.
  | sizeP,: | OUT: contains total sizes for the font face
  | styleP,: | OUT: contains total styles for the font face

Return values:

  | Nothing |

Boolean VMFontExists | ( | UInt16 | libRefNum,
|  | const VMFontPtr | fontP |
| ) |  |  |

Check to see if the specified font exists in the database.

Parameters:

  | libRefNum,: | IN: Reference number of the Font Picker library.
  | fontP,: | IN: the font characteristics we want to check.

Return values:

  | Boolean | True if the font exists in the database, false otherwise.

     MemHandle handle;
     VMFontPtr fontP;
     Boolean exists = false;

     handle = MemHandleNew(sizeof( VMFontType ));
     fontP = (VMFontPtr) MemHandleLock(handle);

     fontP->face = segoe;
     fontP->size = size6;
     fontP->style = bold;

     exists = VMFontExists( gRefNum, fontP );

     MemHandleUnlock(handle);
     MemHandleFree(handle);

See also:
  VMFontGetFont

UInt8 VMFontGetFont | ( | UInt16 | libRefNum,
|  | const VMFontPtr | fontP |
| ) |  |  |

Get the font ID based on the given font characteristics. The returned font ID is NOT guaranteed to be always available. Therefore to avoid any error, please make sure that VMFontExists is used whenever a font is needed.

Parameters:

  | libRefNum,: | IN: Reference number of the Font Picker library.
  | fontP,: | IN: the font characteristics.

Return values:

  | UInt8 | The defined font ID

     // get the font ID for gill Sans MT 9 pt Italic
     VMFontPtr fontP = (VMFontPtr) MemPtrNew (sizeof (VMFontType));
     fontP->face = gillSans;
     fontP->size = size6;
     fontP->style = italic;
     UInt8 myFontID = stdFont;
     if (VMFontExists( theRefNum, fontP ))
        {    myFontID = VMFontGetFont( theRefNum, fontP );   }

See also:
  VMFontExists

UInt8 VMFontGetFontByID | ( | UInt16 | libRefNum,
|  | VMFontPtr | targetP,
|  | UInt8 | fontID |
| ) |  |  |

Get the Font characteristics based on a saved FontID

Parameters:

  | libRefNum,: | IN: Reference number of the Font Picker library.
  | targetP,: | IN: the font characteristics.
  | fontID,: | IN: the font ID passed in.

Return values:

  | UInt8 | The defined font ID

     UInt8 myOldID;
     UInt8 myFontID;
     MemHandle handle;
     VMFontPtr fontP;

     handle = MemHandleNew(sizeof(VMFontType));
     fontP = (VMFontPtr) MemHandleLock(handle);

     myOldID = GetFontIDFromPrefs(); // assume that we have a funct to get the old ID
     myFontID = VMFontGetFontByID( gRefNum, fontP, myOldID );

Err VMFontOpen | ( | UInt16 | libRefNum,
|  | UInt32 * | clientContextP |
| ) |  |  |

This function should be called prior to calling the other Font Picker functions.

Opens the Font Picker library. Does Initialization of library.

Parameters:

  | libRefNum,: | IN: Reference number of the Font Picker library.
  | clientContextP,: | OUT: pointer to variable for returning client context. The client context is used to maintain client-specific data for multiple client support.The value returned here will be used as a parameter for other library functions which require a client context.

Return values:

  | Err | The error code returned from the library. If this is errNone, the function was sucessful.

     UInt16 fontPickerLibRefNum = 0;
     UInt32 context;
     err = SysLibFind(fontPickerLibName, &fontPickerLibRefNum);
     if( err == sysErrLibNotFound )
     {
         err = SysLibLoad(fontPickerType, fontPickerCreatorID, &fontPickerLibRefNum);
             if( !err ) {
                 err = VMFontOpen(fontPickerLibRefNum, &context);
             }
     }

See also:
  VMFontClose

void VMFontToString | ( | UInt16 | libRefNum,
|  | const VMFontPtr | fontP,
|  | char * | stringP |
| ) |  |  |

Given a font characteristics (defined as VMFontPtr), get the human-readable font description of that font in the form of "<NAME> <SIZE> <STYLE>", e.g. "Gill Sans MT 9 Bold".

Parameters:

  | libRefNum,: | IN: Reference number of the Font Picker library.
  | fontP,: | IN: the font characteristics we want to check.
  | stringP,: | OUT: Pointer to output string buffer.

Return values:

  | Nothing |

Err VMFontVersion | ( | UInt16 | libRefNum,
|  | UInt32 * | versionP |
| ) |  |  |

Get the Font Library Version

Parameters:

  | libRefNum,: | IN: Reference number of the Font Picker library.
  | versionP,: | OUT: Pointer to the version number

Return values:

  | Err | Always errNone

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