Futurebasic/Language/Reference/picture field

PICTURE FIELD

Syntax

PICTURE FIELD [#]pfID [,[pict][,[rect][,[type][,just]]]]

Revised

February, 2002 (Release 6)

Description

Use this statement to create a new picture field in the current output window, or to modify the characteristics of an existing picture field. A picture field displays a picture which is automatically refreshed when necessary, and which can optionally respond to mouse clicks.

There are important differences in how picture fields are handled in the older Standard BASIC versus the newer Appearance Runtime. In Standard BASIC, picture fields were actually edit fields that had a destination rectangle with no height. (The top of the destination rectangle was equal to the bottom.) The contents of those edit fields consisted of data that told FB what to display. For instance, if the contents were. "%1001" then FB knew to display a resource picture with an ID of 1001.

Appearance picture fields are buttons and as such inherit the full power of the Appearance Manager's ability to display and manage them properly. There is, however, a difference between a picture field and a picture button. A picture field is fully managed as a user pane (a special type of button) by the Appearance Runtime.In other words, FB tells the toolbox that it should call back into the runtime for the details of managing the picture. A picture button is a standard CDEF (control definition) that is managed by the Appearance Manager. Both are buttons. But PICTURE FIELDs are generally display items where APPEARANCE BUTTONs that employ pictures are generally action items.

Appearance Manager picture fields abandon the more obscure framing conventions that were available in the Standard BASIC runtime. For instance, frame types such as _round, _rounder, and _roundest are no longer available.

The parameters are interpreted as follows.

pfID
This is the ID number of the picture field. To create a new picture field, specify a pfID value which is different from the ID of any existing picture field, and any existing edit field, in the current window. When you're creating a new picture field, the pict and rect parameters are also required. To modify an existing picture field, specify the ID number of the existing field, and any other parameters that you want to modify; any parameter that you omit won't have its corresponding characteristic changed.

pict
This parameter specifies the picture to display in the picture field. You can specify it in any of the following forms:

• resName$—The name of a PICT resource in a currently open resource file.
• %resID%—A "%" symbol followed by the resource ID number of a PICT resource in a currently open resource file.
• &pictHandle&—An "&" symbol followed by a picture handle.

If you use a PICT resource, it's best to use one that's purgeable so that the memory it occupies will be properly released (this memory is not automatically released when the picture field is closed). Don't close the resource file containing the picture until after you close the picture field or you put a different picture into the field. If you use a picture handle, make sure you do not release its memory (don't call KILL PICTURE) until after you close the picture field or you put a different picture into the field.

rect
This parameter specifies the rectangle in which the picture will appear; no part of the picture will be drawn outside of this rectangle. You can specify it in either of the following forms:

• (x1%,y1%)-(x2%,y2%)—These coordinates specify two diagonally opposite corners of the rectangle.
• rectAddr&—A pointer or long integer expression. This is interpreted as the address of a standard 8-byte RECT structure.

type
This is an integer which specifies several characteristics about the field.

"Clickable" types. Picture fields of these types will generate an _efClick Dialog event (Standard BASIC) when the user clicks in them.

<img src="p/PICTURE_FIELD_statement04.gif" alt="IMAGE imgs/PICTURE_FIELD_statement04.gif" width=444 height=257>

"Non-clickable" types. Picture fields of these types will not generate any Dialog event when the user clicks in them.

<img src="p/PICTURE_FIELD_statement05.gif" alt="IMAGE imgs/PICTURE_FIELD_statement05.gif" width=419 height=193>

You can also add any combination of the following constants to the type parameter to achieve different effects in appearance:

"Images Were Here.

Note

To remove a picture field from the window, use the EDIT FIELD CLOSE statement.

When you create, modify or click on a "clickable" picture field, all edit fields in the current window become inactive, and the picture field becomes "active." When a picture field is "active," you can retrieve various kinds of information about it using the WINDOW function.

See Also

EDIT FIELD; EDIT FIELD CLOSE; PICTURE ON/OFF; WINDOW; Function