Method XbpPresSpace():mapPoint()

Maps a point from page to device space or vice versa.

:mapPoint( <aPoint>, ;
           [<lMapToDevice>] ) --> <aPoint>

<aPoint> := { nX, nY }

<aPoint> contains a two-dimensional array with the x and y coordinate of the point.

[<lMapToDevice>]

This parameter contains a logical value that specifies the operation to be performed by :mapPoint(). If .T. (true) is passed in this parameter, the point specified in <aPoint> is mapped from page to device space. Otherwise, <aPoint> is assumed to be a point specified in device coordinates (pixels). Parameter <lMapToDevice> is optional and defaults to .T. (true).

The method returns a two-dimensional array with the converted coordinate. If .T. is passed in <lMapToDevice>, both elements of the array are specified in device units. If <lMapToDevice> contains .F., :mapPoint()returns the point in page units.

The method :mapPoint() can be used to convert points between device units (pixels) and the units defined in page space. The coordinate system to be used in the abstract page is defined by the application when the method :create() is called. If the whole output rectangle of the device associated with the PS is to be filled using the GraBox() primitive, for example, method :mapPoint() can be used to determine the end point for the operation, notwithstanding the units selected for the PS.

:mapPoint() respects the current page-to-device transform as well as a transform matrix set using :setGraTransform(). If <lbMapToDevice> is .T., both transforms are applied to the point specified and return is the resulting coordinate in device units (pixel). If <lMapToDevice> is .F., both the inverse of the page-to-device transform and the transform matrix, if set, are applied to <aPoint>. Return is the coordinate in page units that selects the pixel originally specified in <aPoint>.

// 
// Example of using :mapPoint() to determine the 
// device resolution of a printer 
// 
#include "Gra.ch" 

PROCEDURE Main 
   LOCAL oPS 
   LOCAL oDC 
   LOCAL aPoint 

   // Create presentation space for default printer. 
   oPS := PrinterPS() 

   // Select 0.01 Inch units to be used in the 
   // abstract page. 
   oPS:setPageSize( {100,100}, GRA_PU_LOENGLISH ) 

   // Use :mapPoint() to compute the DPI (dots 
   // per Inch) resolution of the printer device. 
   // After the conversion, the coordinate 
   // is equivalent to the number of device units 
   // that span a box that is one Inch across. 
   aPoint := oPS:mapPoint( {100,100}, .T. ) 

   ? "Printer's DPI resolution is: " + LTrim( Str(aPoint[1]) ) 
   WAIT 

   DestroyDevice( oPS ) 
RETURN 

// Create presentation space and link to 
// device context for printer. 
// 
FUNCTION PrinterPS( cPrinterObjectName ) 
   LOCAL oPS, oDC := XbpPrinter():New() 
   LOCAL aSize 

   oDC:Create( cPrinterObjectName ) 

   oPS := XbpPresSpace():New() 
   aSize := oDC:paperSize() 

   // Size of printable region on paper 
   aSize := { aSize[5] - aSize[3], ; 
              aSize[6] - aSize[4]  } 
   oPS:Create( oDC, aSize, GRA_PU_LOMETRIC ) 
RETURN oPS 

PROCEDURE DestroyDevice( oPS ) 
   LOCAL oDC := oPS:device() 

   IF oDC <> NIL 
      oPS:configure() 
      oDC:destroy() 
   ENDIF 
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.

Method XbpPresSpace():mapPoint() Foundation