Skip to main content
BuyLog In
VCL
Search in…
Docs > VCL Controls > ExpressSpreadSheet Suite > Concepts > Floating Containers > Customization Options
All docs
V24.2
VCL Controls
What's New
Express Cross Platform Library
ExpressQuantumGrid Suite
ExpressEditors Library
ExpressBars Suite
ExpressCharts Suite
ExpressRichEditControl Suite
ExpressSkins Library
ExpressScheduler Suite
ExpressSpreadSheet Suite
Concepts
Appearance Customization
Clipboard Operations
Custom Draw
File Format Specifications
Export and Import Data
History
Password Protection
VCL Spreadsheet Controls: Supported Commands List
VCL Spreadsheet Controls: Supported Keystrokes
Table Item
Table Items
Understanding Views
Working with Rows and Columns
Worksheet Management
Cells
Controls
Dialogs
Floating Containers
Comments
Customization Options
General Information
Managing Container Objects
Formula Expressions
Groups
How to...
Shared Libraries
API Reference
ExpressQuantumTreeList Suite
ExpressPDFViewer Suite
ExpressPrinting System
ExpressLayoutControl Suite
ExpressNavBar Suite
ExpressPivotGrid Suite
ExpressVerticalGrid Suite
ExpressDocking Library
ExpressMemData
ExpressDataController
ExpressSpellChecker Suite
ExpressMapControl Suite
ExpressGanttControl Suite
ExpressGaugeControl Suite
ExpressTileControl Suite
ExpressFlowChart Suite
ExpressFlowChart Editor
ExpressOrgChart Suite
ExpressPageControl Suite
ExpressWizardControl Suite

Floating Container Customization Options

  • 10 minutes to read

The Spreadsheet control allows you to decorate your worksheets with floating picture, shape, and text box containers. The cell comments, also supported by the Spreadsheet control, are implemented as dedicated comment containers. Each available container type provides both common and type-specific settings that can be customized both programmatically and by end-users:

  • General Options

  • Shape-Specific Settings

  • Picture-Specific Settings

  • Text Box-Specific Settings

General Options

General options, provided by all floating containers, include:

  • Container size and position parameters are specified as the anchoring settings.

  • Simple status settings, represented by the floating container’s Focused and Visible properties.

  • Applied geometric transformations.

  • A hyperlink associated with the floating container.

  • Alternative text title and content strings provided for compatibility with the popular spreadsheet document file formats.

Anchoring Settings

No floating container object can be displayed without assigning anchor settings. Both the container’s position and size are determined by the actual positions of the upper-left and bottom-right corners of the container’s bounding box. These corners are anchored to two points within the worksheet area. The anchor settings of the upper-left and bottom-right bounding box’s corners are provided by the container’s the AnchorPoint1 and AnchorPoint2 properties, respectively:

Shapes and Bounds

In addition to the identical anchor settings provided by the AnchorPoint1 and AnchorPoint2 properties, the container’s AnchorType property allows you to choose one of the three available container anchoring modes. Each of them corresponds to a specific container positioning and sizing model:

Two Cells Anchoring Mode

  • The absolute container positioning mode. The position of the upper-left corner of the container bounding box is specified as absolute horizontal and vertical offsets (in pixels) from the upper-left corner of the worksheet area. The position of the bottom-right corner of the bounding rectangle is specified as absolute horizontal and vertical offsets (in pixels) from the position of the bounding box’s upper-left corner. The offset values for the upper-left and bottom-right corners are specified via the AnchorPoint1.Offset and AnchorPoint2.Offset properties, respectively:

Absolute Anchoring Mode

  • The mixed anchoring mode. The upper-left corner of the bounding rectangle is anchored to the upper-left corner of the cell object specified via the AnchorPoint1.Cell property. The bottom-right corner’s position is specified as absolute horizontal and vertical offsets (in pixels) from the actual position of the bounding rectangle’s upper-left corner. The offset values for the bottom-right corner are specified via the AnchorPoint2.Offset property:

Mixed Anchoring Mode

Additional parameters which can be applied to the anchor points of a container, include:

  • The FixedToCell property, which specifies whether the particular anchor point can be moved separately from the upper-left corner of the cell object to which it is anchored. Note that this property has no effect for the anchor points which are not bound to their cell object as specified by the respective anchoring mode:

Fixed to Cell

  • For the cell-bound anchor points in the cell and mixed modes, you can also specify additional horizontal and/or vertical absolute offsets (in pixels) from the upper-left corner of their respective cell object. Offset values, specified via the AnchorPoint1.Offset and AnchorPoint2.Offset properties, can be both positive and negative. In the case of negative offsets, the anchor point is shifted up and/or left from the upper-left corner of its respective anchor cell object:

Cell Offsets

While the Spreadsheet control provides no specific UI elements for creating floating containers, there are numerous container moving/resizing options available to end-users out-of-the-box:

  • Move the focused container by performing drag-and-drop operations;

  • Resize the focused container either by dragging the sizing handles or by pressing the arrow keys while holding down the Shift key.

  • Resize the container by specifying the height and width values in the Customize Object dialog window’s Size tab.

  • Select one of the available container anchoring options at the Properties tab of the Customize Object dialog window (each option corresponds to the specific value of the FixedToCell property at the first and second container anchor points).

Geometric Transformations

While the anchoring settings determine the basic size and positioning parameters of the container object, geometric transformations provide the next optional level of customization. You can apply the following geometric transformations to the anchored floating container by using its Transform property:

  • Rotate the container around the center of its bounding rectangle (negative values of the Transform.RotationAngle property correspond to a counterclockwise direction of rotation, while positive values represent clockwise rotation of the container):

Rotation Angle

You can combine any number of the available geometric transformations with the previously assigned container anchoring settings, regardless of the chosen anchoring mode. Both the horizontal and vertical container inversions are applied before the rotation.

End-users can rotate container objects by using one of the following options:

  • Assign the required rotation angle in the Size tab of the Customize Object dialog;

  • Perform drag-and-drop operations on the green circular handle, provided by the container bounding rectangle;

  • Press Right or Left keys while holding the Alt key down.

Unlike the shapes, pictures and text boxes, no geometric transformation can be applied to a comment container.

Note that the Spreadsheet control provides no user interface elements for the container object inversion operations.

Floating containers can serve as hot areas for hyperlinks created within the same worksheet.

Container Hyperlink

To associate an existing hyperlink with a container, simply assign a hyperlink object to the container’s Hyperlink property. Additionally, you can associate the same hyperlink with other containers on the same sheet, if required.

A typical hyperlink in the Table View worksheet’s Hyperlinks collection already has a hot area corresponding to a cell or cell range. If you need to associate a floating container with a hyperlink without an additional hot area, refer to the following code example:

var
  ATableView: TdxSpreadSheetTableView;
  APictureContainer: TdxSpreadSheetPictureContainer;
//...
  ATableView := dxSpreadSheet1.ActiveSheetAsTable;
  APictureContainer := ATableView.Containers.Add(TdxSpreadSheetPictureContainer) as TdxSpreadSheetPictureContainer;  // Creating a picture container
//...
  APictureContainer.Hyperlink := ATableView.Hyperlinks.Add(Rect(-1, -1, -1, -1));  // Creating a hyperlink associated with the picture container
  APictureContainer.Hyperlink.Value := 'http://www.devexpress.com';  // Assigning the required URL as the hyperlink value (reference)
  APictureContainer.Hyperlink.ScreenTip := 'DevExpress Official Site';  // Assigning the desired description as the hyperlink tip

To achieve the same goal, end-users can invoke the Insert Hyperlink dialog window by clicking the “Hyperlink…” item in the floating container’s context menu:

Insert Hyperlink Container Dialog

Shape-Specific Settings

In addition to the anchoring settings, all floating containers as visual objects are determined by the shape parameters. With the shape-related settings, available via the Shape property provided by both the picture and shape containers, you can specify exactly how the particular container object is displayed:

  • Assign a particular geometric shape to the container object from the supported shape list (Shape.ShapeType);

  • Determine the container outline settings (Shape.Pen);

  • Set up the container painting parameters, including the gradient mode, colors, etc (Shape.Brush).

Container Shapes

Currently, the Spreadsheet control supports three shape types, or six actual shapes, depending on the container’s height-to-width ratio, determined by the anchoring settings:

  • A rectangle or square (the stRect shape type):

Rectangle

  • A rounded rectangle or square (the stRoundRect shape type):

Rounded Rectangle

  • An ellipse or circle (the stEllipse shape type):

Ellipse

If the imported spreadsheet document file contains a container that has an unsupported geometric shape, it is displayed as either a rectangle or square, depending on its current aspect ratio.

The Spreadsheet control does not provide specific interface elements allowing end-users to change the container object’s shape. However, you can assign a different shape type to the container object at any time by using its Shape.ShapeType property.

Container Painting Settings

The container painting settings include separate brush parameters for both the outline and inner container area. Like Microsoft Excel®, the Spreadsheet control supports various shape painting effects, including transparency, gradients, and texture fill. With the exception of texture fill, all these effects can be applied to both the container’s outline and interior area. The Shape.Pen property provides access to the container’s outline brush parameters while the Shape.Brush property is used for customization of the container’s inner area. These properties are available for both the picture and shape containers. However, if the TdxSmartImage bitmap image is assigned to a picture container by using the Picture.Image property, it overrides any previously assigned container interior area brush settings:

Picture Shape

The Shape.Brush container property provides access to the following display parameters of a shape’s interior area:

  • The brush painting mode (Shape.Brush.Style);

  • The color used to display a brush in active solid fill mode (Shape.Brush.Color);

  • The brush gradient direction used in active gradient fill mode (GradientMode);

  • The set of gradient key points used in active gradient fill mode (Shape.Brush.GradientPoints);

  • The image used as a texture in active texture fill mode (Shape.Brush.Texture). Due to the texture support in shape containers, you can use them instead of picture containers if necessary. However, the picture containers provide more convenient way of sizing and positioning an image within the floating shape.

The container’s Shape.Pen property provides access to the following shape outline parameters:

  • The container outline’s width (Shape.Pen.Width);

  • Settings of the brush used to paint the container’s outline (the Shape.Pen.Brush property provides access to the same property set available for the container’s internal area);

  • The pattern applied to the container’s outline (Shape.Pen.Style).

Since all floating containers in the Spreadsheet control support transparency, the brushes used to paint both the container’s inner area and outline, use the TdxAlphaColor colors instead of the standard TColor. To work with transparent colors, you may need to add the dxCoreGraphics unit to your project.

Picture-Specific Settings

Since a picture container is an extended version of a shape container, the picture containers allow you to assign a bitmap image and its associated settings in addition to all of the shape-specific settings.

Although the shape containers can display the TdxSmartImage pictures as textures, the dedicated picture containers provide more freedom due to the extra positioning and sizing settings:

  • With the Picture.Image property, you can assign a picture loaded as the TdxSmartImage image;

  • With the Picture.CropMargins property, you can set a cropping rectangle for the loaded bitmap;

  • The RelativeResize property specifies whether an end-user is able to change the picture’s height-to-width ratio.

Text Box-Specific Settings

Text box-specific settings, available only for text box and comment floating containers, are provided by the TextBox property. You can use this property to: