Using Layers

TImage32 holds an indexed collection of layers, referenced by the Layers property. The number of layers is limited only by the amount of free memory.

Each layer is an entity, which basically 'knows' how to paint itself to the back-buffer of the control and how to interact with the mouse. Layers are indexed and their indexes are similar to the Z-order of standard controls. Layers with smaller indexes are considered to lie deeper. This common behavior is implemented in the TCustomLayer class.

Common Properties and Methods

The basic layer's behavior is controlled by its LayerOptions property, which is a 32-bit unsigned integer value composed of Layer Options Bits. This property allows for fast and relatively simple referencing of layers and groups of layers.

Consider, for example, the LOB_VISIBLE bit (31-st bit in layer options). When TImage32 repaints its layers at PST_DRAW_LAYERS stage, it uses the stage parameter from corresponding TPaintStage record as a bit-mask (default value is LOB_VISIBLE=$80000000). Being compared (logical AND operation) with LayerOptions of each layer, this mask determines whether the layer should be painted or not.

Similar situation is with reaction to mouse messages (see below).

Using LayerOptions you can easily customize the appearance and modify the order of in thich TImage32 repaints layers. For example, you may assign several categories to layers, using lower 24-bits of LayerOptions and then just change the mask in corresponding TPaintStage record to specify exactly which category you want do be displayed.

More of that, remember, that you can insert several PST_DRAW_LAYERS paint stages (even before the PST_DRAW_BITMAP stage), each with its own mask, or, alternatively, call ExecDrawLayers while handling PST_CUSTOM stages. Basically it means, that you can realize almost any complex repainting scheme, like overlay layers, underlay layers, layers, which are always on top... or always in the background, etc.

Tracking the Mouse

Each layer is capable of responding to mouse down/move/up messages, which are routed to OnMouseDown, OnMouseMove and OnMouseUp events of the container (TImage32 control). Only one layer can receive a mouse message at a time.

Searching for the layer that receives a mouse message starts from the top-most layer and ends when the first layer satisfying both of the following conditions is found:

Layer has LOB_MOUSE_EVENTS bit activated in its LayerOptions;
Layer passes a hit test (see below);

There is also a possibility to disable passing of all mouse messages to layers. Just set the MouseEvents property of the layer collection to False, and TImage32 will generate mouse events right away, without checking for a possible receiving layer.

As stated earlier, layer should pass a hit test in order to receive mouse messages. The hit test is a boolean response to the mouse coordinates, accomplished by the HitTest method:

function HitTest(X, Y: Integer): Boolean; virtual;

X and Y parameters here are the coordinates of the point specified relative to the top-left corner of TImage32 (in pixels). The function returns a value that indicates that the layer is 'there'. This function is overriden in descendants, for example, in TBitmapLayer, this hit test may take into consideration values stored in the alpha channel of the contained bitmap. You can also write a handler for OnHitTest event to customize hit tests at run-time.

Similar to standard controls, layers may also capture mouse messages. By default, all mouse messages are captured automatically once the mouse is pressed on top of the layer and until the mouse is released. The layer that has captured the mouse is pointed to by the MouseListener property of the layer collection. (There are a few things to work on here... will do it later).

Painting Layers

Layers are painted in bottom-to-top order, starting from lower indexes. By default, only visible layers are painted, that is the ones with LOB_VISIBLE bit set, but as it was shown above, this order may be changed.

Positioned Layers

Positioned layers are the layers, you will probably use most of the time. The base class for positioned layers is TPositionedLayer. In addition to basic layer behavior, it introduces Location property (of the TFloatRect type), which specifies layer's position and size. Having location specified as a floating point rectangle helps to avoid rounding errors when layers are resized.

The location can be specified in pixels, relative to TImage32 top-left corner, or in scaled pixels, relative to the top-left corner of the bitmap image. In the second case, the scale of the layer coincides with the scale of the bitmap image and the actual location of the layer relative to the top-left corner of TImage32 may be obtained with its GetAdjustedLocation method.

Using Layers

Common Properties and Methods

Tracking the Mouse

Painting Layers

Positioned Layers

See Also