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