Class XbpFont() Foundation

Class function of the XbpFont class.

Description

Objects of the XbpFont class allow the fonts for character output to be selected and managed. Fonts can be defined for character output on the screen or any other output device. XbpFont objects are required by the Xbase++ graphics engine (GRA) functions in order to display different fonts. The most important GRA functions for displaying different fonts on the screen are GraSetFont(), GraSetAttrString(), GraStringAt()and GraQueryTextBox() (see each of these functions for more information on their capabilities). Other Xbase Parts, for example XbpPushButton and XbpCheckBox, also use XbpFont objects for text output on the screen.

The XbpFont class provide programmers an easy way to select different fonts. In order to use different fonts, XbpFont objects must be created. This is done when the class object generates a new XbpFont object via the class method :new(). After an XbpFont object is created, values describing the desired font must be assigned to the instance variables of the XbpFont object. The corresponding font then needs to be created before it can be used. This is comparable to opening a file. If a file already exists, the information in it can be used only after the file is opened.

Fonts are requested using the :create() method of the XbpFont object. This passes the description of the desired font to the operating system which actually provides the font. Whether a font is successfully requested can be determined using the :status()method. This method returns the value of the #define constant XBP_STAT_CREATE when the font is available (all #define constants for Xbase Parts are in the #include file XBP.CH). If the definition of the desired font does not match an existing font, the available font that has the "best fit" (the closest match) with the definition is selected.

The values in the instance variables of the XbpFont object may be different before and after the font is created. Before the method :create() is executed, these instance variables contain the values for the desired font. After the :create() method terminates, these instance variables contain values describing the font actually created.

After the font is loaded, it is available within the Xbase++ program. However, since several fonts can be loaded at the same time, the desired font for the display must be specified by assigning the font object to the GRA module. This occurs using the function GraSetFont(). Characters are output in the current font using the function GraStringAt(). The basic mechanism for installing and using a font is shown in the following lines of code:

oFont := XbpFont():new()              // Create XbpFont object 

oFont:familyName := "Times New Roman" // Describe font 
oFont:height     := 16 
oFont:width      :=  8 

oFont:create()                        // Create font 

GraSetFont ( , oFont )                // Select font 
GraStringAt( , {10,300}, "Font" )     // Output characters 

Using fonts extensively requires knowledge of "presentation spaces" (see XbpPresSpace() for more information). This is an Xbase Part that provides an abstract drawing surface where characters can be output using any font (a presentation space is analogous to a blank sheet of paper).

A presentation space is generally required to output fonts to the printer. A context device is also required and is provided by the XbpPrinter() class. See the chapter "Graphic output devices" in the the Xbase++ documentation.

Displaying or printing characters in different fonts is by nature a very complex task. The difficulty lies not only in the large number of possible fonts but in the fact that the available fonts depend on the capabilities of the hardware. The operating system provides a number of system fonts that can be used with most hardware installations. Special device dependent fonts can include a large number of possible parameters that describe the font. For this reason creation of a specific font cannot be guaranteed. To ensure that the correct font was created, the values of the instance variable of the XbpFont after the font is created should be compared with the description of the desired font. In the examples at the end of this discussion, a program is shown that determines the parameters of all fonts available on the particular computer system, writes this to a DBF file and allows it to be viewed on the screen. These parameters can be used as values for describing and selecting a font.

The XbpFontDialog class provides the standard font dialog that allows fonts to be selected and installed by the user at runtime (see XbpFontDialog() for more information).

Class methods
:new()
Creates an instance of the XbpFont class.
Instance variables
:antiAliased
Determines whether the font is an "antialiased" font.
:baseLine
Determines the base line for the font.
:bold
Determines whether the font is "Bold".
:codePage
Determines the code page (character set) for which the font can be used.
:compoundName
Determines the font family and font attributes.
:dbcs
Determines whether the font uses a "double byte character set" (DBCS).
:familyName
Determines the name of the font family (for example, "Times New Roman").
:fixed
Determines whether the font is a non-proportional font.
:generic
Determines whether the font is a device independent font.
:height
Determines the height of a font.
:italic
Determines whether the font is an italic font.
:kerning
Determines whether a font has "kerning" information.
:mbcs
Determines whether the font uses a "mixed byte character set" (MBCS).
:nominalPointSize
Determines the type size of the font in points.
:outlined
Determines whether the font is an outline font.
:strikeout
Determines whether the font is a "strikeout" font.
:underscore
Determines whether the font is an "underscored" font.
:vector
Determines whether the font is a vector font.
:weightClass
Determines the weight or thickness of a font.
:width
Determines the width of font characters.
:widthClass
Determines the distance between two characters of the font.
Life cycle
:create()
Selects a font that corresponds with the instance variables of the XbpFont object.
:configure()
Installs a font corresponding to the updated instance variable values of the XbpFont object.
:destroy()
Unloads the font and releases the memory used by the font.
Methods
:getIFont()
Return font as an IFont automation object.
:list()
Creates an array containing matching XbpFont objects.
:setIFont()
Initialize font through an IFont automation object.
Examples
Display various system fonts

// This example sequentially selects various system fonts 
// and displays the font name as a sample. 

#include "Font.ch" 

PROCEDURE  Main 
   LOCAL oFont, aSettings, i, imax 

   aSettings := { ; 
      FONT_DEFFIXED_SMALL , ; 
      FONT_DEFPROP_MEDIUM , ; 
      FONT_HELV_LARGE     , ; 
      FONT_TIMES_SMALL    , ; 
      FONT_TIMES_MEDIUM   , ; 
      FONT_TIMES_LARGE    , ; 
      FONT_TIMES_XLARGE + FONT_STYLE_BOLD , ; 
      FONT_TIMES_XLARGE + FONT_STYLE_ITALIC + FONT_STYLE_BOLD  ; 
   } 

   SETCOLOR( "N/W" ) 
   CLS 

   imax   := LEN(aSettings) 
   oFont  := XbpFont():new()             // Create font object 
   oFont:create()                        // and font 

   FOR i:=1 TO imax 
      oFont:configure( aSettings[i] )    // Load new font 

      GraSetFont ( , oFont )             // Set current font 

      graStringAt( , {10, 360 - 30* i } , ;       // Graphics x,y 
                  STR(oFont:nominalPointSize,2)+; // coordinates! 
                   "." + oFont:compoundName   )    
   NEXT 

   SETPOS( MAXROW()-1, 0 ) 
   WAIT "Press a key" 

RETURN 
Write the attributes of available system fonts into a DBF file

// In this example, an XbpFont object is created and the method 
// :list() is immediately executed. This creates an array 
// containing XbpFont objects that describe all available 
// system fonts. The instance variables of the XbpFont objects 
// are written into a DBF file and displayed. 

#include "inkey.ch" 

PROCEDURE Main 
   LOCAL oFont, aFontList, aStruct, aIVars, oTbrowse, oColumn 

   oFont         := XbpFont():New() // Create XbpFont object 
   aFontList     := oFont:list()    // Create array of fonts 
   oFont:familyName:= "Default values of font object" 

   AINS( aFontList, 1, oFont )      // Insert XbpFont object at 
                                    // the beginning of the list. 
   aIVars := { ;                    // Code to access all of the 
      {|o| o:antiAliased      }, ;  // instance variables of an 
      {|o| o:baseLine         }, ;  // XbpFont object in code 
      {|o| o:bold             }, ;  // blocks. 
      {|o| o:codePage         }, ; 
      {|o| o:compoundName     }, ; 
      {|o| o:dbcs             }, ; 
      {|o| o:familyName       }, ; 
      {|o| o:fixed            }, ; 
      {|o| o:generic          }, ; 
      {|o| o:height           }, ; 
      {|o| o:italic           }, ; 
      {|o| o:kerning          }, ; 
      {|o| o:mbcs             }, ; 
      {|o| o:nominalPointSize }, ; 
      {|o| o:outlined         }, ; 
      {|o| o:strikeout        }, ; 
      {|o| o:underscore       }, ; 
      {|o| o:vector           }, ; 
      {|o| o:weightClass      }, ; 
      {|o| o:width            }, ; 
      {|o| o:widthClass       }  ; 
   } 

   aStruct := { ;                   // Structure for DBF file 
      { "antiAlias"  , "L", 1, 0 }, ; 
      { "baseLine"   , "N", 3, 0 }, ; 
      { "bold"       , "L", 1, 0 }, ; 
      { "codePage"   , "N", 5, 0 }, ; 
      { "compName"   , "C",32, 0 }, ; 
      { "dbcs"       , "L", 1, 0 }, ; 
      { "familyName" , "C",32, 0 }, ; 
      { "fixed"      , "L", 1, 0 }, ; 
      { "generic"    , "L", 1, 0 }, ; 
      { "height"     , "N", 3, 0 }, ; 
      { "italic"     , "L", 1, 0 }, ; 
      { "kerning"    , "L", 1, 0 }, ; 
      { "mbcs"       , "L", 1, 0 }, ; 
      { "pointSize"  , "N", 3, 0 }, ; 
      { "outlined"   , "L", 1, 0 }, ; 
      { "strikeout"  , "L", 1, 0 }, ; 
      { "underscore" , "L", 1, 0 }, ; 
      { "vector"     , "L", 1, 0 }, ; 
      { "weightClas" , "N", 3, 0 }, ; 
      { "width"      , "N", 3, 0 }, ; 
      { "widthClass" , "N", 3, 0 }  ; 
   } 

   DBCREATE("FONTS", aStruct)            // Create and open 
   USE Fonts                             // DBF file 

   AEVAL( aFontList, ;                   // Import all fonts into 
          {|o| oFont := o, DBAPPEND(), ; // file. Write instance 
               AEVAL( aIVars, ;          // variables to fields 
                      {|b,i| FIELDPUT(i, EVAL(b,oFont)) } ; 
                    ) ;                  // in the file 
          } ; 
        ) 

   oTBrowse := TBROWSEDB(2, 2, 22, 77)   // Create Tbrowse 
   AEVAL( DBSTRUCT(), ;                  // object 
          {|a| oTBrowse:AddColumn( ;     // Add columns 
               TBColumnNew(a[1], &("{||"+a[1]+"}")) ); 
          } ; 
        ) 

   oColumn  := oTbrowse:delColumn( 5 ) // Place column with 
   oTBrowse:insColumn( 1, oColumn )    // :compoundName at left 
   oTBrowse:freeze := 1                // and freeze 

   DISPBOX(1, 1, 23, 78, 1 ) 

   DO WHILE LASTKEY() <> K_ESC         // browse 
      DO WHILE ! oTBrowse:stabilize() 
         IF (nKey := INKEY()) <> 0 
            EXIT 
         ENDIF 
      ENDDO 

      IF oTBrowse:stable 
         nKey := INKEY(0) 
      ENDIF 

      TBNavigate(oTBrowse, nKey) 
   ENDDO 

RETURN 

********************************* 
PROCEDURE TBNavigate( oTB, nKey ) 

   DO CASE 
   CASE nKey == K_DOWN       ; oTB:down() 
   CASE nKey == K_PGDN       ; oTB:pageDown() 
   CASE nKey == K_CTRL_PGDN  ; oTB:goBottom() 
   CASE nKey == K_LEFT       ; oTB:left() 
   CASE nKey == K_CTRL_LEFT  ; oTB:panLeft() 
   CASE nKey == K_HOME       ; oTB:home() 
   CASE nKey == K_CTRL_HOME  ; oTB:panHome() 
   CASE nKey == K_RIGHT      ; oTB:right() 
   CASE nKey == K_CTRL_RIGHT ; oTB:panRight() 
   CASE nKey == K_END        ; oTB:_end() 
   CASE nKey == K_CTRL_END   ; oTB:panEnd() 
   CASE nKey == K_UP         ; oTB:up() 
   CASE nKey == K_PGUP       ; oTB:pageUp() 
   CASE nKey == K_CTRL_PGUP  ; oTB:goTop() 
   ENDCASE 

RETURN 

Feedback

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.