PtBkgd

A color-gradient, image, or bitmap background

Class hierarchy:

PtWidget --> PtBasic --> PtContainer --> PtPane --> PtBkgd

For more information, see the diagram of the widget hierarchy.

PhAB icon:

Public header:

<photon/PtBkgd.h>

Description:

The PtBkgd widget provides various background layouts.

A background image.

You can choose from the following background types:

• Color gradients - These let you vary hue, saturation, or brightness to achieve various effects. For example, you could place a background behind a window's widgets that starts from dark blue at the top and gradually fades to light blue at the bottom.
• Images - These let you display your favorite image file as a background for your application. If the image is small or a texture, you can tile it. Images are always opaque and won't let the window's background show through.
• Bitmaps - These are similar to images with one exception: they let a window's background show through.

New resources:

Pt_ARG_BKGD_BRT_FROM, Pt_ARG_BKGD_BRT_TO

These define a brightness range using the standard HSB (hue/saturation/brightness) model. Values range from 0 to 255.

The HSB model is also known as the HSV (hue/saturation/value) model. For more information, see PgHSV().

Pt_ARG_BKGD_HUE_FROM, Pt_ARG_BKGD_HUE_TO

These define a hue range using the standard HSB (hue/saturation/brightness) model. Values range from 0 to 65535. The hue determines the color background.

Pt_ARG_BKGD_IMAGE

This resource points to a PhImage_t structure that defines an image to be displayed. For more information, see PhImage_t, PgDrawImage() and PxLoadImage() in the Photon Library Reference.

Set the flags member of the PhImage_t structure to:

Ph_RELEASE_IMAGE | Ph_RELEASE_PALETTE |
Ph_RELEASE_TRANSPARENCY_MASK | Ph_RELEASE_GHOST_BITMAP
      

before providing the image to the widget. If you do this, the memory used for the image is released when the widget is unrealized or destroyed.

Remember that this is an Alloc resource. When you set this resource, the widget copies the PhImage_t structure but not the data pointed to by the members of the structure. After setting this resource, you can free() the PhImage_t if you don't need it, but don't free() the members of it.

Pt_ARG_BKGD_MIX

For the Pt_BKGD_HUE, Pt_BKGD_SATURATION, and Pt_BKGD_BRIGHTNESS background types. This resource determines whether or not color dithering is used in the gradient. By default, it's turned on.

Pt_ARG_BKGD_ORIENTATION

For the Pt_BKGD_HUE, Pt_BKGD_SATURATION, and Pt_BKGD_BRIGHTNESS background types. This resource sets the gradient orientation. By default the orientation is horizontal. Possible values:

• Pt_BKGD_HORIZONTAL
• Pt_BKGD_VERTICAL

Pt_ARG_BKGD_PIXCOLORS

For the Pt_BKGD_PIXMAP background type. An array of bitmap colors that correspond to the planes defined in Pt_ARG_BKGD_PIXMAP.

Pt_ARG_BKGD_PIXMAP

For the Pt_BKGD_PIXMAP background type. A sequence of planes provided in the format described in PgDrawBitmap().

Pt_ARG_BKGD_PIX_HEIGHT, Pt_ARG_BKGD_PIX_WIDTH

For the Pt_BKGD_PIXMAP background type. These resources indicate the height and width of the bitmap in pixels.

Pt_ARG_BKGD_SAT_FROM, Pt_ARG_BKGD_SAT_TO

These define a saturation range using the standard HSB (hue/saturation/brightness) model. Values range from 0 to 255. The saturation determines the amount of color to be used. A high value makes the color bright; a low one makes it look dim or gray.

Pt_ARG_BKGD_SPACING

The spacing, in pixels, between tiles.

Pt_ARG_BKGD_STEPS

For the Pt_BKGD_HUE, Pt_BKGD_SATURATION, and Pt_BKGD_BRIGHTNESS background types. This resource determines the number of steps used in the gradient to get from the minimum to the maximum value.

Pt_ARG_BKGD_TILE

For the Pt_BKGD_PIXMAP and Pt_BKGD_IMAGE background types. This resource determines which type of tiling will be used to display the image. Possible values:

Pt_BKGD_GRID

Repeat the image in grid fashion.

Pt_BKGD_ALT

Repeat the image in alternating grid fashion.

Pt_BKGD_CENTER

Draw the image once and center it within the container.

Pt_BKGD_CENTER_GRID

Center the image within container and then, if the image is smaller than the container, tile the image around the outside.

If you set this resource to zero, tiling will be disabled and the image will be drawn once at the top-left corner.

Pt_ARG_BKGD_TYPE

Determines which type of background will be displayed. Possible values:

Pt_BKGD_HUE
Pt_BKGD_SATURATION
Pt_BKGD_BRIGHTNESS

These types let you display color gradients. The type you choose affects how the resources are interpreted.

In general, you specify the range of values for the background type you choose and enter only the "to" value for the other resources. So, for example, if you chose Pt_BKGD_HUE, you would enter both the "to" and "from" values for Pt_BKGD_HUE but only the "to" values for Pt_BKGD_SATURATION and Pt_BKGD_BRIGHTNESS.

The smoothness of the gradient is determined by Pt_ARG_BKGD_STEPS and Pt_ARG_BKGD_MIX.

Pt_BKGD_PIXMAP
Pt_BKGD_IMAGE

These types let you display picture backgrounds.

You can use the Pt_BKGD_PIXMAP type for small pictures drawn by hand where you need the background fill color to show through. If you select this type, the widget uses the Pt_ARG_BKGD_PIXMAP resource.

You use the Pt_BKGD_IMAGE type primarily to display images imported from other sources. If you select this type, the widget uses the Pt_ARG_BKGD_IMAGE resource.

Inherited resources:

If the widget modifies an inherited resource, the "Default override" column indicates the new value. This modification affects any subclasses of the widget.