Tutorials > How to manage cells

Starting from version 8 of the control, you have the opportunity to add as many cells you want to the button surface, both at design-time, through 3D Button Visual Editor, and at runtime through the CellsManager property (that internally implements the CellsManager COM object). On the screenshot below you can see an example containing four different cells, each having its own text, graphics and transparency level:

3dabm_i000123

Each single cell can have the following features:

•	Position and size

•	Visibility

•	Solid background with border and alpha channel transparency support

•	Fully configurable caption text

•	Picture for control's normal and disabled states with alignment and alpha channel transparency support

•	Dedicated Click event (CellClick)

Let's see how to create our cells at Design-time:

•	Inside 3D Button Visual Editor, click the "Manage Cells" button as shown below

3dabm_i000101

•

The cells management User Interface will appear as shown below: at any time you can go back to the standard user interface pressing the "Manage Control" button; as you can see, most of the cells management User Interface is disabled: the first thing to do is to press the "Add" button to add a new cell.

3dabm_i000104

•

After pressing the "Add" button, a dialog box will require to identify the new cell with a numerical UniqueID (Unique IDentification number): this UnqiueID will be used at runtime to identify existing cells from each other; as you can see on the screenshot below, the User Interface will suggest you the UniqueID: you are in any case free to assign to the new cell the UniqueID you prefer. Pressing the "OK" button will create the new cell and will add it to the cells listbox.

3dabm_i000105

•	You can now add as many cells as you need and then change the respective settings as explained on the sections below.

General settings

Actually there is no limit to the number of cells you can create inside a control (apart from your PC memory and resources) ; on the screenshot below, you can see that 4 cells have been created and listed inside the white listbox: note that the visible settings are relative to the cell selected inside the listbox: changing the selected cell will cause the various settings to be automatically updated and the Text and Pictures tabs will change their label in order to remember you which of the available cells is under editing.

Note: The image below has hot links to take you to explanations of the various controls: the property/method on the right column can be used at runtime.

3dabm_i000106

Item name	Description	Corresponding property/method
Unique IDs listbox	Contains the list of the available cells Unique IDs	CellsManager.CellGetCount and CellsManager.CellGetUniqueID methods
"Add" button	Creates a new cell	CellsManager.CellAdd method
"Delete" button	Deletes the selected cell	CellsManager.CellDelete method
Visible	Sets/resets the selected cell visibility	CellsManager.Visible
Scale units	The unit used for defining the posizion and size for a given cell	CellsManager.ScaleUnit
Position in % X	The horizontal cell position expressed in the unit specified by the CellsManager.ScaleUnit property	CellsManager.CellAdd, CellsManager.CellSetPos and CellsManager.CellGetPos methods
Position in % Y	The vertical cell position expressed in the unit specified by the CellsManager.ScaleUnit property	CellsManager.CellAdd, CellsManager.CellSetPos and CellsManager.CellGetPos methods
Size in % Width	The cell width expressed in the unit specified by the CellsManager.ScaleUnit property	CellsManager.CellAdd, CellsManager.CellSetSize and CellsManager.CellGetSize methods
Size in % Height	The cell height expressed in the unit specified by the CellsManager.ScaleUnit property	CellsManager.CellAdd, CellsManager.CellSetSize and CellsManager.CellGetSize methods
"Apply" buttons	Apply the respective settings
Background transparent factor	Applies alpha channel transparency to the cell background color (if any)	CellsManager.BackTranspFactor
Background color	Applies a color to the cell background: if no color is applied (situation represented with the symbol inside the color box) the cell background will result completely transparent	CellsManager.BackColor
Border width	If set to 1 or higher, adds a border line to the cell	CellsManager.BorderWidth
Border color	Applies a color to the cell's border (if any): the default color is black	CellsManager.BorderColor
Change buttons	These buttons will open the color choice dialog box for the corresponding property.

At runtime you can also:

•	retrieve the total number of available cells using the CellsManager.CellGetCount method and the UniqueID for each of them using the CellsManager.CellGetUniqueID method.

•	understand if a cell with a certain UniqueID exists using the CellsManager.CellFind method.

Text settings for a specific cell

Note: The image below has hot links to take you to explanations of the various controls: the property/method on the right column can be used at runtime.

3dabm_i000109

Item name	Description	Corresponding property

Text	The text that will appear over the button: it can be multi-line (press the Enter key each time you need to create a new line of text).	CellsManager.Text and CellsManager.TextDescriptor.Text
Visible	Hides/shows the selected text	CellsManager.TextDescriptor.Visible
Alignment	Horizontal and vertical text alignment	CellsManager.TextHorzAlign and CellsManager.TextVertAlign
Offset X	Offset from the default horizontal position	CellsManager.TextDescriptor.OffsetX
Offset Y	Offset from the default vertical position	CellsManager.TextDescriptor.OffsetY
Effect	Enhancement special effect applied to text	CellsManager.TextDescriptor.SpecialEffect
Factor	Enhancement special effect factor	CellsManager.TextDescriptor.SpecialEffectFactor
Double space	Applies/removes double space	CellsManager.TextDescriptor.DoubleSpace
Antialias	Applies/removes anti-aliasing to text borders	CellsManager.TextDescriptor.Antialias
Transparency	Applies alpha channel transparency to text.	CellsManager.TextDescriptor.TransparentFactor
Rotation angle	Text rotation angle	CellsManager.TextDescriptor.Angle
Normal Color (Up)	Text color when the button is in Normal state.	CellsManager.TextDescriptor.ColorNormal
Mouse over Color	Text color when the mouse is over the button surface: if this color is left undefined the Normal Color will be used. The undefined state is represented with the symbol inside the color box. Once the color has been defined, it can be reset back to the undefined state by double-clicking the relative color box (not the "..." button).	CellsManager.TextDescriptor.ColorMouseOver
Pressed Color (Down)	Text color when the button is in Pressed state: if this color is left "undefined" the Normal Color will be used. The undefined state is represented with the symbol inside the color box. Once the color has been defined, it can be reset back to the undefined state by double-clicking the relative color box (not the "..." button).	CellsManager.TextDescriptor.ColorPressed
Highlight effect color	Color of the highlighted text portion (available when a special effect is applied): if this color is left undefined the color will be calculated automatically. The undefined state is represented with the symbol inside the color box. Once the color has been defined, it can be reset back to the undefined state by double-clicking the relative color box (not the "..." button).	CellsManager.TextDescriptor.ColorHighlight
Shadow effect color	Color of the shadowed text portion (available when a special effect is applied): if this color is left undefined the color will be calculated automatically. The undefined state is represented with the symbol inside the color box. Once the color has been defined, it can be reset back to the undefined state by double-clicking the relative color box (not the "..." button).	CellsManager.TextDescriptor.ColorShadow
Halo effect color	Color used to create a Halo special effect.	CellsManager.TextDescriptor.ColorHalo
Solid background Color	Applies/removes a solid background under the text position .	CellsManager.TextDescriptor.SolidBack and CellsManager.TextDescriptor.ColorSolidBack
Background border Color	Applies/removes a border.	CellsManager.TextDescriptor.Border and CellsManager.TextDescriptor.ColorBorder
Background shadow Color	Applies/removes a shadow.	CellsManager.TextDescriptor.SolidBackShadow and CellsManager.TextDescriptor.ColorSolidBackShadow
"..." color editing buttons	These buttons will open the color choice dialog box for the corresponding property.

Font related properties can be retrieved/modified at runtime using the CellsManager.CellGetLogFont and CellsManager.CellSetLogFont that will manage a standard Windows LOGFONT data structure.

Item name	Description	Corresponding LOGFONT field
Font	The font name (also known as typeface or facename): only TrueType (marked with the symbol) and OpenType (marked with the symbol) fonts are supported.	lfFaceName
Size	The height of the button expressed in points	lfHeight
B Bold checkbox	Sets/resets the bold attribute	lfWeight
I Italic checkbox	Sets/resets the italic attribute	lfItalic
U Underline checkbox	Sets/resets the underline attribute	lfUnderline
S Strikethrough checkbox	Sets/resets the strikethrough attribute	lfStrikeOut

Pictures settings for a specific cell

Note: The image below has hot links to take you to explanations of the various controls: the property/method on the right column can be used at runtime.

3dabm_i000108

Item name	Description	Corresponding property/method

Picture for normal state	The picture file displayed on the cell surface when the button is in Normal state.	CellsManager.PictureNormal and CellsManager.CellSetPictureFromHandle method
Picture for disabled button	The picture file displayed on the cell surface when the button is in Disabled state.	CellsManager.PictureDisabled and CellsManager.CellSetPictureFromHandle method
Transparent factor	Apply alpha channel transparency to the loaded pictures	CellsManager.PictureTranspFactor
Alignment	Changes the picture or animation position over the cell.	CellsManager.PictureHorzAlign and CellsManager.PictureVertAlign
Browse button	Browses the current PC folders for a picture.
Delete button	Deletes the current picture.
Preview	Preview of the loaded picture.