GRAPHIC Code Group

Purpose

The GRAPHIC Code Group offers statements and functions which display text and graphics on a GRAPHIC TARGET (this could be a Graphic Window or a Graphic Bitmap). In addition, it provides a wide variety of support to manage and interact with these items.

Syntax

GRAPHIC DirectorWord [params]

GRAPHIC DirectorWord [params] TO ReturnVariable(s)

Function Form:

ReturnVariable = GRAPHIC (DirectorWord [,params])

ReturnVariable$ = GRAPHIC$ (DirectorWord [,params])

Remarks

Some of the functionality of the GRAPHIC group was available in prior versions of PowerBASIC, but it has now been expanded. Some Graphic Procedures (namely those which return a single value) may be used in two forms, a statement with a TO clause, or a function which may be used as a term in an expression:

GRAPHIC GET LINES TO LineCountVar&

LineCountVar& = GRAPHIC(LINES)

The two examples above are functionally identical. The choice is simply a matter of your personal preference. If you use the second form (as a function which returns a value), it can be a term in any expression of any complexity. When a function form is available, it is labeled with the prefix "Function Form".

Some Graphic procedures return two or more values. As it is not possible to simultaneously inject multiple terms into a valid expression, the function option is not available for them.

GRAPHIC TARGET

The term GRAPHIC TARGET refers to a Graphic Bitmap or a Graphic Window. You may want to think of a graphic target as your painter's canvas, where you display any amount of text and graphics. Many graphic targets may exist simultaneously, but only one is attached to the graphic stream at a time. The attached graphic target is the one acted upon by graphic code.

Graphic Bitmap	This is a non-visible target typically used as a work area to construct an image prior to displaying it. You can create a new, blank bitmap with GRAPHIC BITMAP NEW, or load one from a resource or disk file with GRAPHIC BITMAP LOAD. At that point, other graphic code can be used to act on it.
Graphic Window	This is a standalone window which can be placed at any location on the desktop. It's created with GRAPHIC WINDOW and can even be used as a graphical console window. Once you attach this window, you can display all forms of text and graphics on it.

GRAPHIC STREAM

The Graphic Stream is the connection between graphic code and a graphic target. The Graphic Stream is created when you attach a particular target with GRAPHIC ATTACH. From that moment forward, all graphic code acts on that selected target. This continues until such time as you select a new graphic target. When this occurs, the graphic stream to the first target is disabled, and a new graphic stream to the new target is created.

You can redirect the graphic stream to different graphic targets as often as necessary for the logic of your program.

PAGE UNITS

PAGE UNITS are used to measure the size of a graphical item, or to define a particular position on a graphic target. You can define page units to be pixels, dialog units, or scaled units of your choice.

Initially, each graphic target inherits the page unit size from its parent: pixels or dialog units. You can change this to scaled world coordinates of your choice with GRAPHIC SCALE. You can revert from dialog units or scaled units back to pixels (the most accurate form) by executing GRAPHIC SCALE PIXELS.

By default, the upper left corner of a graphic target is considered to be the X,Y position 0,0 and grows larger to the right or downward. The X axis is horizontal, while the Y axis is vertical. Whenever an X,Y position is given, the X value is stated first. Both the limits and the axis direction can be altered with GRAPHIC SCALE.

GRAPHIC POSITION (POS)

Each time you draw text or graphics, it is displayed at the current graphic position (POS) for that target. Upon completion, the POS is updated to the last point referenced. You can draw a relative distance from the POS (using a STEP option), or set an entirely new position with GRAPHIC SET POS.

Most PowerBASIC functions specify graphic and pixel positions in Page Units as X,Y (horizontal term first, then the vertical term). This is true for both graphics and text. When you draw text with GRAPHIC PRINT, POS defines the position of the upper-left corner of the first character.

TEXT CELL (ROW/COLUMN POSITION)

For ease of programming, a few procedures specify text position by row and column. In this case, the position is measured in text cells, which is the space occupied by one character. This works well with fixed width fonts, which is recommended. If a variable width font is chosen, PowerBASIC must use the average character size for these calculations, which can give imprecise results.

For compatibility with most current and prior versions of BASIC (PowerBASIC included), code which references text rows and columns names the vertical term first (ROWS, COLUMNS). Rows and columns are always numbered from one upward.