2.2 Description of the Core Classes

This section describes the core classes in the public interface of the Objective Grid for Microsoft .NET control. All of the classes are contained in the Stingray.Grid namespace.

The Cell class represents a single cell in the grid control. A cell is referenced using row and column offsets into the grid. By default, the grid reserves the first row for column headers and the first column for row headers, as shown in Figure 1. The header row and column are numbered row 0 and column 0, respectively.

Figure 1: GridControl Column and Row Headers

In Figure 1, the cell at row 1 and column A has row and column offsets 1, 1. This cell is referenced in source code as follows:

C#:

Cell cell = gridControl1[1,1]; cell.Style.Value = "Hello";

Visual Basic:

Dim cell As Cell cell = GridControl1(1, 1) cell.Style.Value = "Hello"

The Cell class is included in the Stingray.Grid namespace. To reference the Cell class as shown above, this namespace must be opened for use as follows:

C#:

using Stingray.Grid;

Visual Basic:

Imports Stingray.Grid

Instances of the Cell class can be obtained only through an instance of the GridControl class. Once created, a cell instance maintains its association with the GridControl from which the cell was obtained. This allows the Cell instance to be used to change the properties of the referenced cell in the referenced grid. Cell instances can be used to change the style, text, formula, and other properties of a given grid cell. For example, the following code changes the cell at row 1 and column 2 so that it is read-only and is displayed using the Courier font.

C#:

cell = gridControl1[1,2]; Style style = gridControl1[1,2].Style; style.ReadOnly = true; style.TextFont = new OGFont("Courier", 10, 0); style.Value = "World"; cell.Style = style;

Visual Basic:

cell = GridControl1(1, 2) Dim style As Style style = GridControl1(1, 2).Style style.ReadOnly = true style.TextFont = New OGFont("Courier", 10, 0) style.Value = "World" cell.Style = style

---

For efficiency, changes to individual attributes of the cell style are not applied to the grid cell immediately. Instead, style changes must be made as shown above. All desired changes to the cell style are performed in sequence. These changes are not visible in the grid cell until the cell style is applied back to the cell through an assignment of the updated cell style object.

---

For a complete description of the public interface to Cell, see the Objective Grid for Microsoft® .NET® Reference Guide.

The Cell class contains the following public methods.

The Cell class contains the following public properties:

The Range class represents a rectangular range of cells in the grid. It can be set to represent an entire column, an entire row, or the entire table. Explicit coordinates can also be initialized with the top, bottom, left, and right members of a Range object.

Range objects appear frequently in the interface to GridControl. Ranges are used for assigning styles and values to ranges of cells. Ranges are also used to hide, clear, move, copy, and select ranges of cells.

For a complete description of the public interface to Range, see the Objective Grid for Microsoft® .NET® Reference Guide.

The Range class contains the following public methods.

Use the Rows(), Cols(), and Table() methods to define regions without definite top-left or bottom-right coordinates. These methods define the range as being entire rows, entire columns, or the entire table, independent of the actual grid dimensions. This means that as the dimensions of the grid grow or shrink, the realized dimensions of the range also grow or shrink. For example, a grid with 10 rows, 10 columns, and a range defined using Cols(2,4) has the realized coordinates of top = 0, bottom = 10, left = 2, and right = 4, as shown in Figure 2.

Figure 2: Range.Cols(2,4) in a 10x10 grid

If the last three rows of the grid are removed, the realized coordinates of the same range are now top = 0, bottom =7, left = 2, and right = 4. No changes were made to the original range. It is still defined as Cols(2,4).

Figure 3: Range.Cols(2,4) in a 7x10 grid

Ranges do not change when rows or columns are inserted into or deleted from the grid. In the example above, if we insert a new column between columns three and four, the range does not expand to reflect the addition. The range is still Cols(2,4).

Calls to Rows(), Cols(), Cells(), and Table() are not cumulative. You cannot combine successive calls to these methods to define more complex range of cells. A call to any of these methods redefines a range. For example, calling Rows(4,7) followed by Cols(2,5) results in a range of Cols(2,5), not the intersection or union of the two ranges.

The Range class contains the following public properties.

The Style class encapsulates all of the information required to format a cell in a grid control. In addition to formatting information, styles also define most of the grid's behavior. The style information for a cell or a range of cells can be obtained from a Cell object. Style objects can also be applied to a cell or range of cells to change the format of that cell or range. The following code snippets show the use of a style object to format a range of cells in a grid control.

C#:

// Create a range and a style Range range = Range.Cells(2, 3, 4, 5); Style style = new Style(); // Assign a background color and value to the style style.Interior = OGBrush.OGSolidBrush(Color.White); style.Value = "Test"; // Apply the style to the grid gridControl1.SetStyleRange(range, style);

Visual Basic:

' Create a range and a style Dim range As Range range = range.Cells(2, 3, 4, 5) Dim style As Style style = New Style() ' Assign a background color and value to the style style.Interior = OGBrush.OGSolidBrush(Color.White) style.Value = "Test" ' Apply the style to the grid GridControl1.SetStyleRange(range, style)

The Style class supports combining style objects. For example, you can copy from one style to a second style only the properties that are not initialized in the second style. This feature allows you to combine styles and is analogous to the concept of inheritance in programming languages. You can specify a base style from which other styles can inherit properties at run time.

Properties of the Style class are associated with an include bit. This include bit is true when a property is initialized. If it is false, the property is not initialized. When drawing the grid, Objective Grid for Microsoft .NET fills up all uninitialized properties of the cell style object with values inherited from the base styles.

The Style attribute on a Cell object allows users to get and change the style of a specific cell. For details, see Section 2.2.1, "The Cell Class." The GridControl class contains methods and events for changing the style of a cell or range of cells. For details, see Section 2.2.5, "The GridControl Class."

For a complete description of the public interface to Style, see the Objective Grid for Microsoft® .NET® Reference Guide.

The Style class contains the following public methods:

The Style class contains the following public properties:

Making a change to a cell's style is an expensive operation. Because changes to a cell's style are automatically updated when assigned, making many changes sequentially can decrease your application's performance. The following code shows this penalty:

gridControl[1,1].Style.Value = "100"; gridControl[1,1].Style.TypeOf = StyleValueType.typeNumeric; // ...other assignments to the Style object...

To avoid this penalty, create a new Style object (or copy an existing Style object), apply your changes to it, and then assign it to the cell(s):

// create a new Style object Style myStyle = new Style(); // apply changes myStyle.Value = "100"; myStyle.TypeOf = StyleValueType.typeNumeric; // ...other assignments to myStyle ... // assign new Style to a cell gridControl[1,1].Style = myStyle;

This technique is particularly important when you are assigning many properties to the same cell.

An instance of the Param class contains or points to all necessary data for persisting the state of the grid object. Parameter objects can be stored in documents and serialized, or can be used as members of other classes. Parameter objects can also be shared between grid objects.

For a complete description of the public interface to Param, see the Objective Grid for Microsoft® .NET® Reference Guide.

The GridControl class encapsulates the Objective Grid for Microsoft .NET custom control. It is derived from the Windows.Forms.Panel class (which is derived from System.Windows.Control). It inherits a rich set of methods, properties, and events from its base class. It also adds a rich public interface, a number of properties, and many events of its own.

Windows Forms custom controls allow you to quickly create user interfaces by re-using existing controls. The Objective Grid for Microsoft .NET custom control is an example of the benefits of this programming paradigm. To use the GridControl, you drag a GridControl from the Toolbox in Visual Studio onto a Windows form, and an instance of GridControl is created and displayed for design-time editing. The public properties and events defined for GridControl appear in the property grid for design-time manipulation.

For a complete description of the public interface to GridControl, see the Objective Grid for Microsoft® .NET® Reference Guide.

The Windows Forms Designer generates the code needed to instantiate, initialize, format (according to the selected design-time property settings), and display the grid. All of the following code is generated by the Windows Forms Designer:

C#:

#region Windows Forms Designer generated code /// <summary> /// Required method for Designer support - do not modify /// the contents of this method with the code editor. /// </summary> private void InitializeComponent() { this.gridControl1 = new Stingray.Grid.GridControl(); ((System.ComponentModel.ISupportInitialize)(this.gridControl1)). BeginInit(); this.SuspendLayout(); // // gridControl1 // this.gridControl1.ColCount = 30; this.gridControl1.DefaultColWidth = 70; this.gridControl1.DefaultRowHeight = 14; this.gridControl1.EnableUndo = true; this.gridControl1.FrozenCols = 0; this.gridControl1.FrozenRows = 0; this.gridControl1.HeaderCols = 0; this.gridControl1.HeaderRows = 0; this.gridControl1.Location = new System.Drawing.Point(8, 8); this.gridControl1.Name = "gridControl1"; this.gridControl1.RowCount = 30; this.gridControl1.Size = new System.Drawing.Size(608, 472); this.gridControl1.TabIndex = 0; this.gridControl1.Text = "gridControl1"; // // Form1 // this.AutoScaleBaseSize = new System.Drawing.Size(5, 13); this.AutoScroll = true; this.ClientSize = new System.Drawing.Size(544, 405); this.Controls.AddRange(new System.Windows.Forms.Control[] { this.gridControl1}); this.Name = "Form1"; this.Text = "Sample Grid Application"; ((System.ComponentModel.ISupportInitialize)(this.gridControl1)). EndInit(); this.ResumeLayout(false); } #endregion

Visual Basic:

'NOTE: The following procedure is required by the Windows Forms Designer 'It can be modified using the Windows Forms Designer. 'Do not modify it using the code editor. Friend WithEvents GridControl1 As Stingray.Grid.GridControl <System.Diagnostics.DebuggerStepThrough()> Private Sub InitializeComponent() Me.GridControl1 = New Stingray.Grid.GridControl() CType(Me.GridControl1, System.ComponentModel.ISupportInitialize).BeginInit() Me.SuspendLayout() ' 'GridControl1 ' Me.GridControl1.ColCount = 30 Me.GridControl1.DefaultColWidth = 70 Me.GridControl1.DefaultRowHeight = 15 Me.GridControl1.EnableUndo = true Me.GridControl1.FrozenCols = 0 Me.GridControl1.FrozenRows = 0 Me.GridControl1.HeaderCols = 0 Me.GridControl1.HeaderRows = 0 Me.GridControl1.Location = New System.Drawing.Point(8, 8) Me.GridControl1.Name = "GridControl1" Me.GridControl1.RowCount = 30 Me.GridControl1.Size = New System.Drawing.Size(584, 464) Me.GridControl1.TabIndex = 0 Me.GridControl1.Text = "GridControl1" ' 'Form1 ' Me.AutoScaleBaseSize = New System.Drawing.Size(5, 13) Me.ClientSize = New System.Drawing.Size(600, 477) Me.Controls.AddRange(New System.Windows.Forms.Control() {Me.GridControl1}) Me.Name = "Form1" Me.Text = "Form1" CType(Me.GridControl1, System.ComponentModel.ISupportInitialize).EndInit() Me.ResumeLayout(false) End Sub

GridControl defines a number of public events along with associated virtual event handlers. This allows you to handle grid events in one of two ways.

1. You can derive a new control class from GridControl, override the virtual event handler methods, and include custom event-handling logic for the events. This technique must be used when you want to completely avoid executing the base class (GridControl) event-handling logic for an event. Do not call the base class event handler.

   ---

   The base class event handler must be called in order to invoke any delegates attached to the event.

   ---

2. You can attach delegates to the events and handle the events in those delegates. This mechanism is convenient, particularly when using the Windows Forms Designer. You can double-click the name of the event to be handled, and the Windows Forms Designer automatically generates a delegate stub and attaches it to the event. You then write the event-handling logic in the generated delegate stub.

   ---

   Using delegates does not give you any control over how or when the base class event-handling logic is executed (except in special cases where event-handling options are included in the event arguments for the event).

   ---

Once the GridControl is placed into a Windows Form and all desired design-time configurations are complete, you can use the public interface to the GridControl to programmatically control the grid and respond to grid events.

This section describes the methods of the GridControl class. Table 12 lists public and protected methods available for GridControl.

Table 13 lists the virtual event handlers that are available with GridControl. Each of these methods raises its corresponding event (to invoke any attached delegates) when it is invoked. When overriding these methods, the base (GridControl) implementation of the method must be invoked from the derived class implementation, in order to invoke any attached delegates.

Table 14 shows the public properties in the GridControl class.

This section lists the events available to be handled in the GridControl class.

Each event has an associated virtual event handler, whose name is prefixed with "On". The grid-specific event handlers (those not inherited from the Windows.Forms.Control class) accept an event arguments object whose type name is formed by the name of the event plus the text "EventArgs". For example, the CancelEditing event has an associated event handler named "OnCancelEditing", and the argument passed to "OnCancelEditing" is of type "CancelEditingEventArgs".

A delegate attached to grid-specific events accepts two arguments: an object and an event arguments object of the same type as supplied to the virtual event handler for the event. For example, the signature of a delegate for the CancelEditing event would appear as follows:

C#:

private void gridControl1_CancelEditing( object sender, Stingray.Grid.CancelEditingEventArgs e) { }

Visual Basic:

Private Sub GridControl1_CancelEditing( ByVal sender As Object, ByVal e As Stingray.Grid.CancelEditingEventArgs) Handles GridControl1.CancelEditing End Sub

For more information regarding the events and virtual event handlers associated with the GridControl class, see the Objective Grid for Microsoft® .NET® Reference Guide.

Table 15 lists the Objective Grid for Microsoft .NET-specific public events. The events are grouped by function.

Copyright © Rogue Wave Software, Inc. All Rights Reserved.

The Rogue Wave name and logo, and Stingray, are registered trademarks of Rogue Wave Software. All other trademarks are the property of their respective owners.
Provide feedback to Rogue Wave about its documentation.