• Download Grid Control Source and Demo - 311.9 KB

Preface

This grid is the work of thousands of hours of squinting at pixels, hunting memory leaks, adding new features, fixing new bugs and beating the code by force of will into a form that is as feature rich and useable as something of this form can be. Dozens of developers from all over the world have contributed fixes, improvements and suggestions over the 4 years that the grid has been growing, and there is still no end in sight. Most of the fixes have been sent in by readers so I'm trusting that they have done sufficient testing.

Release 2.27 is a minor update of 2.26 for Visual Studio 2010 and includes a couple of minor bug fixes. Version 2.26 has is still available for download above.

Contents

Introduction

After pushing the CListCtrl to its limits in trying to display and edit tabulated data I decided what was really needed was a dedicated grid control. I started writing my own grid control from scratch but decided to save time by modifying Joe Willcoxson's free WorldCom grid control at http://users.aol.com/chinajoe/wcmfclib.html. I tore apart his code and rebuilt it from the ground up in order to get it to do all the things I needed. The code has gone through so many modifications that I'm not sure if there is even a single original line of code. In any case Joe's code was a great framework on which to build.

The project started out as a simple clean up but very quickly ballooned into a bit of a nightmare as I kept finding new features that I felt just had to go into it. It has not been tested exhaustively - but I'm fairly confident that it won't fall over too badly  . Joe was kind enough to allow me to release the source with no strings attached (since it is based on his code) but since the project was such a marathon I am placing a couple of very minor conditions on the use of this code:

This code may be used in compiled form in any way you desire (including commercial use). The code may be redistributed unmodified by any means providing it is not sold for profit without the authors written consent, and providing that this notice and the authors name and all copyright notices remains intact. However, this file and the accompanying source code may not be hosted on a website or bulletin board without the authors written permission.

This software is provided "as is" without express or implied warranty. Use it at your own risk!

Whilst I have made every effort to remove any undesirable "features", I cannot be held responsible if it causes any damage or loss of time or data.

The control features:

• Cell selection using the mouse, with optional Control and Shift key combinations. Selection can be disabled.
• Row and Column resizing. Sizing can be disabled for row, columns or both.
• Auto row or column sizing when dividers are double-clicked.
• Any number of fixed rows and columns.
• Individual cells can have separate text and background colours.
• Individual cells can have separate fonts.
• Individual cells can be marked "Read-Only", or have their modification status set and checked.
• OLE Drag and drop.
• Ctrl-C, Ctrl-X and Ctrl-V perform clipboard copy, cut and paste, and Ctrl-A for "Select All"
• In place editing of cell contents. If a character key is pressed while a cell has focus, editing will start on that cell, and the arrow keys will allow navigation to other keys. If the current focus cell is clicked on, editing will start and the arrow keys will move the carat inside the edit control. Editing can be disabled.
• Support for Microsoft intellimouse.
• Optional grid lines.
• Images in any cell
• "Virtual" mode for large datasets
• Full printing support, for either a Doc/View environment (inc Print preview) or a standalone dialog based app (no print preview).
• Optional "List mode", including full row selection, single row selection, and sort on column header click.
• Numerous virtual functions to allow this control to be extended very easily.
• Unicode support.
• WinCE support
• Titletips for cells that are too small to display their data.
• Hidden rows and columns
• Compiles under VC 4.2, 5.0, 6.0 and under the CE toolkit version 2.0 and 3.0

Files

To use the Grid control in your project you will need to add a number of files to your project:

gridctrl.cpp, gridctrl.h	Main grid control source and header files.
gridcellbase.cpp, gridcellbase.h	Main grid cell base class.
gridcell.cpp, gridcell.h	Main grid cell default class implementation.
CellRange.h	Definition of CCellID and CCellRange helper classes.
MemDC.h	Keith Rule's memory DC helper class.
InPlaceEdit.cpp, InPlaceEdit.h	In-place edit windows source and header files.
GridDropTarget.cpp, GridDropTarget.h	Grid control OLE drag and drop target. Only necessary if you don't define GRIDCONTROL_NO_DRAGDROP in gridctrl.h
Titletip.cpp, Titletip.h	Titletips for cells, from Zafir Anjum. Only necessary if you don't define GRIDCONTROL_NO_TITLETIPS in gridctrl.h

Structure

The grid is based on a framework (the CGridCtrl object) that organises and controls a collection of cells (CGridBaseCell) that contain the data, perform operations such as drawing, and handle methods such as button clicks. The grid object itself handles events such as button clicks before the cells get a chance, and will pass on certain mouse messages if it considers it necessary. The grid also contains a drag and drop target (CGridDropTarget) that is registered to handle drop notifications, and there is also a title tip object (CTitleTip) that displays the contents of cells when the physical dimensions of a cell are insufficient to display its' contents in their entirety.

The grid cells can be of any type as long as the class is derived from CGridBaseCell. Included with the package is a CGridCell class that handles basic data storage and editing. Extensions such as the CGridCellCombo andCGridURLCell class demonstrate how to create your own cell classes.

There are two main types of cell - fixed and non-fixed. Fixed cells are typically on the left and top of the grid and do not move when the grid is scrolled. Typically these contain column and row headings and are not editable. Non fixed cells make up the "interior" of the grid and can be edited and selected.

Default values for various properties of the grid are stored in CGridDefaultCell objects. There are currently 4 of these objects per grid - one each to hold default values for the non-fixed cells, fixed columns, foxed rows, and cells that are both fixed rows and columns cells. Thus in order to set a default property for the grid, useCGridCtrL::GetDefaultCell to get the default cell implementation you are after, then set it's values directly.

Cells hold their property values explicitely, except for the font property. Each cell holds a pointer to a font structure, and this pointer is only allocated and used if you set that cell's font to a non-default value.

The grid also has a virtual mode that stops the grid from actually creating cells, and allows you to specify either a callback funtion or message handler that the grid will call each time it needs information on a cell. This saves enourmously on memory at the expense of slightly decreased performance. There is a GVN_ODCACHEHINTmessage that is sent to the grid's parent that will help you cache data in preparation for the grid's cell info requests.

Grid cells are stored row-by-row, so all operations on large numbers of cells should be done row-by-row as well.

Construction

OK - so how do you use it?

The underlying class of the grid control is CGridCtrl which is derived from CWnd. To use it, either use the MS Visual C++ dialog editor to place a custom control on a dialog, and enter "MFCGridCtrl" (no quotes) as the Class name. To subclass the control using the DDX mechanism (this will be done by default by the ClassWizard) use theDDX_GridControl function instead of the DDX_Control function (just manually change the ClassWizard entry). This ensures your control is correctly registered as a drop target and avoids some weird win95 issues.

Alternatively you can use CGridCtrl::Create:

Hide   Copy Code

CGridCtrl grid;
grid.Create(rect, pParentWnd, nID);

Number of rows and columns

Sizing and position functions

BOOL GetCellOrigin(int nRow, int nCol, 
                   LPPOINT p)

BOOL GetCellOrigin(const CCellID& cell, 
                   LPPOINT p)

BOOL GetCellRect(int nRow, int nCol, 
                 LPRECT pRect)

BOOL GetCellRect(const CCellID& cell, 
                 LPRECT pRect)

BOOL GetTextRect(int nRow, int nCol, 
                 LPRECT pRect)t

BOOL GetTextRect(const CCellID& cell, 
                 LPRECT pRect)

BOOL GetTextExtent(int nRow, int nCol, 
                   LPCTSTR str)

Reordering Rows and Columns

Virtual Mode

Virtual mode allows you to use the grid to display large amounts of data without requiring the grid to actually store this data. In Virtual Mode, no cells are created and no data is stored other than the widths and heights of columns and rows.

Since the data is not stored by the grid, the grid must have some way of asking the application to supply it with data. This is done either by either registering a callback function with the grid, or by having the parent handle aGVN_GETDISPINFO notification.

void SetCallbackFunc(GRIDCALLBACK pCallback, 
                     LPARAM lParam) 

If no callback function is specified then the grid will send a GVN_GETDISPINFO message to it's parent. AGV_DISPINFO structure part of this notification, and looks like:

Hide   Copy Code

typedef struct tagGV_DISPINFO {
    NMHDR   hdr;
    GV_ITEM item;
} GV_DISPINFO;

Obviously it's nice to have a hint as to what sort of data the grid will be asking for in order to allow caching, so the grid sends out a GVN_ODCACHEHINT message before displaying a page of cells. A GV_CACHEHINT structure is sent as part of this message and looks like:

Hide   Copy Code

typedef struct tagGV_CACHEHINT {
    NMHDR      hdr;
    CCellRange range;
} GV_CACHEHINT;

An example of handling these messages is as follows:

Hide   Shrink    Copy Code

// m_Grid is a member variable of a dialog class that is handling
// this message
BOOL CGridCtrlDemoDlg::OnNotify(WPARAM wParam, LPARAM lParam, 
                                LRESULT* pResult) 
{
    if (wParam == (WPARAM)m_Grid.GetDlgCtrlID())
    {
        *pResult = 1;
        GV_DISPINFO *pDispInfo = (GV_DISPINFO*)lParam;
        if (GVN_GETDISPINFO == pDispInfo->hdr.code)
        {
            //TRACE2("Getting Display info for cell %d,%d\n", 
                     pDispInfo->item.row, pDispInfo->item.col);
            pDispInfo->item.strText.Format(_T("Message %d,%d"),
                     pDispInfo->item.row, pDispInfo->item.col);
            return TRUE;
        }
        else if (GVN_ODCACHEHINT == pDispInfo->hdr.code)
        {
            GV_CACHEHINT *pCacheHint = (GV_CACHEHINT*)pDispInfo;
            TRACE(_T("Cache hint received for cell range %d,%d - %d,%d\n"),
                  pCacheHint->range.GetMinRow(), 
                  pCacheHint->range.GetMinCol(),
                  pCacheHint->range.GetMaxRow(), 
                  pCacheHint->range.GetMaxCol());
        }
    }
    
	return CDialog::OnNotify(wParam, lParam, pResult);
}

You can use SetCallbackFunc to set a callback function that the grid will call directly instead of sending aGVN_GETDISPINFO message. A GVN_ODCACHEHINT message will still be send if a callback is used.

The callback function should be of the form:

Hide   Copy Code

BOOL CALLBACK CallbackFunction(GV_DISPINFO * pDispInfo, LPARAM lParam);

For example:

Hide   Copy Code

BOOL CALLBACK CGridCtrlDemoDlg::GridCallback(GV_DISPINFO *pDispInfo, 
                                             LPARAM /*lParam*/) 
{
    pDispInfo->item.strText.Format(_T("Callback %d,%d"),
                          pDispInfo->item.row, pDispInfo->item.col);
    return TRUE;
}

When calling SetCallbackFunc you can specify an LPARAM value that will be passed to the callback function each time it is called. Note that the callback function must be a static or global function.

General appearance and features

Colours

The following functions are no longer supported. You should use GetDefaultCell to get the default cell implementation for the cell type you are intererested in, then set that cell's properties directly. If a given cell has default values set, then it will use the values in the default cell implementation that matches that cell type.

See also the Individual Cell colour functions that allow an individual cell's colours to be changes seperate to the rest of the grid.

General cell information

CGridCellBase* GetDefaultCell(BOOL bFixedRow, 
                        BOOL bFixedCol) const

BOOL SetCellType(int nRow, int nCol, 
                CRuntimeClass* pRuntimeClass);

void SetModified(BOOL bModified = TRUE, 
                 int nRow = -1, int nCol = -1)

BOOL SetItemData(int nRow, int nCol, 
                 LPARAM lParam)

BOOL SetItemImage(int nRow, int nCol, 
                  int iImage)

BOOL SetItemState(int nRow, int nCol, 
                  UINT state)

BOOL SetItemFormat(int nRow, int nCol, 
                   UINT nFormat)

CCellID SetFocusCell(CCellID cell);
CCellID SetFocusCell(int nRow, int nCol);

BOOL SetItemBkColour(int nRow, int nCol, 
                COLORREF cr = CLR_DEFAULT)

BOOL SetItemFgColour(int nRow, int nCol,
                COLORREF cr = CLR_DEFAULT)

BOOL SetItemFont(int nRow, int nCol, 
                 LOGFONT* lf)

BOOL IsCellVisible(CCellID &cell) const
BOOL IsCellVisible(CCellID cell) const

BOOL IsCellEditable(CCellID &cell) const
BOOL IsCellEditable(CCellID cell) const

BOOL IsCellSelected(CCellID &cell) const
BOOL IsCellSelected(CCellID cell) const

Operations

int InsertColumn(LPCTSTR strHeading,   
           UINT nFormat, int nColumn = -1)

int InsertRow(LPCTSTR strHeading, 
              int nRow = -1)

BOOL AutoSizeColumn(int nCol, 
        UINT nAutoSizeStyle = GVS_DEFAULT, 
        BOOL bResetScroll = TRUE)

void SetRedraw(BOOL bAllowDraw,   
               BOOL bResetScrollBars = FALSE)

BOOL RedrawCell(int nRow, int nCol, 
                CDC* pDC = NULL)

BOOL RedrawCell(const CCellID& cell, 
                CDC* pDC = NULL)

void SetSelectedRange(const CCellRange& Range,
                  BOOL bForceRepaint = FALSE);

void SetSelectedRange(int nMinRow, int nMinCol,
                      int nMaxRow, int nMaxCol,
                    BOOL bForceRepaint = FALSE);

CCellID GetNextItem(CCellID& cell, int nFlags)
 const

Sorting

BOOL SortTextItems(int nCol, BOOL bAscending, 
                   LPARAM data = 0)

BOOL SortItems(int nCol, BOOL bAscending, 
               LPARAM data = 0)

BOOL SortItems(PFNLVCOMPARE pfnCompare, int nCol,
               BOOL bAscending, LPARAM data = 0)

Sorting is achieved by calling one of the variants of SortItems, SortTextItems, or by the user clicking on a column header when in list mode. 

The simplest way to handle sorting is to set the function that will be used in cell comparisons (by callingSetCompareFunction and/or SetVirtualCompare) and then calling SortItems(int nCol, BOOL bAscending, LPARAM data = 0). nCol is the column to sort, bAscending sets whether the sort is in ascending or descending order, and data is application specific data that will be passed to the comparison function.

The comparison function must be a global or static function with the form

Hide   Copy Code

int CALLBACK pfnCellCompare(LPARAM lParam1, LPARAM lParam2, LPARAM lParamSort)

lParam1 and lParam2 will be CGridCellBase pointers, and lParamSort will be the application specific data you pass into the SortItems function as the data parameter. The function must return -1 if the first cell contains a value less than the second cell; 0 if they are equal, otherwise 1.

An example of a sort comparison function is as follows:

Hide   Copy Code

int CALLBACK MyClass::pfnCellNumericCompare(LPARAM lParam1,
                                            LPARAM lParam2, 
                                            LPARAM lParamSort)
{
	CGridCellBase* pCell1 = (CGridCellBase*) lParam1;
	CGridCellBase* pCell2 = (CGridCellBase*) lParam2;
	if (!pCell1 || !pCell2) return 0;

	int nValue1 = _ttol(pCell1->GetText());
	int nValue2 = _ttol(pCell2->GetText());

	if (nValue1 < nValue2)
		return -1;
	else if (nValue1 == nValue2)
		return 0;
	else
		return 1;
}

Two functions have been provided for your convenience:

Hide   Copy Code

int CALLBACK CGridCtrl::pfnCellTextCompare(LPARAM lParam1, 
                                           LPARAM lParam2, 
                                           LPARAM lParamSort)
int CALLBACK CGridCtrl::pfnCellNumericCompare(LPARAM lParam1, 
                                              LPARAM lParam2, 
                                              LPARAM lParamSort)

These sort by Text value and by numeric value (using itoa respectively. To set the comparison function for the grid simply call:

Hide   Copy Code

m_Grid.SetCompareFunction(CGridCtrl::pfnCellNumericCompare);

If the comparison function is set as NULL, CGridCtrl::pfnCellTextCompare will be used by default.

Sorting in Virtual mode requires you provide a function with the signature bool (*PVIRTUALCOMPARE)(int, int); to the function SetVirtualCompare. Needless to say this function will have to be optimised if you are trying to sort large amounts of data.

Printing

virtual void OnBeginPrinting(CDC *pDC, 
                  CPrintInfo *pInfo)

virtual void OnEndPrinting(CDC *pDC, 
                  CPrintInfo *pInfo)

void SetPrintMarginInfo(int nHeaderHeight, 
       int nFooterHeight, int nLeftMargin, 
       int nRightMargin, int nTopMargin, 
       int nBottomMargin, int nGap)

void GetPrintMarginInfo(int &nHeaderHeight, 
       int &nFooterHeight, int &nLeftMargin, 
       int &nRightMargin, int &nTopMargin, 
       int &nBottomMargin, int &nGap)

Structures, defines and Messages

The CGridCellBase class

This class is the base class for all grid cell classes, and holds the information for each cell. The class also defines a number of methods that are called by the grid itself, such as drawing and printing. Almost all methods and functions are virtual and this class is not designed to be used directly - rather it should be derived from. The default class CGridCell is derived from CGridCellBase and is used by the Grid control as the default cell class.

Attributes

Hide   Shrink    Copy Code

virtual void SetText(LPCTSTR szText);
virtual void SetImage(int nImage);
virtual void SetData(LPARAM lParam);
virtual void SetState(DWORD nState);
virtual void SetFormat(DWORD nFormat);
virtual void SetTextClr(COLORREF clr);
virtual void SetBackClr(COLORREF clr);
virtual void SetFont(const LOGFONT* plf);
virtual void SetGrid(CGridCtrl* pGrid);
virtual void SetCoords(int nRow, int nColumn);
virtual void SetMargin(UINT nMargin);

virtual LPCTSTR  GetText() const         // returns the text in the cell
virtual LPCTSTR  GetTipText() const      // return alternate tooltip text 
                                         // if you wish 
virtual int      GetImage() const        // returns image index for cell
virtual LPARAM   GetData() const         // returns data associated with cell
virtual DWORD    GetState() const        // returns cell state
virtual DWORD    GetFormat() const       // returns cell format
virtual COLORREF GetTextClr() const      // returns cell text color
virtual COLORREF GetBackClr() const      // returns cell background color
virtual LOGFONT* GetFont() const         // returns cell font as a LOGFONT
virtual CFont*   GetFontObject() const   // returns a CFont object with the 
                                         // cell's font
virtual UINT     GetMargin() const       // returns internal margin for cell
virtual CGridCtrl* GetGrid() const       // returns grid that cell is associated 
                                         // with
virtual CWnd*    GetEditWnd() const      // returns editing window for cell, 
                                         // or NULL
    
virtual BOOL IsEditing() const
virtual BOOL IsFocused()  const 
virtual BOOL IsFixed()    const 
virtual BOOL IsFixedCol() const
virtual BOOL IsFixedRow() const
virtual BOOL IsSelected() const 
virtual BOOL IsReadOnly() const
virtual BOOL IsModified() const
virtual BOOL IsDropHighlighted() const
virtual BOOL IsDefaultFont() const       // TRUE if cell is using default
                                         // font in grid

virtual CGridCellBase* GetDefaultCell() const;

Operators

Hide   Copy Code

virtual void operator=(CGridCellBase& cell);

Operations

Hide   Copy Code

virtual void Reset();

virtual BOOL Draw(CDC* pDC, int nRow, int nCol, CRect rect, 
                  BOOL bEraseBkgnd = TRUE);
virtual BOOL GetTextRect( LPRECT pRect)     - dimensions of text 
                                              within cell
virtual BOOL GetTipTextRect( LPRECT pRect)  - boundary for tooltips
virtual CSize GetTextExtent(LPCTSTR str)    - size of text
virtual CSize GetCellExtent(CDC* pDC)       - size of cell

// start and stop cell editing
virtual BOOL Edit(int nRow, int nCol, CRect rect, 
                  CPoint point, UINT nID, UINT nChar) 
virtual void EndEdit()

// Validates the results of an edit. If "str" is not a valid 
// value for the
// cell then  return FALSE to have the edit rejected
virtual BOOL ValidateEdit(LPCTSTR str);

virtual BOOL PrintCell(CDC* pDC, int nRow, int nCol, CRect rect);

// This can ONLY be called by CGridCellBase derived classes, and 
// not CGridCellBase itself.
LRESULT SendMessageToParent(int nRow, int nCol, int nMessage);

Overridables

Hide   Copy Code

virtual void OnEndEdit();
virtual void OnMouseEnter();
virtual void OnMouseOver();
virtual void OnMouseLeave();
virtual void OnClick( CPoint PointCellRelative);
virtual void OnClickDown( CPoint PointCellRelative);
virtual void OnRClick( CPoint PointCellRelative);
virtual void OnDblClick( CPoint PointCellRelative);
virtual BOOL OnSetCursor();

This makes customising cells extremely simple. To install a new type of derived class for your grid cells, you can either override CGridCtrl::CreateCell and create your derived CGridCellBase cells, or you can useCGridCtrl::SetCellType and CGridCtrl::SetDeafaultCellType to automate this.

Simply create a new cell class derived from CGridCellBase or CGridCell (eg. CMyGridCell), and then replace the cells in the grid by calling

Hide   Copy Code

MyGrid.SetCellType(row, column, RUNTIME_CLASS(CMyGridCell));

The cell at (row,column) will now be of type CMyGridCell.

The CGridCell class

This class is derived from CGridCellBase and provides a default implementation for use with CGridCtrl.

The CCellID class

Hide   Copy Code

class CCellID
{    
public:
    int row, col; // The zero based row and column of the cell.

    CCellID(int nRow = -1, int nCol = -1)

    int IsValid();
    int operator==(const CCellID& rhs);
    int operator!=(const CCellID& rhs);
}

The CCellRange class

This is a handy helper class used to reference cell ranges. This class is adapted from Joe Willcoxsons original implementation.

Hide   Shrink    Copy Code

class CCellRange
{ 
public:
    CCellRange(int nMinRow = -1, int nMinCol = -1, 
               int nMaxRow = -1, int nMaxCol = -1);
    void Set(int nMinRow = -1, int nMinCol = -1, 
             int nMaxRow = -1, int nMaxCol = -1);
    
    int  IsValid() const;
    int  InRange(int row, int col) const;       // Is the row/col in the range?
    int  InRange(const CCellID& cellID) const;  // is the cell in the range?
    
    CCellID  GetTopLeft() const;                // Get topleft cell in range
    CCellRange Intersect(const CCellRange& rhs) const; 
                                                // Returns the intersection of
                                                // two cell ranges

    int GetMinRow() const;                      // Self explanatory
    void SetMinRow(int minRow);
    int GetMinCol() const;
    void SetMinCol(int minCol);
    int GetMaxRow() const;
    void SetMaxRow(int maxRow);
    int GetMaxCol() const;
    void SetMaxCol(int maxCol);

    int GetRowSpan() const;                    // Number of rows spanned
    int GetColSpan() const;                    // Number of columns spanned
    
    void operator=(const CCellRange& rhs);
    int  operator==(const CCellRange& rhs);
    int  operator!=(const CCellRange& rhs);
}

The GV_ITEM structure. This structure is used for Get/SetItem calls.

Hide   Copy Code

typedef struct _GV_ITEM {
        int      row,col;   // Row and Column of item
        UINT     mask;      // Mask for use in getting/setting cell data
        UINT     state;     // cell state (focus/hilighted etc)
        UINT     nFormat;   // Format of cell. Default imaplentation 
                            // used CDC::DrawText formats
        CString  szText;    // Text in cell
        int      iImage;    // index of the list view item’s icon
        COLORREF crBkClr;   // Background colour (or CLR_DEFAULT)
        COLORREF crFgClr;   // Forground colour (or CLR_DEFAULT)
        LPARAM   lParam;    // 32-bit value to associate with item
        LOGFONT  lfFont;    // cell font
} GV_ITEM;

Hide   Copy Code

GVL_NONE      // No grid lines
GVL_HORZ      // Horizontal lines only
GVL_VERT      // Vertical lines only
GVL_BOTH      // Both vertical and horizontal lines

Hide   Copy Code

GVS_DEFAULT   // default 
GVS_HEADER    // Size using column fixed cells data only
GVS_DATA      // Size using column non-fixed cells data only
GVS_BOTH      // Size using column fixed and non-fixed

Hide   Copy Code

GVIF_TEXT      // Cell text will be accessed
GVIF_IMAGE     // Cell image number will be accessed
GVIF_PARAM     // Cell user data (lParam) will be accessed
GVIF_STATE     // Cell state will be accessed
GVIF_BKCLR     // Cell background colour will be accessed
GVIF_FGCLR     // Cell foreground colour will be accessed
GVIF_FORMAT    // Cell format field will be accessed
GVIF_FONT      // Cell logical font will be accessed
GVIF_MARGIN    // Cell margin information will be accessed 
GVIF_ALL       // All information will be accessed 

Hide   Copy Code

GVIS_FOCUSED     // Cell has focus
GVIS_SELECTED    // Cell is selected
GVIS_DROPHILITED // Cell is drop highlighted
GVIS_READONLY    // Cell is read-only and cannot be edited
GVIS_FIXED       // Cell is fixed
GVIS_FIXEDROW    // Cell is part of a fixed row
GVIS_FIXEDCOL    // Cell is part of a fixed column
GVIS_MODIFIED    // Cell has been modified

Hide   Copy Code

GVNI_FOCUSED     // Search for focus cell
GVNI_SELECTED    // Search for selected cells
GVNI_DROPHILITED // Search for drop highlighted cells
GVNI_READONLY    // Search for read-only cells
GVNI_FIXED       // Search for fixed cells 
GVNI_MODIFIED    // Search for modified cells

GVNI_ABOVE       // Search above initial cell
GVNI_BELOW       // Search below initial cell
GVNI_TOLEFT      // Search to the left of the initial cell
GVNI_TORIGHT     // Search to the right of the initial cell
GVNI_ALL         // Search all cells in the grid starting from
                 // the given cell
GVNI_AREA        // Search all cells below and to the right of 
                 // the given cell

Hide   Copy Code

GVN_BEGINDRAG      // Sent when dragging starts
GVN_BEGINLABELEDIT // Sent when inplace editing starts
GVN_ENDLABELEDIT   // Sent when inplace editing stops
GVN_SELCHANGING    // Sent just before cell selection changes
GVN_SELCHANGED     // Sent after cell selection changes
GVN_GETDISPINFO    // A request for cell information when the grid is 
                   // in virtual mode
GVN_ODCACHEHINT    // Cache hint when in virtual mode

These messages are exactly the same as their LVN_... counterparts, except they use an NM_GRIDVIEW structure:

Hide   Copy Code

typedef struct tagNM_GRIDVIEW { 
    NMHDR hdr; 
    int   iRow; 
    int   iColumn; 
} NM_GRIDVIEW;

Protected overridable functions

These functions have been made virtual to aid extensiblity.

Printing - called in OnPrint.

Hide   Copy Code

virtual void PrintColumnHeadings(CDC *pDC, CPrintInfo *pInfo);
virtual void PrintHeader(CDC *pDC, CPrintInfo *pInfo); 
virtual void PrintFooter(CDC *pDC, CPrintInfo *pInfo);
virtual void PrintRowButtons(CDC *pDC, CPrintInfo* pInfo);

Drag n' drop

Hide   Copy Code

// No longer necessary but I thought the code was cool so kept it :).
virtual CImageList* CreateDragImage(CPoint *pHotSpot)  

Mouse Clicks

Hide   Copy Code

virtual void OnFixedColumnClick(CCellID& cell);
virtual void OnFixedRowClick(CCellID& cell);

Editing

Hide   Copy Code

// Starting edit
virtual void OnEditCell(int nRow, int nCol, CPoint point, 
                        UINT nChar) 
// ending edit
virtual void OnEndEditCell(int nRow, int nCol, CString str) 
// Create the inplace edit control
virtual void CreateInPlaceEditControl(CRect& rect, DWORD dwStyle, 
                                      int nRow, int nCol,
                                      LPCTSTR szText, int nChar)

Drawing

Hide   Copy Code

virtual void OnDraw(CDC& origDC);  // Draws everything

Construction and Cleanup

Hide   Copy Code

// Creates a new cell and initialises it.
virtual CGridCellBase* CreateCell(int nRow, int nCol)
                                                     
// Destroys a cell and performs any cleanup necessary
virtual void DestroyCell(int nRow, int nCol)

Clipboard

A number of Clipboard functions have been included.

Cell Editing and Validation

There are several ways you can control whether or not cells can be edited, or indeed whether or not changes to cells should be accepted or rejected.

The simplest is to use SetEditable(BOOL). This determines whether or not the cells in the grid can be edited. Finer scale control can be achieved by setting the GVIS_READONLY flag on a particular cell:

Hide   Copy Code

int row = 1;
int col = 10;
m_Grid.SetItemState(row,col, m_Grid.GetItemState(row,col) | GVIS_READONLY);

Further control can be achieved by handling the GVN_BEGINLABELEDIT message. If the return value for this message is < 0 then the edit attempt for the given cell will be rejected and the cell will be treated as read-only. This message is sent each time an edit attempt is made on a cell.

To handle the message, add a handler in your main window:

Hide   Copy Code

BEGIN_MESSAGE_MAP(CGridCtrlDemoDlg, CDialog)
	...
	// Add a handler
	ON_NOTIFY(GVN_ENDLABELEDIT, IDC_GRID, OnGridEndEdit)
END_MESSAGE_MAP()

...

// GVN_ENDLABELEDIT
void CGridCtrlDemoDlg::OnGridStartEdit(NMHDR *pNotifyStruct, 
                                       LRESULT* pResult)
{
    NM_GRIDVIEW* pItem = (NM_GRIDVIEW*) pNotifyStruct;
    
    // AllowCellToBeEdited is a fictional routine that should return TRUE 
    // if you want to allow the cell to be edited.
    BOOL bAllowEdit = AllowCellToBeEdited(pItem->iRow, pItem->iColumn);

    *pResult = (bAllowEdit)? 0 : -1;
}

Accepting or rejecting the new edited value for the cell can be achieved by handling the GVN_ENDLABELEDITmessage in the same way

Hide   Copy Code

// GVN_ENDLABELEDIT
void CGridCtrlDemoDlg::OnGridEndEdit(NMHDR *pNotifyStruct, 
                                     LRESULT* pResult)
{
    NM_GRIDVIEW* pItem = (NM_GRIDVIEW*) pNotifyStruct;
    
    // AcceptChange is a fictional routine that should return TRUE
    // if you want to accept the new value for the cell.
    BOOL bAcceptChange = AcceptChange(pItem->iRow, pItem->iColumn);

    *pResult = (bAcceptChange)? 0 : -1;
}

The final validation method you can use is to derive a new CGridCellBase class and override the ValidateEditmethod. If this method returns TRUE then the edit is accepted, otherwise the edit is rejected.

Acknowledgements

This would not have been possible without the following authors making their code freely available:

• Joe Willcoxson: Joe's original code spurred this project on, and provided the basic structure of this grid control.
• Keith Rule: Keith provided a neat CMemDC class to make flicker free display simple, and provided sample OLE copy/paste/drag/drop code.
• Ravi Reddy: I used a derivation of Ravi's listview printing code.
• Zafir Anjum: Provided the starting point for my CInPlaceEdit, the sorting routines and the TitleTip code.
• Eric Woodruff, Brian V. Shifrin, Scot Reed, Aqiruse, Ken Bertelson, Martin Daly for updates to the version 2.X classes - plus all the dozens that helped with previous versions.
• All those who freely contribute code to one another: Without you all I would not have been able to write this.
• All those who sent in bug reports, suggestions, improvements and encouragement. Thank you!

History

Version	Comments
1.0 - 1.13 20 Feb 1998 - 6 May 1999	First release version. Progressed from being a basic grid based on the original WorldCom Grid control written by Joe Willcoxson (mailto:chinajoe@aol.com, http://users.aol.com/chinajoe) to something a little more feature rich. Rewritten so many times I doubt there is a single line of Joe's code left. Many, many, MANY people sent in bug reports and fixes. Thank you all.
2.0 16 Feb 2000	Rewritten to make the grid more object oriented, in that the CGridCell class now takes care of cell-specific tasks. This makes the code more robust, but more importantly it allows the simple insertion of other types of cells. Most of the bugs in the previous version have been fixed, especially the "ExpandToFit" functions and the cell selection/focus. I expect I've introduced a bunch more
2.01 23 Feb 2000	Fixes by Eric Woodruff, <Eric_Woodruff@compuserve.com> Minor MemDC fix, In-place edit WM_KILLFOCUS, "PrintCell" added to CGridCell, plus changes to CGridCell::Draw. Added GetCellTextExtent, SetItemTextFmt to CGridCtrl + better print support. OnRButtonUp handler. various Clipboard and key handling fixes. Search for EFW.
2.0229 Feb 2000	Brian V. Shifrin, Scot Reed Fixes to reduce flicker, fix font selection bug, Fixed SetFixed[Row/Col]Count bug
2.10 11 Mar 2000	Ken Bertelson, Aqiruse and Chris Maunder Titletips now use cell color More attribute accessor functions, plus previously private functions now public Additions for virtual CGridCell support of embedded tree & cell buttons implementation Optional WYSIWYG printing Awareness of hidden (0 width/height) rows and columns for key movements, cut, copy, paste, and autosizing CGridCell can make title tips display any text rather than cell text only Minor vis bug fixes CGridCtrl now works with CGridCellBase instead of CGridCell. This is a taste of things to come.
2.11 19 May 2000	Chris Maunder + Co Increasing fixed cells clashed with selected cells (Ivan Ilinov) AutoSizeRows obvous bug fixed OnLButtonDown fix (Ken Bertelson)  ExpandToFit bug fixed (scrollbar space) (Igor Proskuriakov) List mode selection/deselection fixed Keyboard cell movement improved. You can now see the cells! m_nBarState MS madness fixed (Phil K)
2.12 26 May 2000	Martin Richter's fixes: If using TRY/CATCH (winCE) instead of try/catch (win32), e->Delete is not called EnsureVisible "fix" was fixed properly.
2.13 28 May 2000	Chris Maunder, Martin Richter, Ken Bertelson AutoSizeColumn works on either column header, data or both EnsureVisible. The saga continues. Rewrote exception handling Added the Get/EnableColumnHide and Get/EnableRowHide functions
2.20 29 July 2000	Font storage optimised (suggested by Martin Richter) AutoSizeColumn works on either column header, data or both EnsureVisible. The saga continues... (Ken) Rewrote exception handling Added TrackFocusCell and FrameFocusCell properties, as well as ExpandLastColumn (suggested by Bruce E. Stemplewski). InsertColumn now allows you to insert columns at the end of the column range (David Weibel) Shift-cell-selection more intuitive API change: Set/GetGridColor now Set/GetGridLineColor API change: Set/GetBkColor now Set/GetGridBkColor API change: Set/GetTextColor, Set/GetTextBkColor depricated  API change: Set/GetFixedTextColor, Set/GetFixedBkColor depricated  Stupid DDX_GridControl workaround removed. Added "virtual mode" via Set/GetVirtualMode Added SetCallbackFunc to allow callback functions in virtual mode Added Set/GetAutoSizeStyle AutoSize() bug fixed added GVIS_FIXEDROW, GVIS_FIXEDCOL states added Get/SetFixed[Row|Column]Selection cell "Get" methods now const'd. Sorry folks... GetMouseScrollLines now uses win98/W2K friendly code WS_EX_CLIENTEDGE style now implicit
2.21 30 Aug 2000	re-jigged OLE initialisation and drag/drop registration Cut and Paste bug fixed (empty cells not being treated correctly) Added "bExpandFixed" parameter to Expand*ToFit functions (Hans-Peter Werner) SetRedraw bug fixed Resizing 0-width last row and column now works Fixed CreateCell SetFormat bug (Loic Baudry) Fixed GetFixedTextColor typo (raybie@Exabyte.COM) Modified EnableScrollBars calls in Expand*ToFit functions (Simon Hughes) GetCellFromPt now public GV_CACHEHINT sent more appropriately, and also sent with -1 cellrange at the end of operations (so App can discard data - Martin Richter) CGridCellBase::operator= checks for NULL font before setting (Martin Richter) After drag/drop, mouse button was still marked as "down". Fixed.
2.22 1 Jan 2001	SetModified bug in SetItem (Keith Worden) ifdef around SetItemTextFmt corrected for win32 Save() bug fixed (row 0 saved twice) GetTopleftNonFixedCell, GetUnobstructedNonFixedCellRange and GetVisibleNonFixedCellRange have optional parameter to force recalc. added virtual ValidateEdit. if the return value from the SendMessage operation for GVN_ENDLABELEDIT or GVN_BEGINLABELEDIT is < 0 then the edit, or the attempt to edit (respectively) is rejected. Added GetEditWnd to CGridCellBase Fixed the paste bug for cells being edited (Gary Lyben). GVN_SELCHANGING/GVN_SELCHANGED messages now sent correctly OnRButtonUp was not handling clicks on fixed cells correctly SB_ENDSCROLL message now sent on keypress initiated scroll GetCellTextExtent bug fixed (Elco) SetSelectedRange inefficiency fixed by huangchaoyi (ahaa007@263.net) DT_NOCLIP removed from CGridCellBase::Paint SetRowCount returns correct value on OOM condition (asigal@hotmail.com) Bug when editing using Japanese characters fixed (Michael Dunn) Fixed columns and rows printed correctly (fletch - untested) Added the "ClearCells" function Added the "SetCompareFunction" function and revamped sorting Added "GetEditWnd()" to CGridCellBase Added "GetTipText" to CGridCellBase
2.23 22 July 2001	Save/Load now take optional second parameter to set separator character When in list mode, fixed columns are no longer editable Combobox grid cells now auto-resize correctly Cells are printed using printer font, not screen font (Laura Michaels) ExpandLastColumn fixed (Jim Arnold) When entering DBCS chars into cells the first char was being lost (KiteFly) EnsureVisible no longer steals the focus (Damir) Ctrl+mouse-click no longer puts a cell into edit mode (useful for unselecting) (Richard Bouwman) SetModified/GetModified wasn't handling the first row or column (Ivan Melnychuk) GetCellFromPt Fixed cell check bug fixed (Jim Arnold) Plus a few nips and tucks (Simon Hughes and others) SetItem bug when setting select state fixed (Mik) ComboCell draw error (Joanna Sadler) NULL pointer reference bug fixed in GetTextRect (Jim Arnold) Drag/Drop handler functions now virtual Print() now accepts a pointer to a CPrintDialog object, so you can use your own print dialog when printing (Andrew Truckle) Cell drawing now uses CGridCellBase::GetTextExtent, which simplifies drawing logic for derived classes that embed controls. See the Checkbox cell for more info ValidateAndModifyCellContents no longer modifies read-only cells Drag and drop can now start from read-only cells (Jim Arnold) ResetScrollBars fixed (not fully checked though) - Paul Runstedler EraseBkgnd vis problem fixed (Sean McKinnon) ExpandLastColumn, ExpandRowsToFit and ExpandColumnsToFit now respect hidden rows/columns. Thanks to Podsypalnikov Eugen for the DateTimeCtrl cell type.
2.24 4 July 2002	Corrected compile errors in Visual C++ .NET Added CGridCellNumeric cell type - Andrew Truckle Selecting cells using the keyboard sends GVN_SELCHANG* messages to the parent - Arthur Westerman/Scot Brennecke When printing, the cells now use the grid's default cell colour unless otherwise specified Tabbing over hidden rows now works correctly EnsureVisible bug where NULL pFocusWnd was being used fixed - Patrick DellEra Client border now shows at startup even if size if cells is smaller than size of grid client area CGridCellBase members pure virtual - Scot Brennecke Minor code cleanups and clarifications Minor speed improvements (eg Optimised OnDraw for invisible cells) Pasted cells now set as selected Clicking on a fixed row no longer sets a focus cell (David Pritchard) DEL key now clears all selected cells
2.25 13 Mar 2004	Minor changes so it will compile in VS.NET 2003 and Whidbey Fixed minor bug in EnsureVisible - Junlin Xu Changed AfxGetInstanceHandle for AfxGetResourceHandle in RegisterWindowClass Various changes thanks to Yogurt
2.26 15 Dec 2005	All changes by Pierre Couderc Added sort in Virtual mode Change row/column order programatically or via drag and drop Added save/restore layer (for undoing row/column order changes)
2.27 6 May 2010	Minor changes to allow this to work correctly in VS 2008 and VS 2010.

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)