Class XbpPresSpace() Foundation

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 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).

// 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 

// 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 

// 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