Class XbpPresSpace() Foundation

Class function of the XbpPresSpace class.

Description

Objects of the XbpPresSpace class represent presentation spaces. Presentation spaces are abstract drawing areas where graphic output is performed. A presentation space is analogous to a sheet of paper that can be drawn on. The presentation space contains all of the information required to display graphic output that is independent of the output device ("hardware independent"). This includes information such as colors, fonts, and units for the coordinate system.

All graphic output occurs in a presentation space. For the output to be visible, the presentation space must be associated with an output device (a presentation space by itself is useless). An output device is represented in Xbase++ by objects that are called "device contexts". For example, the XbpPrinter class provides a device context that is appropriate for output to a printer. A device context contains all of the information for outputting graphic that is dependent on the output device ("hardware dependent").

A presentation space is "hardware independent", a device context is "hardware dependent". The output of graphic functions or elements always occurs in a presentation space, the display is only possible using a device context. Displaying graphics requires both a presentation space and a device context.

If you are not familiar with the concepts of a presentation space and a device context, you should read the appropriate sections in the Xbase++ documentation. Reading the chapter "The Xbase++ Graphics Engine (GRA)"is also recommended.

A default presentation space linked to the device context for screen output exists in Xbase++. This presentation space is created by the function AppSys() (APPSYS.PRG file) that is executed during each application startup. The default presentation space for all graphic output is the screen or the current window. This means that no presentation space needs to be created for screen output.

A presentation space includes information for the following device independent characteristics of graphic output:

- Colors for foreground and background

- Color mix attributes

- Font

- Attributes for areas, lines, markers and text

- Coordinate system

- Unit for the coordinate system

- Image transformation

One of the most important pieces of information about a presentation space is the coordinate system. The presentation space determines the unit for measurement in the coordinate system where graphic output occurs. The unit can be pixel, centimeter, inch or an aribtrary unit.

In addition to the measurement unit, the presentation space determines the origin of the coordinate system (the point {0,0}) for the output. All graphic output is relative to the coordinate system of the presentation space. This, in turn, is relative to the coordinate system of the output device. Two coordinate systems must be considered during graphic output: the coordinate system of the presentation space and the coordinate system of the device context.

The coordinate system of the presentation space is predetermined by the page size. The page determines the available space where graphic output can occur. Since all graphic output occurs in a presentation space, this output uses the page coordinates of the presentation space.

A presentation space displays the page in the device context. It uses what is called a "viewport" to do this. The entire page of the presentation space is completely displayed in the viewport. The viewport is relative to the coordinates of the output device. This means that the size of the viewport determines what is displayed in the output device. However, the page size determines what is displayed in the presentation space.

The page size of a presentation space, as well as the size of the viewport used by the presentation space can be set. The size of the page is determined using the :setPageSize() method and the size of the viewport is defined using the :setViewPort() method. The page determines the display in the presentation space and the viewport determines the display in the output device (or the device context).

When the output is displayed on the screen, the output device usually is an XbpCrt object or an XbpDialog object. The page and the viewport of the presentation space are usually the same size as the window so that drawing is at the scale 1:1 when the unit "pixel" is used. If the output is to a printer, the page size of the presentation space is generally set to the size of a sheet of paper and metric units or inches are used for the coordinate system.

In addition to the device contexts for "screen" and "printer" there are two other output devices that can be linked to a presentation space: a raster image (bitmap) and a metafile. Device contexts for these output devices are provided by the classes XbpBitmap() and XbpMetaFile() respectively (see these classes for more information).

Class methods
:new()
Creates an instance of the XbpPresSpace class.
Configuration

The instance variables in this group configure system resources. If changes are made to these values, they must either be made before the :create() method is executed or the :configure() method must be used to activate the changes.

:mode
Adjusts precision of graphic output
Life cycle
:create()
Creates a presentation space for a device context.
:configure()
Reconfigures an existing presentation space.
:destroy()
Releases the presentation space of the XbpPresSpace object.
Manipulation
:drawMode()
Sets the drawing mode for graphic segments.
:device()
Returns the device context.
:lastError()
Returns the error code of the last graphic function called.
:mapPoint()
Maps a point from page to device space or vice versa.
:mapColor()
Maps a RGB color to a color available in the color palette.
:maxColorIndex()
Returns the number of colors that can be simultaneously defined in the color palette.
:setAttrArea()
Sets or returns the attributes for areas drawn by GraArc() and GraBox().
:setAttrLine()
Sets or returns the attributes for lines drawn with GraLine().
:setAttrMarker()
Sets or returns the attributes for markers drawn by GraMarker().
:setAttrString()
Sets or returns the attributes for characters drawn by GraStringAt().
:setColor()
Sets or returns the default colors for all graphic functions.
:setColorIndex()
Sets or returns the RGB color values for a color.
:setFont()
Sets or returns the font used to display characters drawn with GraStringAt().
:setGraTransform()
Sets or returns the graphic transformation matrix.
:setPageSize()
Sets or returns the page size in the presentation space.
:setViewPort()
Sets or returns the size of the viewport.
Examples
Scale an image using the viewport

// This example demonstrates the significance of the viewport in 
// a presentation space. A circle is drawn two times in a window 
// using the same coordinates. The first time the circle appears 
// in the middle of the window. The second time it appears at the 
// upper left, since the viewport is limited to the upper left 
// quarter of the window. When the viewport is redimensioned, images 
// can be scaled. 

PROCEDURE Main 
   LOCAL aArray, oPS 

   SetColor( "N/W" ) 
   CLS 

   oPS := SetAppWindow():presSpace() 
   GraArc( oPS, {320,200}, 100 ) 

   WAIT "Now shrink the viewport" 
   CLS 

   // Limit viewport to the upper left quarter in the window 
   aArray := oPS:setViewPort( {0,200,320,400} ) 
   GraArc( oPS, {320,200}, 100 ) 

   // Reset the viewport 
   oPS:setViewPort( aArray ) 
   WAIT 
RETURN 
Define RGB color values

// This example demonstrates how colors can be defined for 
// graphic output. A color index is defined for displaying 
// characters using the graphic primitive GraStringAt(). 
// The RGB color values for this color index are changed 
// using the method :setColorIndex(). 

#include "Gra.ch" 

#define MY_COLOR  200                // Constant for color index 

PROCEDURE Main 
   LOCAL aAttr, oPS := SetAppWindow():presSpace() 

   aAttr := Array(GRA_AS_COUNT)      // Determine the color index for 
   aAttr[ GRA_AS_COLOR ] := MY_COLOR // displaying characters 
   GraSetAttrString( oPS, aAttr ) 
                                     // Change RGB color values 
   oPS:setColorIndex( MY_COLOR, {255,127,0} ) 
   GraStringAt( oPS, {5,360}, "Colors are: {255,127,0}" ) 

   oPS:setColorIndex( MY_COLOR, {0,127,255} ) 
   GraStringAt( oPS, {5,180}, "Colors are: {0,127,255}" ) 

   AppEvent()                        // Wait for event 
RETURN 
User-defined colors

// The example demonstrates how hardware dependent color support 
// can be dealt with. The procedure InitColors() takes care of the 
// definition of user-defined colors for a presentation space object 
// and detects if a presentation space can take advantage of 
// RGB colors or if it must use a color palette. 

#include "Gra.ch" 
#include "Appevent.ch" 

STATIC saRGB := { {255,220,220}, ; 
                  {200,220,200}, ; 
                  {220,220,240}  } 

#define MY_CLR_COUNT             3 

STATIC saColors[ MY_CLR_COUNT ] 

#define MY_CLR_RED     saColors[1] 
#define MY_CLR_GREEN   saColors[2] 
#define MY_CLR_BLUE    saColors[3] 


PROCEDURE InitColors( oPS ) 
   LOCAL i, n, nColorIndex, nColorValue 

   nColorIndex := oPS:maxColorIndex( .F. ) 

   IF nColorIndex == 0 
      // We can use RGB color values. 

      FOR i:=1 TO MY_CLR_COUNT 
         saColors[i] := GraMakeRGBColor( saRGB[i] ) 
      NEXT 
   ELSE 
      FOR i:=1 TO MY_CLR_COUNT 
         nColorValue := oPS:mapColor( saRGB[i], .T. ) 

         IF nColorValue == NIL 
            // Color is not available in the color palette. 
            // Create this color! 

            oPS:setColorIndex( nColorIndex, saRGB[i] ) 
            saColors[i] := nColorIndex 
            nColorIndex -- 
         ELSE 
            saColors[i] := nColorValue 
         ENDIF 
      NEXT 
   ENDIF 
RETURN 
   
   
PROCEDURE Main 
   LOCAL oPS, aPos1, aPos2 
   
   SetColor( "N/W") 
   CLS 
   SetAppWindow():useShortCuts := .T. 

   // We have an XbpCrt window! 
   oPS := SetAppWindow():presSpace() 
   InitColors( oPS ) 

   GraSetColor( oPS, MY_CLR_RED ) 
   GraStringAt( oPS, { 10, 200 }, "MY_CLR_RED" ) 

   aPos1    := GraPos( oPS ) 
   aPos1[1] += 100 
   aPos2    := AClone( aPos1 ) 
   aPos2[1] += 100 
   aPos2[2] += 20 
   GraBox( oPS, aPos1, aPos2, GRA_FILL ) 

   GraSetColor( oPS, MY_CLR_GREEN ) 
   GraStringAt( oPS, { 10, 150 }, "MY_CLR_GREEN" ) 

   aPos1[2] -= 50 
   aPos2[2] -= 50 
   GraBox( oPS, aPos1, aPos2, GRA_FILL ) 

   GraSetColor( oPS, MY_CLR_BLUE ) 
   GraStringAt( oPS, { 10, 100 }, "MY_CLR_BLUE" ) 

   aPos1[2] -= 50 
   aPos2[2] -= 50 
   GraBox( oPS, aPos1, aPos2, GRA_FILL ) 

   WAIT 
RETURN 
Feedback

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.