Function GraSetAttrString() | Xbase++

Functions and Directives Functions and Directives

Determines attributes for characters drawn by GraStringAt().

GraSetAttrString( [<oPS>], [<aAttributes>] ) --> aOldAttributes

<oPS>

The argument <oPS> specifies the presentation space where string attributes are set. If the current window is an XbpCrt window, <oPS>is optional. If it is NIL, the return value of SetAppWindow():presSpace() is used. In all other cases <oPS> is not optional. It must be created either using XbpPresSpace():new() or a "Micro PS" must be requested from an Xbase Part using the method:lockPS(). After graphic output the Micro PS must be released with :unlockPS().

<aAttributes> := Array( GRA_AS_COUNT )

<aAttributes> is an array whose elements contain the attributes for character strings drawn by the function GraStringAt().

Array element	#define \| value	Default value
GRA_AS_COLOR	GRA_CLR_*	GRA_CLR_NEUTRAL
GRA_AS_BACKCOLOR	GRA_CLR_*	GRA_CLR_BACKGROUND
GRA_AS_MIXMODE	GRA_FGMIX_*	GRA_FGMIX_OVERPAINT
GRA_AS_BGMIXMODE	GRA_BGMIX_*	GRA_BGMIX_LEAVEALONE
GRA_AS_BOX	{ nXSize, nYSize }	dependent on output device
GRA_AS_ANGLE	{ nX, nY }	{ 1, 0 }
GRA_AS_SHEAR	{ nX, nY }	{ 0, 1 }
GRA_AS_DIRECTION	GRA_CHDIRN_*	GRA_CHDIRN_LEFTRIGHT
GRA_AS_HORIZALIGN	GRA_HALIGN_*	GRA_HALIGN_LEFT
GRA_AS_VERTALIGN	GRA_VALIGN_*	GRA_VALIGN_BASE
GRA_AS_EXTRA	nExtra	0
GRA_AS_BREAK_EXTRA	nBreakExtra	0

The function GraSetAttrString() returns a copy of the array containing the currently set character attributes. If new attributes are specified with <aAttributes>, the function returns an array containing the previous attributes.

The function GraSetAttrString() specifies the attributes for characters or character strings drawn with the function GraStringAt(). The character attributes which can be specified result in the following:

Array element	Description
GRA_AS_COLOR	Foreground color
GRA_AS_BACKCOLOR	Background color
GRA_AS_MIXMODE	Color mix attribute for foreground
GRA_AS_BGMIXMODE	Color mix attribute for background
GRA_AS_BOX	Cell size for a character
GRA_AS_ANGLE	Angle at which characters are output
GRA_AS_SHEAR	Shearing of characters (italics characters)
GRA_AS_DIRECTION	Direction for output of characters
GRA_AS_HORIZALIGN	Horizontal alignment of characters
GRA_AS_VERTALIGN	Vertical alignment of characters
GRA_AS_EXTRA	Space between characters in a character string
GRA_AS_BREAK_EXTRA	Width of a blank space (space between words)

All character attributes remain in effect until the function GraSetAttrString() is called again. The exceptions to this are the colors, which are redefined with GraSetColor().

Foreground and background color

By default, the colors set by GraSetColor() are used. For characters, a foreground and background color are specified separately. The foreground color is the color in which a character is displayed and the background color is the color for the area of the cell which surrounds a character. The background color is not displayed when the mix attribute for the background color GRA_AS_BGMIXMODE has the value GRA_BGMIX_LEAVEALONE (which is the default value).

If an outline font is set, only the outline of the character is displayed in the foreground color. The area within the border is displayed in the background color.

Mix attributes

The color mix attributes determine how the colors of characters are mixed with the colors of previously drawn graphic elements when text overwrites existing graphic output. A detailed description of the mix attributes is found in the Basics part of the Xbase++ documentation.

Windows supports only the two mix attributes GRA_BGMIX_OVERPAINT and GRA_BGMIX_LEAVEALONE for the background color.

Cell size for a character

Each character is surrounded by a rectangular area, termed the character cell. The attribute GRA_AS_BOX determines the average dimension of the cell in x and y coordinates. If the size changes, an array with two elements { nXSize, nYSize } must be entered in the array element GRA_AS_BOX of the attribute array. The first element contains the x dimension (width) of the character cell and the second element the y dimension (height) of the character cell.

The attribute GRA_AS_BOX affects only vector fonts, not bitmap fonts. When a vector font is used, the characters are scaled corresponding to the character cell. Using vector fonts, characters can be displayed compressed or stretched apart.

Angle at which characters are output

Characters or character strings can be drawn at any angle. The attribute GRA_AS_ANGLE determines the angle for the display. The angle is determined by a point {nX,nY} different from the origin of the coordinate system {0,0}. The output of characters is at the angle given by the line from the point {0,0} to the point {nX,nY} (an example is found with the function GraQueryTextBox()). The GRA_AS_ANGLE attribute has no effect on bitmap fonts.

Shearing of characters (italics characters)

The attribute GRA_AS_SHEAR indicates the angle at which characters are sheared (commonly called italic or slanted) at output. This attribute only has an effect when the current font set with GraSetFont() is a vector font. This attribute has no effect with bitmapped fonts. As with GRA_AS_ANGLE, the shear angle is determined by the angle of the line from the origin {0,0} to the specified point {nX,nY}.

Windows does not support the shearing of characters. An italic font must be set with GraSetFont() to achieve a similar effect.

Direction for the output of characters

The following table lists #define constants used for the attribute GRA_AS_DIRECTION:

Constant	Description
GRA_CHDIRN_LEFTRIGHT	Display from left to right
GRA_CHDIRN_TOPBOTTOM	Display from top to bottom
GRA_CHDIRN_RIGHTLEFT	Display from right to left
GRA_CHDIRN_BOTTOMTOP	Display from bottom to top

Windows supports only the output direction from left to right.

Alignment of characters

Characters output with GraStringAt() are aligned horizontally as well as vertically in relation to the output point. The horizontal alignment includes "left", "right", and "centered". For horizontal alignment, the following #define constants are used for the array element GRA_AS_HORIZALIGN:

Constant	Description
GRA_HALIGN_LEFT	Left aligned
GRA_HALIGN_CENTER	Centered
GRA_HALIGN_RIGHT	Right aligned

To align characters vertically, a constant from the following table must be used for the array element GRA_AS_VERTALIGN:

Constant	Description
GRA_VALIGN_TOP	Top alignment
GRA_VALIGN_HALF	Alignment at half height
GRA_VALIGN_BASE	Alignment at the base line
GRA_VALIGN_BOTTOM	Alignment bottom

Distance between characters in a character string

The attribute GRA_AS_EXTRA specifies the distance between the characters in a character string. The distance is determined by an integer whose default value is 0. When a negative value is used the distance between the characters is reduced. With a positive value, it is increased.

Width of a blank space

The attribute GRA_AS_BREAK_EXTRA determines the width of a blank space. This attribute sets the distance between two character strings (between words). The value is an integer with the default value of zero. Just like the attribute GRA_AS_EXTRA, negative values reduce the width of the blank space and positive values increase the width.

Windows does not distinguish blank spaces from characters. Therefore, the attribute GRA_AS_BREAK_EXTRA is ignored and GRA_AS_BREAK is used for blank spaces, too.

Define attributes for character strings

// In the example various character attributes are set and 
// strings are displayed with each font available. After 
// a key stroke a new font is selected. 

#include "gra.ch" 
#include "xbp.ch" 
#include "inkey.ch" 

PROCEDURE Main 
   LOCAL aAttr, aList, oFont, aOldAttr, i 

   aList := XbpFont():new():list()  // All available fonts 

   SetColor( "N/W" )                // color for CLS 

   FOR i:=1 TO Len( aList ) 

      CLS                           // fill window with pale gray 
      @ 1,1 SAY "Press a key. (ESC quits)" 

      oFont := aList[i] 
      GraSetFont( , oFont)          // set font 
      GraArc( , {320,200}, 150,,,, GRA_FILL ) 

      aAttr := ARRAY( GRA_AS_COUNT ) 
      aAttr [ GRA_AS_COLOR ]     := GRA_CLR_RED 
      aAttr [ GRA_AS_BACKCOLOR ] := GRA_CLR_BLUE 
      aAttr [ GRA_AS_MIXMODE ]   := GRA_FGMIX_OVERPAINT 
      aAttr [ GRA_AS_BGMIXMODE ] := GRA_BGMIX_OVERPAINT 

      IF i % 2 == 0                 // background color changes each 
                                    // second time through loop 
         aAttr [ GRA_AS_BGMIXMODE ] := GRA_BGMIX_OR 
      ENDIF 
                                    // set character attributes 
      aOldAttr := GraSetAttrString( , aAttr ) 

      IF i % 2 == 0 
         GraStringAt( , {10,300}, "GRA_BGMIX_LEAVEALONE" ) 
      ENDIF 

      GraStringAt( , {10,250}, oFont:compoundName ) 

      IF oFont:vector 
         aAttr [ GRA_AS_BOX ] := {40,20} 
         GraSetAttrString( , aAttr ) 

         GraStringAt( , {10,200}, "GRA_AS_BOX = { 40, 20 }" ) 

         aAttr [ GRA_AS_BOX ] := {20,40} 
         GraSetAttrString( , aAttr ) 

         GraStringAt( , {10,150}, "GRA_AS_BOX = { 20, 40 }" ) 
      ENDIF 

      aAttr [ GRA_AS_EXTRA ] := 5 
      GraSetAttrString( , aAttr ) 

      GraStringAt( , {10,100}, "Test GRA_AS_EXTRA = 5" ) 

      aAttr [ GRA_AS_BREAK_EXTRA] := 10 
      GraSetAttrString( , aAttr ) 

      GraStringAt( , {10,50}, "Test GRA_AS_BREAK_EXTRA = 10" ) 

      GraSetAttrString( , aOldAttr ) 

      IF Inkey(0) == K_ESC 
         EXIT 
      ENDIF 

   NEXT 

RETURN

Function GraSetAttrString() Foundation