Programming Guide:xppguide

Basics for graphic output Foundation

Using the GRA engine requires that an Xbase++ program be linked in for the GUI mode. Graphic output cannot be done in VIO mode. All graphic functions begin with the prefix "Gra". They often require graphic coordinates which are generally specified in "pixel units". A pixel is a dot on the screen. The default size of a window in which an Xbase++ application is run is 640x400 pixels. The origin of the graphic coordinate system (the point 0,0) is at the bottom left corner of a window.

In text mode (VIO mode), the coordinates of the screen cursor are determined using the functions Row() and Col(). The origin of the coordinate system in text mode is the upper left corner of the window and the default size of a window is 25 rows and 80 columns. When programming using graphic functions, a different graphic coordinate system must be used. It has a different origin than the text mode coordinate system, and row and column coordinates are not used. Graphic X and Y coordinates are used instead. The XY coordinates are in relation to the geometric X axis (horizontal) and Y axis (vertical).

Graphic output does not involve a screen cursor such as the one used in text mode to identify the current position on the screen. Instead, graphics mode incorporates a "pen". The pen position in graphics mode is similar to the cursor position in text mode. The pen position is defined as a point in the coordinate system and the cursor position is defined in terms of its row and column position. In graphics programming, a point is always represented by an array containing two elements which represent the X and Y coordinates for a point. The following code shows a comparison of cursor and pen position:

SetPos( 10, 20 )             // position cursor in text mode 
? Row()                      // result: 10 
? Col()                      // result: 20 

GraPos( , {20,10} )          // position pen in graphics mode 
? GraPos()                   // result: { 20, 10} 

The origin of the coordinate system for graphic output is lower left while in text mode it is upper left. The unit for the coordinate system is "pixel". One pixel (or point) is specified using a two-element array.

Graphic output generally occurs in the current window. When the output is not in a window (for example, it may be sent to a printer), the output mechanism for graphics must be taken into account. Graphic output occurs only in what is called a "presentation space".

In Xbase++, presentation spaces are provided by the XbpPresSpace() class.

A presentation space contains the part of the definition for graphic output that is independent of the output device. A graphic can look different depending on the output device used for the display. Example: he display of a graphic on the screen occurs in a window. The unit for the coordinate system is the "pixel". When the graphic is output to a printer, the unit "0.1 cm" could be selected instead of pixel. The output of the graphic on the printer would then differ considerably from the output in the window.

In the discussion of graphic output, the device independent output must be distinguished from device dependent output. A presentation space defines everything required for device independent display of graphics. This includes, for example:

- Origin and unit of the coordinate system

- Colors for the display

- Type of line for lines

- Fill pattern for areas

- Font type and size for characters

- Size of the display area

The presentation space can be thought of as an abstract drawing area for graphic output (a presentation space can also be thought of as similar to an empty piece of paper that can be drawn on). It defines all attributes for graphic output that are independent of the output device. An output device is, for example, a window (the screen) or a printer. A physical output device is called a "device context". A device context contains all device dependent attributes. To display graphic output, a presentation space (device independent) must be combined with a device context (device dependent). Nothing drawn in the presentation space is visible. Only by linking the presentation space with a device context can graphic output in the presentation space be made visible on the physical output device.

As long as graphic output occurs only in an XbpCrt window, the presentation space does not need to be dealt with because that window has a presentation space associated with it and makes the device context available. In the description of the GRA engine and its functions other windows or output devices are not considered. They are described in the chapters Presentation Spaces for Graphic Output and Graphic output devices .

In all graphic functions the first parameter specifies the presentation space for drawing. The current XbpCrt window is the default presentation space so that neither a device context nor a presentation space need to be specified when drawing in the current window. If a window is created in the default size, a drawing area of 640x350 pixels is available. The pen position is at the point {0,0} after the window is created. Drawing output always begins at the current pen position. Because it sets the pen position, the function GraPos() is an important, fundamental function of the GRA engine. Another basic function is GraError() which determines whether graphic output was successful or an error occurred.

Basic functions for the GRA engine
Function Description
GraPos() Return or set pen position
GraError() Return numeric error code for last graphic output

The GRA engine is dependent on the hardware and on installed device drivers in the same way as the operating system does. If graphic output does not occur as expected, GraError() tests whether the graphic operation is unsupported by the hardware or device driver.


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.