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:
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:
- The cell object anchoring mode. Both the upper-left and bottom-right corners of the container’s bounding box are anchored to the upper-left corners of two cell objects specified via the AnchorPoint1.Cell and AnchorPoint2.Cell properties:
- 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:
- 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:
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:
- 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:
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):
- Flip the container along the vertical axis (Transform.FilpVertically):
- Flip the container along the horizontal axis (Transform.FlipHorizontally):
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.
Container Hyperlink
Floating containers can serve as hot areas for hyperlinks created within the same worksheet.
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:
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):
- A rounded rectangle or square (the stRoundRect shape type):
- An ellipse or circle (the stEllipse shape type):
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:
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:
Specify the text displayed by a comment or text box container (TextBox.TextAsString);
Customize settings of the font used to display text (TextBox.Font);
Set the horizontal and vertical text block alignment (TextBox.AlignHorz and TextBox.AlignVert);
Set distances between the text block and the left, top, right, and bottom container boundaries (TextBox.ContentOffsets).