GRAPHIC ATTACH statement

Purpose

Select the graphic target (window, control, or bitmap ) on which future drawing operations will take place.

Syntax

GRAPHIC ATTACH hWin, id [, REDRAW]

Remarks

This statement chooses a graphic target.  All further graphic operations will be directed to this target until another GRAPHIC ATTACH or GRAPHIC DETACH statement is executed, or the graphic target is deleted.  All PowerBASIC graphical displays are persistent -- they will be automatically redrawn even if minimized or temporarily covered by another window.

By default, all graphic operations are displayed immediately upon execution of a graphic statement.  In many cases, this is a good choice, because the display is always up-to-date.  However, as the complexity of graphic operations increases, this continuous update process does not afford the best performance.  It is usually better to use the REDRAW option described below, as it will generally provide a dramatic improvement in overall performance.

Only one thread may be attached to a particular Graphic Target at a time.  An attempt to attach more than one will generate an Illegal Function Call Error 5.

hWin

Handle of the GRAPHIC WINDOW, DIALOG, or BITMAP to be used with GRAPHIC statements.

id

The control id, if the target is a GRAPHIC CONTROL, or zero if the target is a GRAPHIC WINDOW or GRAPHIC BITMAP.

REDRAW

This option can provide a dramatic improvement in the execution speed of graphic statements, as it eliminates repetitive updates to the display.  If this option is included, all drawing statements are buffered until a GRAPHIC REDRAW statement is executed, or the operating system chooses to update the target window.  Without REDRAW, all graphical statements (Line, Box, Print, etc.) are performed immediately.  However, in most cases, it's better to defer the display until a number of statements have been performed.

While the REDRAW option defers update of the display, it does not guarantee that no interim updates will be performed.  There are times when the operating system, or other factors, may intervene.  If update must be suppressed until complete, you should create your graphic invisibly using a GRAPHIC BITMAP, then display it by using GRAPHIC COPY.

Example

' Draw a blue gradient fill.

' Each line is displayed as it's drawn.
GRAPHIC ATTACH hDlg, %IDC_GRAPHIC1
FOR y& = 0 TO 255
  GRAPHIC LINE (0, y&) - (255, y&), RGB(0, 0, y&)
NEXT

' Draw a buffered, blue gradient fill.
' Nothing is displayed before GRAPHIC REDRAW,
' this enhancing performance dramatically.
GRAPHIC ATTACH hDlg, %IDC_GRAPHIC2, REDRAW
FOR y& = 0 TO 255
  GRAPHIC LINE (0, y&) - (255, y&), RGB(0, 0, y&)
NEXT
GRAPHIC REDRAW

See also

CONTROL ADD GRAPHIC, GRAPHIC BITMAP LOAD, GRAPHIC BITMAP NEW, GRAPHIC DETACH, GRAPHIC WINDOW