JadeMask Class

The JadeMask control is a combination picture, button, and label. This control enables you to define images that are automatically presented when the mouse moves over the control and when the button is down or disabled.

The JadeMask control supports user-specified Web events (that is, you can write a function and use the Window class addWebEventMapping method to invoke it when a specified event occurs).

In addition, this control provides:

• A mask picture that defines a region within the control (the presentation can create the effect of a button of any shape)

• The ability to return the color of the pixel that the mouse is currently over in the mask

As the JadeMask class is a subclass of the Picture class, it inherits all of the properties and methods of the Picture, Control, and Window classes.

You can define the control as a single button, a two-state button, or an automatic two-state button based on the style property. You can also define the control as the Cancel button or the default button.

The canHaveFocus property determines whether the control can have focus. When the control has focus, it can be clicked with the mouse, the accelerator defined on the caption can be used, or the space key or return key pressed. If the control is also the Cancel button, pressing the Esc key also fires the click event.

The following examples show the bitmaps that can be provided.

These images represent the following states, respectively.

• Normal

• Disabled

• Down

• Roll over

• Roll under (when the button is down)

• Focus up

• Focus down

• The mask picture, which is never visible

These images are placed on a background picture so that the button gives the impression that it consists of the swirl shown by the mask in the above examples. The control responds only when the mouse is over that logical area.

A skinned button does not display the focus rectangle if the focus picture is included in the skin. If these pictures are not defined, the pictureRollOver state is displayed when the control has focus or the normal control picture property state if that pictureRollOver is not provided.

When an image containing transparency is displayed in a browser as part of a Web-enabled application, the following conditions must be true for the transparency to be displayed:

• The drawing methods of the Window class, such as drawLine, are not used on the control

• The value of the caption property of the control is null

• The client area of the control is the same size as the image, which is true when the stretch property of the control is set to Stretch_ToControl (1)

When a JadeMask control is skinned and at least one of the skin images is 32‑bit (which supports transparency), the control is treated as though it is transparent; that is, the control is painted on its parent without the area being erased with the effective value of the backColor property. Instead, the parent shows through any transparent areas of the images (for rounded corners, for example). In addition, any semi‑transparent parts of the images are anti‑aliased with the parent image so that they are displayed with smooth corners over any background color.

For a summary of the constants, properties, method, and events defined in the JadeMask class, see "JadeMask Constants", "JadeMask Properties", "JadeMask Method", and "JadeMask Events", in the following subsections.