Managing Container Objects

• Jun 21, 2022
• 4 minutes to read

The Spreadsheet control allows you create, destroy, rearrange and customize the floating picture, shape, text box, and comment containers within each individual worksheet.

To create, delete, and access/modify floating containers within a particular Custom View worksheet, use its Containers property. For detailed information on specific container management tasks, refer to the following sections:

• Container Object Creation

• Container Object Deletion

• Accessing Specific Container Objects

Container Object Creation

The Spreadsheet control provides two floating container creation methods accessible via the Custom View worksheet’s Containers collection:

• The general Add method that allows you to create all available types of the floating containers.

• The dedicated AddCommentContainer method is designed to create only comment containers, since unlike other container types, comments must be attached to specific cell objects.

Regardless of the created container type, both methods return a generic container object that provides access only to the basic properties and methods. In order to get access to type-specific container settings, you need to cast a generic object to the actual type of the created container, including the TdxSpreadSheetShapeContainer, TdxSpreadSheetPictureContainer, TdxSpreadSheetCommentContainer, and TdxSpreadSheetTextBoxContainer types. For detailed information on accessing specific container objects and their settings, refer to the Accessing Specific Container Objects section.

In addition to an extensive API, the Spreadsheet control provides three runtime container creation techniques out-of-the-box. Currently, in order to create a container, an end-user can:

• Create comment containers by invoking the context menu for the focused cell and clicking the “Insert Comment…” item:

As a result, the cell comment’s text editor is invoked:

• Create picture containers by pasting a bitmap image currently contained within the clipboard into the active worksheet. A newly created container uses the copied bitmap as a picture source.

• Can copy/paste a floating container, previously created within either the same Spreadsheet control instance, or others.

Container Object Deletion

There are several ways to delete floating containers within a particular worksheet programmatically:

• Invoke the Containers.Clear procedure in order to remove all container objects from the collection.

• Call the Containers.Delete procedure to remove the specified floating container from the worksheet’s collection.

• Destroy a particular container object by calling its Free procedure. For instance, you can access the required container object by its zero-based index within the collection.

End-users can delete floating containers by pressing the Delete key for the currently focused container or pick the Delete option in the container context menu:

Cutting the container object to clipboard either by clicking the Cut option in the context menu or pressing the Ctrl+X key combination also effectively removes it from the collection.

Accessing Specific Container Objects

The Custom View worksheet’s Containers collection provides zero-based indexed access to the created floating containers as generic container objects. These TdxSpreadSheetContainer objects allow you to access and modify only the basic settings that are common to all container types supported by the Spreadsheet control. Therefore, you may need to cast these objects to the actual container types, namely the TdxSpreadSheetShapeContainer, TdxSpreadSheetPictureContainer, TdxSpreadSheetTextBoxContainer, and TdxSpreadSheetCommentContainer classes, to get access to the type-specific settings and methods:

Delphi

var
  AShapeContainer: TdxSpreadSheetShapeContainer;
  APictureContainer: TdxSpreadSheetPictureContainer;
  ATableView: TdxSpreadSheetTableView;
//...
  ATableView := dxSpreadSheet1.ActiveSheetAsTable;
// Creating the shape container as the first collection item
  ATableView.Containers.Add(TdxSpreadSheetShapeContainer);
// Creating the picture container as the second collection item
  ATableView.Containers.Add(TdxSpreadSheetPictureContainer);
//...
// Casting the first collection item to the TdxSpreadSheetShapeContainer type
  AShapeContainer := ATableView.Containers[0] as TdxSpreadSheetShapeContainer;
// Casting the second collection item to the TdxSpreadSheetPictureContainer type
  APictureContainer := ATableView.Containers[1] as TdxSpreadSheetPictureContainer;

C++

TdxSpreadSheetShapeContainer* AShapeContainer;
  TdxSpreadSheetPictureContainer* APictureContainer;
  TdxSpreadSheetTableView* ATableView;
//...
  ATableView = dxSpreadSheet1->ActiveSheetAsTable;
// Creating the shape container as the first collection item
  ATableView->Containers->Add(__classid(TdxSpreadSheetShapeContainer));
// Creating the picture container as the second collection item
  ATableView->Containers->Add(__classid(TdxSpreadSheetPictureContainer));
//...
// Casting the first collection item to the TdxSpreadSheetShapeContainer pointer type
  AShapeContainer = static_cast<TdxSpreadSheetShapeContainer*>(dxSpreadSheet1->Containers->Items[0]);
// Casting the second collection item to the TdxSpreadSheetPictureContainer pointer type
  APictureContainer = static_cast<TdxSpreadSheetPictureContainer*>(dxSpreadSheet1->Containers->Items[1]);

In addition to zero-based indexed access, you can use the container collection’s GetFirstVisibleContainer, GetLastVisibleContainer, GetNextVisibleContainer, and GetPrevVisibleContainer functions to obtain a sheet’s generic container objects. Likewise, you need to cast them to their actual types to access their type-specific members.

An end-user can pick individual containers by clicking within their respective bounding rectangles in order to move, resize, rotate, clone, cut, copy, or delete them.