Function GraQueryTextBox() | Xbase++

Determines coordinates for the boundaries of a character string.

GraQueryTextBox( [<oPS>], <cString> ) --> aPoints

<oPS>

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

<cString> is a character string which is later displayed by GraStringAt().

The function GraQueryTextBox() returns a two dimensional array of five elements. Each element contains a subarray with two elements which are the relative coordinates for five points. The first four elements designate the corner points for a parallelogram which represents the boundaries of the specified character string <cString>. The fifth element is the pen position at which the pen is found after the character string is drawn with GraStringAt():

aPoints := { { nXLeft , nYTop    }, ;  // upper left corner 
             { nXLeft , nYBottom }, ;  // lower left corner 
             { nXRight, nYTop    }, ;  // upper right corner 
             { nXRight, nYBottom }, ;  // lower right corner 
             { nXPen  , nYPen    }  }  // pen position

The points designate the boundaries if the string is displayed at the origin of the coordinate system (the point {0,0}). To calculate the actual coordinates for a box surrounding a string, add the x and y positions at which <cString> is drawn.

The function GraQueryTextBox() determines the corner points of the parallelogram in which the output of a character string occurs. The coordinates describe a rectangle which outlines the character string, unless the characters are output in italic.

GraQueryTextBox() is well suited for determining the space required for a character string displayed in a proportional typeface before it is drawn with GraStringAt().

The function GraQueryTextBox() may return incorrect values when used in conjunction with a Presentation Space which is in retained mode (GRA_DM_RETAIN). In retained mode, graphical primitives are not executed, but are stored in a graphic segment. Consequently, the font and string attributes which are used by GraQueryTextBox() may be others than intended. See the function GraSegDrawMode() for further information on the segment drawing modes.

Drawing character strings with borders


// The example contains the user-defined function DrawTextBox(), 
// in which a character string is displayed with a border. For 
// demonstration the procedure main() varies the angle attributes 
// for the way in which a character string is drawn. 
// The call of GraQueryTextBox() occurs in DrawTextBox(). 

#include "Gra.ch" 

PROCEDURE Main 
   LOCAL cString, aAttr, oFont 

   SETCOLOR( "N/W" ) 
   CLS 

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

   cString := "Xbase++: Graphical text output with surrounding box" 

   DrawTextBox( {120,280}, cString) // output characters with 
                                    // border in UDF 
   GraMarker( NIL )                 // mark pen position 

   aAttr := ARRAY( GRA_AS_COUNT )   // various angle attributes 

   cString := "GRA_AS_ANGLE is {5, 3}" 

   aAttr[ GRA_AS_ANGLE ] := {5, 3}  // incline to upper right 
   GraSetAttrString( NIL, aAttr ) 
   DrawTextBox( {300, 140}, cString ) 
   GraMarker( NIL ) 

   cString := "GRA_AS_ANGLE is {5, -3}" 

   aAttr[ GRA_AS_ANGLE ] := {5, -3}  // incline to lower right 
   GraSetAttrString( NIL, aAttr ) 
   DrawTextBox( {300, 120}, cString ) 
   GraMarker( NIL ) 

   cString   := "GRA_AS_ANGLE is {-5, 3}" 

   aAttr[ GRA_AS_ANGLE ] := {-5, 3}  // incline to upper left 
   GraSetAttrString( NIL, aAttr ) 
   DrawTextBox( {290, 140}, cString ) 
   GraMarker( NIL ) 

   cString   := "GRA_AS_ANGLE is {-5, -3}" 

   aAttr[ GRA_AS_ANGLE ] := {-5, -3} // incline to lower left 
   GraSetAttrString( NIL, aAttr ) 
   DrawTextBox( {290, 120}, cString ) 
   GraMarker( NIL ) 

   INKEY(0) 

RETURN 

***************************************** 
* Draws character string with border    * 
***************************************** 
PROCEDURE DrawTextBox( aPenPos, cString ) 
   LOCAL aTextBox, aLeftTop, aLeftBottom, aRightTop, aRightBottom 

                                    // determine coordinates for 
                                    // border 
   aTextBox        := GraQueryTextBox( NIL, cString ) 

   aLeftTop        := aTextBox[1]   // relative coordinates for 
   aLeftBottom     := aTextBox[2]   // the four corner points of the 
   aRightTop       := aTextBox[3]   // parallelogram 
   aRightBottom    := aTextBox[4] 

   aLeftTop[1]     += aPenPos[1]    // convert relative coordinates 
   aLeftTop[2]     += aPenPos[2]    // to absolute coordinates 
   aLeftBottom[1]  += aPenPos[1] 
   aLeftBottom[2]  += aPenPos[2] 
   aRightTop[1]    += aPenPos[1] 
   aRightTop[2]    += aPenPos[2] 
   aRightBottom[1] += aPenPos[1] 
   aRightBottom[2] += aPenPos[2] 
                                    // draw border 
   GraLine( NIL, aLeftTop, aRightTop ) 
   GraLine( NIL, NIL, aRightBottom ) 
   GraLine( NIL, NIL, aLeftBottom ) 
   GraLine( NIL, NIL, aLeftTop ) 
                                    // draw character string 
   GraStringAt( NIL, aPenPos, cString ) 

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 GraQueryTextBox() Foundation