The Ultimate Grid Beginner's Guide

• Download the Ultimate Grid source code - 380 KB
• Download the Ultimate Grid sample projects - 2.2 MB
• Download the Ultimate Grid documentation in compiled HTML help (CHM) format - 1 MB

Visit the Ultimate Grid main page for an overview and configuration guide to the Ultimate Grid library.

Contents

• Introduction
• Using the Grid in a CView
• Using the Grid in a CDialog
• Using the Grid in a DLL or Static Library
• History
• Comments

Introduction

This is a brief introduction to getting started with the Ultimate Grid. You should find it pretty straightforward to get going with the grid in your MFC-based application after reading these short tutorials on using the grid in view and dialog based applications. You can also download the CHM documentation, which contains a Getting Started section as well as a more detailed tutorial on displaying your first grid in an MFC application.

You can build the core Ultimate Grid source into a static library or DLL with the projects provided and link to it in that format, but we'll start here with examples of using the grid source code directly in your project.

Using the Grid in a CView

To begin, create a new SDI or MDI based MFC application project. Add the CPP files contained in the Ultimate Grid source directory, and the .h files contained in the include directory. You will probably need to set up an Additional Include path to the Ultimate Grid\Include directory in your projects preprocessor settings. As noted on the main page, the source code and sample projects zip files should integrate to form the following directory structure:

That done, your project should build cleanly - compiling the basic grid source code.

Next, we'll need to integrate a grid (CUGCtrl) derived class into the project. We've provided a MyCug 'skeleton' class in the Skel directory. This CUGCtrl derived class has all the grid override and setup function overrides you'll need to work with, allowing you to customize the behaviour of you grid with a minimum of additional coding.

Copy the MyCug.h and MyCug.cpp files to your project directory, and add the files to your project.

Next, you'll need to include the MyCug.h file in the app and view classes - like so:

// YourApp.cpp : Defines the class behaviours for the application.



#include "stdafx.h"


#include "mycug.h" // add the header to the YourApp and YourView cpp files  


#include "test.h"


#include "MainFrm.h"

Next, in the header for the view class, declare an instance of the MyCug grid class:

class CMyView : public CView{
     ...
     //******** Create a New Grid Object ********


     MyCug m_grid;
     ...

Next, in the OnCreate method of the view, we can create our grid:

int CMyView::OnCreate(LPCREATESTRUCT lpCreateStruct) {
     if (CView::OnCreate(lpCreateStruct) == -1)
          return -1;

     // TODO: Add your specialized creation code here


     m_grid.CreateGrid( WS_CHILD|WS_VISIBLE, CRect(0,0,0,0), this, 
         1234 );    // arbitrary ID of 1234 - season to taste



     return 0;
}

And the last bit will tie the grid to the client area of the view - add an OnSize handler, and the following code:

void CMyView::OnSize(UINT nType, int cx, int cy){

     CView::OnSize(nType, cx, cy);

     // TODO: Add your message handler code here


     m_grid.MoveWindow( 0, 0, cx, cy );       // size the grid control to 


                                              // fit the view


}

At this point, should you compile and run the application, the view should contain something almost, but not quite entirely, unlike a grid. So, let's set up some columns and rows and populate cells with data.

We'll place this code in the OnSetup notification of the derived grid class:

/***************************************************
OnSetup
    This function is called just after the grid window 
    is created or attached to a dialog item.
    It can be used to initially setup the grid
****************************************************/
void MyCug::OnSetup(){
    
     int rows = 20;
     int cols = 20;
     int i,j;
     CString  temp;
     CUGCell  cell;

     // setup rows and colums


     SetNumberRows(rows);
     SetNumberCols(cols);

     // fill cells with data


     GetCell(0,1,&cell);
     for (i = 0; i < cols; i++) {
          for (j = 0; j < rows; j++) {
               temp.Format("%d",(i+1)*(j+1));
               cell.SetText(temp);
               SetCell(i,j,&cell);
         }
     }
     // add column headngs


     for (i = 0; i < cols; i++) {
          temp.Format("%d",(i+1));
          cell.SetText(temp);
          SetCell(i,-1,&cell);
     }
     // add row headings


     for (j = 0; j < rows; j++) {
          temp.Format("%d",(j+1));
          cell.SetText(temp);
          SetCell(-1,j,&cell);
     }
}

Now, on running the program, you should see the grid populated with 20 rows and columns of numeric data:

This is a screenshot of the Ex2 project, found in the Examples\BasicMDI directory of the samples download.

Using the Grid in a CDialog

For a dialog based application, you'll want to attach the grid to a control placed on the dialog with the resource editor. Here we've just expanded the default 'TODO' static text item, and given it an ID of IDC_GRID1:

Leaving out the steps shown above (including the source and MyCug files etc), the difference here is in grid creation. In the OnInitDialog method of our dialog, we'll call the Attach method of the grid instead of the Create method used in the view example:

BOOL CEx3Dlg::OnInitDialog()
{
     CDialog::OnInitDialog();
     ...
     // TODO: Add extra initialization here


    
     // attach the grid to the static control


     m_ctrl.AttachGrid(this, IDC_GRID1);

     return TRUE;  // return TRUE  unless you set the focus to a control


}

From here, initialization can be coded in the MyCug::OnSetup routine as in the above view example. You can refer to the Ex3 project in the Samples\BasicDlg directory of the samples download for details.

There are times when you might want to use a member pointer in order to destroy and recreate the grid on a dialog. The problem here is that once attached to the static control window, that window is destroyed along with the grid on calling delete. So, the control needs to be recreated and assigned a known ID so that a new grid can be reattached.

Here is one solution:

void CSampleGridDlgDlg::OnCreatebtn() 
{
     if(m_pGrid != NULL) {
          delete m_pGrid;
          m_pGrid = NULL;
     }
     HWND hWnd = CreateWindowEx(0,"STATIC","Test",
         WS_CHILD | WS_VISIBLE,0,100,720,400,this->m_hWnd,NULL,NULL,0);
     if(hWnd != NULL) {
          SetWindowLong(hWnd, GWL_ID, 37773);    // arbitrary ID for the 


                                                 // static control


          int id = ::GetDlgCtrlID(hWnd);
          m_pGrid = new MyCug;
          m_pGrid->AttachGrid(this, id);
     }
}

Using the Grid in a DLL or Static Library

Two projects are included that will build the static and dynamic (DLL) libraries and place them in the Lib and Dlls folders of the Ultimate Grid directory. As installed, these projects will reference the core Source and Include files and enable you to link without compiling these in your project, but will not incorporate the add on cell types and data sources, which will still need to be added to your project as needed. (See the comments section of the cell types article for instructions on incorporating the advanced cell types in a library build).

Static Lib Settings

The static library project in the BuildLib directory has 16 configurations (batch mode build is recommended) that accommodate the various combinations of MFC linkage, Ole/non-Ole, Unicode/MBCS, and debug/release configurations. Each build configuration is set to create the *.lib file and place it in the Lib directory.

DLL Settings

The DLL project in the BuildDLL directory contains only four configurations, as it assumes all builds link dynamically to the MFC library and are Ole enabled. On creation, the *.lib, *.exp, and *.dll files will be placed in the DLLs directory.

Project Changes - DLL Usage

You can now remove the Ultimate Grid\Source *.cpp files from your project. You'll still need a path to the Ultimate Grid\Include directory, as the headers will still be referenced through the CUGCtrl derived class MyCug.

We've provided a header file that should be added to your project that will select the correct module to link against based on your projects current build settings - uglibsel.h can be found in the Ultimate Grid\Lib directory. We recommend adding this file to your stdafx.h header. If you use this file directly from the Lib directory, you'll need an additional include path for this as well.

If you want to link to the DLL version of the grid, your preprocessor settings should contain the define _LINK_TO_UG_IN_EXTDLL. This will define the UG_CLASS_DECL declaration as AFX_CLASS_IMPORT for the Ultimate Grid classes.

If using uglibsel.h, you will also need to define a path to the DLLs directory as an additional library directory in the linker settings of your project. Alternatively, you can choose to use the following code in your stdafx.h file, replacing the relative paths with their correct equivalents for your project:

#ifdef _DEBUG
    #ifdef _UNICODE
        #pragma message("Automatically linking with UGMFCDU.lib - " +
            "please make sure this file is built.")
        #pragma comment(lib, "..\\..\\DLLs\\UGMFCDU.lib")
    #else // not unicode    


        #pragma message("Automatically linking with UGMFCD.lib - " +
            " please make sure this file is built.")
        #pragma comment(lib, "..\\..\\DLLs\\UGMFCD.lib")
    #endif // _UNICODE


#else // RELEASE


    #ifdef _UNICODE
        #pragma message("Automatically linking with UGMFCU.lib - " +
            "please make sure this file is built.")
        #pragma comment(lib, "..\\..\\DLLs\\UGMFCU.lib")
    #else // not unicode    


        #pragma message("Automatically linking with UGMFC.lib - " +
            "please make sure this file is built.")
        #pragma comment(lib, "..\\..\\DLLs\\UGMFC.lib")
    #endif // _UNICODE


#endif // _DEBUG

Of course, the actual DLL that will be used will need to be in the system path or available in the project directory at runtime.

Project Changes - Static Library Usage

Again, you can now remove the Ultimate Grid\Source files from your project, keeping the additional include path to the Ultimate Grid\Include directory in your preprocessor settings.

Add an additional library directory path to the linker settings (set this to the Ultimate Grid\Lib directory) and include the uglibsel.h header from that directory or copy the file to your project directory.

Your project should now build and link with the correct static library based on your project settings.

History

Initial CodeProject release August 2007.