Function GraTranslate() | Xbase++

Functions and Directives Functions and Directives

Calculates translation (shift) transformation for a matrix.

GraTranslate( [<oPS>], <aMatrix>, ;
              <nXDiff>, <nYDiff>, [<nMode>] ) --> lSuccess

<oPS>

The argument <oPS> specifies the presentation space whose coordinate system is used to calculate the translation transformation. 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().

<aMatrix> := GraInitMatrix()

The parameter <aMatrix> is a three dimensional array that holds the transformation matrix. It must first be created by GraInitMatrix().

<nXDiff> is a numeric value which determines the translation (shift) in the x direction.

<nYdiff> is a numeric value which determines the translation (shift) in the y direction.

<nMode>

For the optional parameter <nMode>, only the #define constants listed in the following table can be used:

Constant	Description
GRA_TRANSFORM_REPLACE	Replaces the <aMatrix> transformation after the transformation
GRA_TRANSFORM_ADD	Keeps the existing <aMatrix> transformation and calculates an additional transformation
The default value is GRA_TRANSFORM_REPLACE.

The return value of GraTranslate() is .T. (true) if the translation transformation was calculated, otherwise it is .F. (false). If the return value equals .F., the cause of error can be determined using GraError().

The function GraTranslate() completes the matrix calculations required for the translation (shift) of graphic segments. A matrix must be passed to the function to hold the values resulting from the calculations. This matrix is a three dimensional array which must first be created by GraInitMatrix() before it can be used for matrix calculations.

Graphic segments moved by a specific amount must have been previously created with graphic primitives. The functions GraSegOpen() and GraSegClose() are used to define a graphic segment. GraTranslate() calculates the shift and the function GraSegDraw() makes the shift visible.

No matrix transformations can be calculated for raster images (bitmaps). To move raster images the function GraBitBlt() must be used.

Moving a graphic segment


// The example demonstrates how a graphic segment is shifted 
// by a translation. The segment draws a character string. 
// It is displayed first in the lower left of the window. 
// Then the segment is output at the upper right and the 
// character string is moved from the bottom. 

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

PROCEDURE Main 
   LOCAL aAttr  , oFont , aTextBox, aMatrix 
   LOCAL cString, nXDiff, nYDiff  , nXMax, nYMax, nSegment, i 

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

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

   cString  := "XBASE++"            // establish coordinates for 
   aTextBox := GraQueryTextBox( NIL, cString ) // string 

   aMatrix  := GraInitMatrix()      // get transformation matrix 
   nSegment := GraSegOpen()         // create segment 
      GraStringAt( NIL, {0,5}, cString ) 
   GraSegClose()                    // string is displayed at 
                                    // lower left 
                                    // Size in x and y direction 
   nXMax  := SetAppWindow():currentSize()[1] 
   nYMax  := SetAppWindow():currentSize()[2] 
   nXDiff := nXMax-aTextBox[3,1]    // draw string upper right 
   nYDiff := nYMax-aTextBox[1,2]    // replace matrix transformation 
   GraTranslate( NIL, aMatrix, nXDiff, nYdiff, GRA_TRANSFORM_REPLACE) 
   GraSegDraw( NIL, nSegment, aMatrix ) 

   aAttr [ GRA_AS_MIXMODE ] := GRA_FGMIX_XOR 
   GraSetAttrString( NIL, aAttr )   // set mix attributes 

   nXDiff := nXMax / 2              // draw string at 
   nYDiff := 0                      // lower middle 
   GraTranslate( NIL, aMatrix, nXDiff, nYdiff, GRA_TRANSFORM_REPLACE) 
   GraSegDraw( NIL, nSegment, aMatrix ) 

   nXDiff := 0                      // shift middle string to top 
   nYDiff := 4                      // calculate matrix 
   FOR i:=1 TO 45                   // by addition 
      GraSegDraw( NIL, nSegment, aMatrix ) // delete string 
      GraTranslate( NIL, aMatrix, nXDiff, nYDiff, GRA_TRANSFORM_ADD) 
      GraSegDraw( NIL, nSegment, aMatrix ) // display string 
      Sleep(10) 
   NEXT 

   Inkey(0) 

RETURN

Function GraTranslate() Foundation