Function GraStringAt() | Xbase++

Displays character string using a graphic function.

GraStringAt( [<oPS>], [<aPoint>], <cString> ) --> lSuccess

<oPS>

The argument <oPS> specifies the presentation space in which a character string is output. 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().

<aPoint>:= { <nX>, <nY> }

<aPoint> is an array of two elements which determines the coordinates for the point at which the character string is drawn. The first element <nX> specifies the x coordinate and the second element <nY> specifies the y coordinate. The unit for the coordinates depends on the coordinate system defined for the presentation space. If no presentation space is specified, the values for the coordinates are specified in pixels, which is the unit for a window. The origin for the coordinates (the point {0,0}) is at the lower left. If <aPoint> is not specified, the character string is drawn at the current pen position.

<cString> is the character string which is drawn.

The return value of GraStringAt() is .T. (true) if the character string was drawn, otherwise it is .F. (false). If the return value equals .F., the cause of the error can be determined using GraError().

The function GraStringAt() draws characters or character strings using graphic functions. After output the pen position is at the end of the character string. GraStringAt() differs from QOut() and DispOut() in that GraStringAt() cannot be used in the VIO-mode (text mode). The graphic output of characters occurs using an XbpFont object which makes a font available. GraStringAt() always uses the font set by GraSetFont().

The space required for output of a characters string varies depending on which font is active. For exact positioning of characters, the coordinates for the area required to display a character string is determined with the function GraQueryTextBox().

Since the display of characters occurs using graphic primitives, the function GraStringAt() can also be called within a graphic segment. The character string <cString> is then displayed each time the function GraSegDraw() is executed. If a segment is scaled or rotated, a vector font must be active since these types of graphic transformations cannot be executed with bitmap fonts.

Using the function GraSetAttrString(), the display of characters of a vector font can be modified in several ways.

Drawing a character string

// In the example attributes for the display of character strings 
// are varied and the applicable attribute is shown on screen with 
// GraStringAt(). The attributes in the example can only be 
// displayed using a vector font. 

#include "Gra.ch" 
#include "Xbp.ch" 

PROCEDURE Main 
   LOCAL aAttr, oFont 

   SetColor( "N/W" )                // fill window with pale gray 
   CLS 

   #ifdef __OS2__                   // create vector font object 
      oFont := XbpFont():new():create( "12.Helv.normal" ) 
   #else 
      oFont := XbpFont():new():create( "12.Arial.normal" ) 
   #endif 
   GraSetFont( NIL, oFont )         // install font 

   GraStringAt( NIL, {50, 350}, "Default string attributes" ) 

   aAttr := ARRAY( GRA_AS_COUNT )   // set various attributes 
   aAttr [ GRA_AS_BOX       ] := { 15, 30 } 
   aAttr [ GRA_AS_COLOR     ] := GRA_CLR_RED 
   GraSetAttrString( NIL, aAttr ) 

                                    // enlarged display 
   GraStringAt( NIL, {100, 200}, "GRA_AS_BOX = { 15, 30 }" ) 

   aAttr [ GRA_AS_BOX        ] := { 8, 16 } 
   aAttr [ GRA_AS_HORIZALIGN ] := GRA_HALIGN_CENTER 
   aAttr [ GRA_AS_COLOR      ] := GRA_CLR_GREEN 
   GraSetAttrString( NIL, aAttr ) 

   GraStringAt( NIL, {100, 100}, "GRA_HALIGN_CENTER" ) 
   GraMarker  ( NIL, {100, 100} )   // centered at given point 

   aAttr [ GRA_AS_ANGLE ] := { 4, 2 } 
   aAttr [ GRA_AS_COLOR ] := GRA_CLR_CYAN 
   GraSetAttrString( NIL, aAttr ) 
                                    // output slanted upward 
   GraStringAt( NIL, {100,  50}, "GRA_AS_ANGLE = { 4, 2 }" ) 
   GraMarker  ( NIL, {100,  50} ) 

   Inkey(0)                         // wait for key press 

RETURN

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.

Function GraStringAt() Foundation