API Guide Home
(Online version only)

Header Files » Incs » 68k » libraries » vmfont

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

Functions

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