FutureBasic Logo

<<    Index    >> FutureBasic 5

picture on/off   statement



Syntax:
picture on [(h1,v1)][-(h2,v2)]
picture off [,pictHandleVar&]


Description:
The picture on statement initiates "picture recording" for the current output window. The picture off statement turns off picture recording.
while picture recording is on, all drawing commands and text-display commands which are sent to the window are "recorded" in a special data structure called a picture. The internal format of a picture is identical to that of a resource of type "PICT". After picture recording is turned off, you can display or print the picture, or attach it to a picture field, or save it to disk (as a "PICT" resource or a "PICT" file).
Every picture has a frame, an imaginary rectangle which is stored as part of the picture's data structure. Usually, but not always, the picture itself is contained within the frame. The frame is used as a reference to determine how the picture should be scaled and positioned when the picture is later displayed or printed. The picture recording is cropped to the recording window's clip region, which may or may not be the same as the frame rectangle.
In the picture on statement, the (h1,v1) and (h2,v2) parameters specify the upper-left and lower-right corners of a rectangle. If you specify both (h1,v1) and (h2,v2), they define the picture's frame. Otherwise, the frame is determined as follows:
If you specify only (h1,v1), it becomes the frame's upper-left corner; the frame's lower-right corner is set to the current lower-right corner of the window. If you specify only (h2,v2), the picture's frame is set to the rectangle (0,0)-(h2,v2). If you specify neither (h1,v1) nor (h2,v2), the picture's frame is set to the window's current rectangle.
In the picture off statement, a handle to the recorded picture is returned in pictHandleVar&, if it's specified. pictHandleVar& must be a long-integer variable, or a Handle variable. The value returned in pictHandleVar& is the same as the value returned by the picture function.
By default, drawing commands are not visible on the screen while they're being recorded. If you want the picture to be visible while you're recording it, you must call the Toolbox procedure SHOWPEN after you start recording. If you do this, SHOWPEN must be "balanced" by a call to the HIDEPEN procedure, before you turn off picture recording. For example:
picture on
call SHOWPEN 'show while recording
'[execute drawing commands here]
call HIDEPEN 'balance the call to SHOWPEN
picture off

Only one window can have picture-recording enabled at any given time; you cannot "nest" picture on/picture off pairs. If you switch output windows while picture recording is on, any drawing commands sent to the new output window will not be recorded.
You cannot "temporarily" turn off the recording of a picture. Each call to picture off completes a picture, and each call to picture on starts a brand new picture. However, it is possible to effectively "append" one picture to another, by "inserting" an old picture inside a new one. For example:
picture on
circle 50,50,45
picture off, circlePict&
:
'"Append" more drawing commands:
picture on 'start a new picture
picture ,circlePict& 'This gets recorded in new pict box 20,20 to 50,50
:
picture off, pictHandle& 'contains circle & box


Note:
Your program is responsible for releasing the memory occupied by pictures created with the picture on/picture off statements. Use the kill picture statement to do this, once you're finished using the picture handle.
Drawing commands which plot icons are not recorded in pictures.

See Also:
picture function; picture statement; kill picture