10Tec
iGrid 2.5 ActiveX Control
What's
New
1. Full support for
Windows XP Visual Styles. iGrid header, combo box
buttons, check box controls and scroll bars support XP styles.
1.1.
You can turn on/off using XP styles for iGrid contents and header
separately using the UseXPStyles and Header.UseXPStyles properties respectively.
1.2.
You can determine whether iGrid can use XP styles or not using the new
Supports function. The Supports function with the igSupFeatXPStyles
parameter returns True if the application use XP styles
and iGrid can use them too; otherwise it returns False.
1.3.
iGrid also raises the new WindowsThemeChanged(ByVal bAppUsesXPStyles As Boolean) event when the user changes
the current Windows XP theme or disable/enable using Visual Styles. The bAppUsesXPStyles parameter indicates whether an application
uses Visual Styles or not after the current theme has changed.
2. iGrid header was fully
rewritten:
2.1.
Each iGrid column header consists of three parts - an icon at the left
of the column title, the column title and sort info (sort icon and optionally
sort key number) at the right of the column title. Column icon is displayed
only at the left part in contrast to the previous version which can display an
icon at the right of the column title. In the previous version column icons at
the right part are used mainly to display numerated sort icons and you could
not be able to use column icons at the left part if you use numerated sort
icons. In iGrid 2.5 you no longer need to specify a special imagelist
that contains numerated sort icons – iGrid draws them by itself and you can use
column icons at the left part simultaneously with numerated sort icons.
2.2.
iGrid header options can be adjusted
using the new Header property of the HeaderObject
type. The following table compares iGrid 2.1 header properties with iGrid 2.5 HeaderObject properties and also lists new properties and
methods:
|
iGrid
2.1 |
iGrid
2.5 |
|
HeaderButtons |
Header.HasButtons |
|
HeaderFlat |
Header.Flat (works only if Header.HasButtons = True and
iGrid header does not use XP styles) |
|
HeaderDragCols |
Header.DragCols |
|
HeaderHeight |
Header.Height |
|
HeaderHotTrack |
Header.HotTrack |
|
|
Header.Hwnd (returns the API handle of iGrid header) |
|
|
Header.BackColor, Header.ForeColor (now you can use the
background and foreground color of the entire header using these properties;
the BackColor property does not work if the header
uses XP styles) |
|
Header |
Header.Visible |
|
ColHeaderImageOnRight(vCol) and the bImageOnRight parameter
of the AddCol method |
Removed (column header icon is displayed at the left of
column title now) |
|
ColHeaderTextAlign and EHdrTextAlignFlags |
Replaced
on ColHeaderTextFlags. Now you can use ETextFormatFlags to format column title. This means that
iGrid column titles can be formatted as iGrid cells, i.e. you can word
wrapping, multiline titles, and so on. |
|
HeaderImageList |
Header.ImageList |
|
|
Header.Font and Header.SortInfoFont. You can change the
font of column titles and sort info using these properties. |
|
|
Header.AutoHeight. |
|
|
Header.UseXPStyles. Allows iGrid header use XP styles (if possible). |
|
|
Header.SortInfoStyle As ESortInfoStyles – determines what info is
displayed in column header when the column is sorted (numerated icons, only
icons or nothing). Notice that then MultiSortIcons property was removed because there is no need
in it. |
|
|
Header.SortIconStyle As ESortIconStyles determines the style of sort
icons (3D or solid); the new Header.SolidSortIconColor
allows you to specify the color of solid sort icons. |
|
|
AutoHeightFlags As EHeaderAutoHeightFlags – allows you to
specify the set of events when the header automatically fit its height |
|
|
Header.MinHeight (18 pixels is the default value) |
2.3.
The ColHeaderBackColor and ColHeaderForeColor
properties were implemented. These properties can be used to specify the
background and foreground colors of particular column header (whereas Header.BackColor and Header.ForeColor
specify colors for the entire header).
2.4.
The bCancel parameter of the StartColWidthChange event was removed. You should use the
new ColAllowSizing property instead of it. If you set
this property to False for a particular column, the user can not resize this
column interactively. In this case iGrid also does not change the cursor to the
size WE pointer when you move it over the column divider (that what could not
be done with the bCancel parameter of the StartColWidthChange event). The AddCol
method was also supplemented by the bAllowSizing parameter
which allows you to enable/disable column resizing when you create the column. Note:
ColAllowSizing have an influence only on interactive
column sizing; the False value does not prohibit you
to change the column width in code using the AutoWidthCol
method or the ColWidth property.
2.5.
Two new header events were implemented:
Public Event ColHeaderMouseEnter(ByVal
lCol As Long)
Public Event ColHeaderMouseLeave(ByVal
lCol As Long)
These events are fired when the mouse pointer is entered or left the
corresponding column header. They are also raised for the header area that does
not contain column headers (at the right of the last column header); the lCol parameter equals zero in that case.
3. Other new features related
with iGrid header:
3.1.
The AutoWidthCol method allows you to fit the
width of a column including the contents of the column header. You can turn on
or off this mode using the new Boolean AutoWidthColWithHeader property; the default value of this
property is True.
3.2.
iGrid can redraw its cells and header as
you are resizing a column. The new ImmediateColumnResizing
property turns on or off this mode. By default the value of this property is
False and iGrid draws only the vertical black line that indicates the future
column width as the user is resizing a column; iGrid changes the column width
and redraws its contents only after the user has released the mouse button. Notice
that you can turn on immediate column resizing only in Windows 2000 or Windows
XP. The Supports function with the igSupFeatImmedColResizing
parameter returns True if you can use this feature in
your application.
4. iGrid 2.5 supports row keys. This means
that you can define string keys for rows and use these keys to access rows and
cells in any method or property which deal with them. The following subitems highlight some changes done in iGrid to implement
the row keys feature:
4.1.
You can define a string key for a new row using the new sKey parameter of the AddRow
method while you are creating the row or change it later with the new RowKey property.
4.2.
The new RowIndex property returns the numeric
index for a specified string row key.
4.3.
iGrid uses the binary search algorithm to
find a cell or row by its string key. iGrid can be
populated slightly slower in the case you define row keys (because it needs to
build the row key index and allocate the additional memory to store it), but
later you can gain very fast access to cells using the following syntax:
iGrid1.CellValue("rowkey", 2).
5. Some changes were done
in the methods concerning iGrid sorting:
5.1.
iGrid allows you to use the new type of
sorting – custom sorting. This means that you can implement your own sort
criteria which can be used by iGrid. To use this feature, specify the new igSortByCustomer member of the ESortTypes
enumeration as the sort type of a column you want to sort by yourself. In this
case iGrid will raise the new CustomSort(ByRef v1, ByRef
v2, ByRef bIsGreater As
Boolean) event for this column when the user is sorting iGrid by this column. iGrid raises this event to compare all cells of this column.
Thus all you need to do is to compare two cell values (the v1 and v2
parameters) and return the result of the comparison in the bIsGreater
parameter. Set this parameter to True if v1 is greater than v2 or to False
otherwise.
5.2.
The bSortIcon parameter was removed from the DoDefaultSort method. This method has the new second
parameter named iShift which allows you to specify
the state of the SHIFT, CTRL or ALT keys when you sort the grid by a specified
column (remember that a non-zero value of this parameter adds the specified
column to existing sorted columns and thus implements multicolumn sorting). So
you can use the DoDefaultSort method to imitate user
clicks and therefore iGrid sorting without any restriction (the previous
version does not allow you to implement multicolumn sorting using this method).
5.3.
iGrid has two new properties, ColSortOrder and ColSortKey,
which indicates the sort state of a specified column. The ColSortKey
property is the order number of the column in multicolumn sort criterion, i.e.
the column is sorted if the value of ColSortKey is
greater than zero. If the column is sorted, the ColSortOrder
property returns the sort order of the column; otherwise it does not make
sense. iGrid changes the values of these properties as
the user clicks column headers and thus sorts its contents. Notice that you can
also change these properties, but these changes do not force iGrid to be
sorted. iGrid redraws its header accordingly to your
changes in these properties and you can use it, for instance, to hide the sort
info in column headers (by setting the ColSortKey
property for each column to zero).
5.4.
The LastSortMode property and the ELastSortModes enumeration were abolished.
6. Two new properties, ColMinWidth and ColMaxWidth,
allow you to specify the minimum and maximum width for a column. The same
effect you can get using the two new parameters of the AddCol
method – lMinWidth and lMaxWidth.
By default the values of these properties equal -1; this means that there is no
restrictions on column size. If you set one or both these properties to a
non-negative value, you specify the corresponding restriction on the column
size; in this case the user can not set the column size to a value less than ColMinWidth and/or greater than ColMaxWidth.
These restrictions also have an influence on changing the column width in your
code – they are checked in such properties and methods as ColWidth
and AutoWidthCol.
All of the methods and properties mentioned in this item also check the
following two conditions: "Column maximum width can not be less than its minimum width"
and "Column width can not be less than its minimum width or greater than
its maximum width". If you violate the first condition in your code, iGrid
raises the new error with the code vbObjectError+519. If you set column width
to a value less than ColMinWidth or greater than ColMaxWidth, iGrid uses the value of ColMinWidth
or ColMaxWidth respectively as the result column
width. iGrid also changes column width in the same way if you set ColMinWidth
to a value greater than the current column width (as well for the ColMaxWidth
property).
7.
iGrid supports OLE Drag-n-Drop now. The new OLEDragMode property
determines whether the component or the programmer handles an OLE drag/drop
operation. iGrid also raises the following OLE Drag-n-Drop events:
·
OLEDragDrop(Data As VBRUN.DataObject, Effect As Long, Button As Integer,
Shift As Integer, x As Single, y As Single)
·
OLEDragOver(Data As VBRUN.DataObject, Effect As Long, Button As Integer,
Shift As Integer, x As Single, y As Single, State As Integer)
·
OLECompleteDrag(Effect As Long)
·
OLEGiveFeedback(Effect As Long, DefaultCursors As Boolean)
·
OLESetData(Data As DataObject, DataFormat As Integer)
·
OLEStartDrag(Data As DataObject, AllowedEffects As Long)
You can
use these events and the OLEDragMode property in the same way like with any VB
standard control.
8. When you select
multiple cells in multiselection mode, the selection is removed from the
selected cells only when you release the mouse button (the previous version
does it when you press the mouse button). This can help you if you implement
drag-n-drop operations for multiple selected cells. You can prohibit this
default behavior using the new bDoDefault parameter of the MouseUp event. This
event also has been supplemented by two new parameters, lRow and lCol, which
returns the row and column of the cell under the mouse pointer when the user
releases the mouse button.
9. iGrid raises the new StartCellDrag(ByVal
Button As Integer, ByVal Shift As Integer, ByVal x As Single, ByVal y As
Single, ByVal lRow As Long, ByVal lCol As Long) event if you press the mouse
button and start to move the mouse pointer greater than 2 pixels in any
direction. iGrid do nothing in that case, but this event is very useful if you
will implement a drag-n-drop operation in your application because this is the best place where you can
start drag-n-drop. This event is raised only for iGrid cells (the lRow and lCol
parameters). The Button parameter indicates what mouse button is pressed, Shift
contains the state of the CTRL, ALT and SHIFT keys.
10. Some features of iGrid
are not accessible depending on the version of your operating system or other
factors. iGrid 2.5 introduces the Supports function that allows you to
determine what features can be used in your application. The Supports function
accepts one of the following ESupportFeatures values:
|
ESupportFeatures
member |
Description |
|
igSupFeatXPStyles |
iGrid
can use XP styles or not |
|
igSupFeatImmedColResizing |
iGrid
can redraw its cells and header as the user is resizing a column |
|
igSupFeatFlatScrollBars |
iGrid
can use the Encarta and Flat styles for its scroll bars |
11.
The MouseMove event was supplemented by the lRow and lCol parameters
which contain the row and column indices of the cell under the mouse pointer;
this event has the following syntax now: MouseMove(ByVal Button As Integer,
ByVal Shift As Integer, ByVal x As Single, ByVal y As Single, ByVal lRow As
Long, ByVal lCol As Long).
12.
iGrid 2.5 introduces the MouseEnter and MouseLeave events for its cells
with the following syntax:
·
MouseEnter(ByVal lRow As Long, ByVal lCol As Long)
·
MouseLeave(ByVal lRow As Long, ByVal lCol As Long)
The first
event is raised when the mouse pointer has just entered the area occupied by
the cell in the lRow row and lCol column. The second event is fired by iGrid
when the mouse pointer has just left this area.
13. The DrawCell(ByVal
vRow As Variant, ByVal vCol As Variant) method was implemented. It allows you
to redraw a particular cell and can be very useful if you need to redraw a
custom draw cell.
14. The CellValue, RowTag,
ColTag properties and values of combo list items can store objects.
Caution. If you manually populate an iGrid control with data from an ADO recordset, iGrid 2.1 allows you to use the code like this:
iGrid1.CellValue(1, 1) = rs!FieldName
In iGrid
2.5 you can not use this code to store the value of the specified field in the
cell because the rs!FieldName expression returns the
reference to the ADO Field object and the reference to this object is stored in
the cell due to the newest feature of iGrid. You should use the following
statement instead of the previous one:
iGrid1.CellValue(1, 1) = rs.Fields(“FieldName”).Value
Notice
that the Fields(...).Value syntax works slightly
faster than rs!FieldName because in the last case VB
must search for the default property (i.e. Value) each time you access the Field
object.
15. iGrid can display row text underneath
normal row cells. iGrid uses the top part of a row to display normal cells. By
default, the height of the row that contains normal cells equals the value of
the DefaultRowHeight property, but you can change this parameter for each row
later using the new RowNormallCellHeight property. The following figure
explains the RowNormallCellHeight property:
16. iGrid 2.5 contains a
lot of new features concerning its scroll bars:
16.1. iGrid scroll bars is
accessible through the HScrollBar and VScrollBar properties of the ScrollBarObject object type.
ScrollBarObject provides you with the following properties: Value, Min, Max, LargeChange, SmallChange,
Thickness, Visible. All of these properties except Value are read-only
properties - you can only change the position of the scroll box using the Value
property.
16.2. The HScrollBarHeight
and VScrollBarWidth properties were abolished – you need to use the Thickness properties
instead of them. This property returns the height of the horizontal scroll bar
or width of the vertical scroll bar depending on the object (HScrollBar or
VScrollBar respectively) it is applied to.
16.3. iGrid 2.5 introduces
the new EScrollBar
enumeration. The members of this enumeration are used mainly in the scroll bars
related events to indicate what scroll bar (horizontal or vertical) has fired
this event:
Enum EScrollBar
igScrollBarH
igScrollBarV
End Enum
16.4. iGrid 2.5 raises the
following new events for its scroll bars:
|
Scroll
bar event |
Description |
|
ScrollBarPosChanged(ByVal
eBar As EScrollBar, ByVal lValue As Long) |
Fired
when the position of a scroll box has been changed (programmatically or interactively) |
|
ScrollBarVisibilityChanged(ByVal
eBar As EScrollBar, ByVal bVisible As Boolean) |
Fired
when a scroll bar is hidden or displayed |
|
ScrollBarEndScroll(ByVal
eBar As EScrollBar) |
Raised
when the user has finished a scrolling operation |
|
ScrollBarThumbTrack(ByVal
eBar As EScrollBar, ByVal lValue As Long) |
Fired
as the user is
dragging the scroll box. This message is raised repeatedly until the user
releases the mouse button. |
|
ScrollBarThicknessChanged(ByVal
eBar As EScrollBar, ByVal lValue As Long) |
Occurs
when the user changes the width of scroll bars in Windows Display Properties
dialog box. |
17.
In iGrid 2.5 you can specify the background color for odd and even rows
using the new BackColorOddRows and BackColorEvenRows properties. If you change
the default value of these properties (-1 or CLR_NONE), iGrid will use the
specified colors to highlight odd and even visible rows.
18.
If you use an external control to edit iGrid cells, the new QuitCustomEdit event can help you to
determine the moment when you need to finish the editing with the external
control. iGrid raises this event in such cases as you click a column header or
scroll its contents, i.e. when you need to hide the external control.
19.
iGrid 2.5 provides you with two new properties that return API handles of
its constituent parts – Header.Hwnd and TextEditHwnd. Notice that the last
property is valid only while the user is editing a text cell and can be changed
if he/she starts to edit another text cell.
20.
iGrid 2.5 allows you to implement your own context menu for text box
cells; this menu can be displayed only while the user is editing a text cell.
To hide the default context menu for such cells and display your own context
menu, set the new TextEditCustomContextMenu property to True (the default value
is False) and iGrid will raise the new TextEditCustomContextMenu(ByVal lRow As
Long, ByVal lCol As Long) event when the user presses the right mouse button
(or SHIFT+F10) in a text cell while he/she is editing it; then you can display
your own context menu in this event.
21.
There are the following new events raised by iGrid while the user is
editing text box cells:
·
TextEditMouseDown(ByVal lRow As Long, ByVal lCol As Long, ByVal Button
As Integer, Shift As Integer, ByVal X As Single, ByVal Y As Single)
·
TextEditMouseMove(ByVal lRow As Long, ByVal lCol As Long, ByVal Button
As Integer, ByVal Shift As Integer, ByVal X As Single, ByVal Y As Single)
·
TextEditMouseUp(ByVal lRow As Long, ByVal lCol As Long, ByVal Button As
Integer, ByVal Shift As Integer, ByVal X As Single, ByVal Y As Single)
·
TextEditDblClick(ByVal lRow As Long, ByVal lCol As Long)
22.
iGrid 2.5 allows you to change the values of the TextEditText,
TextEditSelStrart, TextEditSelLength and TextEditSelText properties while the
user is editing a text box cell (all of these properties are read-only in iGrid
2.1).
23.
The RequestEdit event was supplemented by the eTextEditOpt parameter of
the new ETextEditFlags enumeration. This parameter passed by reference allows
you to use the following effects when the user edit a text cell:
|
ETextEditFlags
member |
Description |
|
igTextEditNumberOnly |
Allows
only digits to be entered into the cell. |
|
igTextEditUpperCase |
Converts
all characters to uppercase as they are typed into the cell. |
|
igTextEditLowerCase |
Converts
all characters to lowercase as they are
typed into the cell. |
24.
Two new properties, HighlightBackColorNoFocus and
HighlightForeColorNoFocus, are used by iGrid to highlight selected cells when
it has no focus. Using these properties, for instance, you can even hide the
selection in iGrid if it has no focus by setting these properties to the
background and foreground color of the selected cells (if they use the same
corresponding colors).
25.
iGrid cell has the following default values of its properties: CellTextFlags = igTextLeft Or igTextSingleLine Or igTextEndEllipsis,
CellIndent = 2 and CellRightIndent = 2. This means that
cell text is left aligned, has indent in 2 pixels at left and right and
finished by ellipsis if cell text does not fit the cell.
26.
Cells in iGrid 2.5 can have the right indent. The right indent can be
set for each cell separately using the new CellRightIndent property.
27.
Two new methods, EnsureVisibleRow and EnsureVisibleCol, were
implemented. They have the following syntax:
·
EnsureVisibleRow(ByVal vRow As Variant, Optional ByVal eMode As
EEnsureVisibleRowMode = igEnsVisRowAuto, Optional ByVal lGap As Long = 8)
·
EnsureVisibleCol(ByVal vCol As Variant, Optional ByVal eMode As
EEnsureVisibleColMode = igEnsVisColAuto, Optional ByVal lGap As Long = 8)
The EnsureVisibleRow method allows you to scroll iGrid so the user will
see the row specified by the vRow parameter. If you omit the eMode parameter or
specify its default value, iGrid scrolls its contents to display the specified
row at the top of its visible area if the row is higher than the grid top edge
or scrolls its contents to display the specified row at the bottom of its
visible area if the row is below than the grid bottom edge; if the specified
row is visible, iGrid does not scrolls its contents. All other eMode values
allow you to redefine this behaviour:
|
EEnsureVisibleRowMode
member |
Description |
|
igEnsVisRowAuto |
The
default behaviour. |
|
igEnsVisRowTop |
Scrolls
iGrid to display the specified row at the top edge. If the row is in the
visible part of the grid, the grid is not scrolled. |
|
igEnsVisRowTopForce |
Scrolls
iGrid to display the specified row at the top edge regardless whether the row
is in the visible part or not. |
|
igEnsVisRowBottom |
Scrolls
iGrid to display the specified row at the bottom edge. If the row is in the
visible part of the grid, the grid is not scrolled. |
|
igEnsVisRowBottomForce |
Scrolls
iGrid to display the specified row at the bottom edge regardless whether the
row is in the visible part or not. |
The lGap parameter specify the distance between the top edge of iGrid
visible part and the top edge of the row or between the bottom edge of iGrid and
the bottom edge of the row depending on the value of the eMode parameter.
The EnsureVisibleCol method works in the same way but it is applied to
iGrid columns.
Notice that the EnsureVisibleCell is not the same as the issuing
EnsureVisibleRow and EnsureVisibleCol for the same cell. The EnsureVisibleCell
method takes into account grouped cells, but EnsureVisibleRow and
EnsureVisibleCol work only with rows and columns regardless of cells they
contain.
28.
If you need to know the coordinates and indices of rows and cols which
are displayed in the visible part of the grid, use the new GetStartEndCell(ByRef lStartRow
As Long, ByRef lStartCol As
Long, ByRef lStartX As
Long, ByRef lStartY As
Long, ByRef lEndRow As
Long, ByRef lEndCol As
Long, ByRef lEndX As Long, ByRef lEndY As Long) method.
29.
iGrid raises the new ContentsSorted event just after the user has clicked a column
header and iGrid has sorted its contents.
30.
The SetHeightInItems method of ComboObject was replaced on the MaxHeightInItems
property. This property allows you to specify the maximum number of visible
items in the drop down part of a combo list. Notice that if the total number of
items is less than MaxHeightInItems, iGrid automatically
fits the height of the drop down part to display only the existing items (i.e.
the blank area after the last item is absent). The previous version of iGrid
(2.1) does not do it and you should issue the SetHeightInItems
method in this version. The default value of the MaxHeightInItems
property is 8.
31.
Other changes in iGrid methods, events and properties:
·
The bCancel parameter was removed from the StartColWidthChange, ColWidthChanging
and ColWidthChanged events.
·
The vKeyBefore parameter of the AddCol method was renamed to vColBefore.
·
The ColHeaderImage property was renamed on ColHeaderIcon.
·
The EnsureVisible method has the EnsureVisibleCell name now.