vcl-168060-expressspreadsheet-concepts-floating-containers-customization-options.md
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, 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.
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:
Additional parameters which can be applied to the anchor points of a container, include:
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).
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:
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.
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
TdxSpreadSheetTableView *ATableView;
TdxSpreadSheetPictureContainer *APictureContainer;
//...
ATableView = dxSpreadSheet1->ActiveSheetAsTable;
APictureContainer = static_cast<TdxSpreadSheetPictureContainer*>(ATableView->Containers->Add(__classid(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:
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).
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:
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.
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.
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, 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).