This may be a Grid Control but, call me Array

• Download demo project - 63 Kb
• Download source - 16 Kb

Introduction

Frequently, different kind of information must be presented to the user in two dimensional form. Often, to do this, we can use ListView or TreeView controls, but sometimes this is not appropriate, or it is hard to code or cannot be used in their native form. Besides, we wish keep difference between elements and display them in appropriate form (e.g., one element show a color table, another show a text or image, and so on). Therefore, We need to have a flexible mode to operate. Control presented here implements a such array of items (like array or matrix in mathematics) which are freely drawn by user. An array is, for example, an image or a color table or whatever information that can be presented in two dimensions (third dimension can be implemented using TabControl as show in demo program). Control assist user in the items arrangement, in the resize of control, in the scroll and in the notify of events inherent the control itself. All items of the array have same size (i.e. width and height), that the control will use to arranging them into rectangle of its client area. Dimensions (i.e. columns and rows) and item size can be changed by the user in any instant, columns or rows can be fixed or dynamic (control will compute them at any change). Since each item will be drawn by user, any kind of things can be drawn on it. To do this, control pass to the user a Device Context (DC) specific for the item that is drawing. User paint the given DC and the control will render it to its window at the appropriated position (based on current scroll position and items arrangement).

Control creation

Array control is implemented by class CArrayCtrl which was inherit from CWnd class. Constructor method initialize members variables and destroyer method is not used. The control's window class has name "ArrayControlClass" and will be register at the first call of create method. Control is created using method Create which synopsis is:

BOOL CArrayCtrl::Create(DWORD dwStyle, const CRect& rect,
 CWnd* pParent, UINT nID, const CSize& itemsize);

where

 dwStyle  specifies the control style attributes
   WS_CHILD        
//create a child window (this style will be enforced by control)
//(control enforce WS_HSCROLL and WS_VSCROLL too)
   WS_VISIBLE      //window is visible
   WS_BORDER       //window has a border
   ACS_TOOLTIP     //control support item's tooltip
   ACS_TTBALLOON   
//tooltip style is ballon form (default is the standard rectangular form)
   ACS_BALLOONTIP  
//combines two previously defined styles (ACS_TOOLTIP | ACS_TTBALLOON)
   ACS_GRIDLINES   //gridlines are required
   ACS_CLIENTEDGE  
//specifies thar window has 3D look, that is, a border with sunken edge 
//(this style is a redefinition of corresponding Windows style)
   ACS_USERDATA    //user will store data (an LPARAM type) on each item
                   //(by default, control don't store any information) 

 rect     //the size and position of the window, 
          //in client coordinate of pParent
 pParent  //the parent window
 nID      //the id of the child window
 itemsize //the size of the item (cx is the width and cy is the height)

The following code show how to create such control

CArrayCtrl* pArrayCtrl; // CArrayCtrl object pointer declaration
CSize ItemSize(32,64);
CRect rControl(8,8,200,100);

pArrayCtrl = new CArrayCtrl;
pArrayCtrl->Create(WS_CHILD | WS_VISIBLE | WS_BORDER
     | ACS_BALLOONTIP | ACS_GRIDLINES,
     rControl, pParentWnd, ID_ARRAY, ItemSize);

After this, window is displayed on screen but none item is visible. You have two mode to specify the items to the control. You can use method SetItemsCount(int nItems) that force the control to start item-paint process, or method AddItem(int nItem, LPARAM dwData) that insert a new item into the control based to nItem value. It can be an item index (such as 5) and the control will insert new item after that, or the special item ACAI_TOP and ACAI_BOTTOM (default), meaning of which is obvious. Since AddItem method will redraw control's window each time item is added, we must suspend redrawing process until all items are been added. To do this you will use the SetRedraw(BOOL bDraw) method to stop the drawing process (bDraw=FALSE) and then restart it (bDraw=TRUE). This code snippet show it:

pArrayCtrl->SetRedraw(FALSE);
while( ... )
{
    ... prepare data item ...
    pArrayCtrl->AddItem(dwData);
}
pArrayCtrl->SetRedraw(TRUE);

If you previously know the items count, you can use SetItemsCount method in this way:

... control is already been created ...
pArrayCtrl->SetRedraw(FALSE);
pArrayCtrl->SetItemsCount(100);
for(i=0; i<100; i++)
{
    ... prepare data item ...
    pArrayCtrl->SetItemData(i, dwData);
}
pArrayCtrl->SetRedraw(TRUE);

Naturally, if you don't need to have userdata associated to the items, you can call above methods without call SetRedraw.

Methods

There are several methods grouped by category and it will be listed with a brief description. For more specific information on code utilization you should look source code implementation and demo.

General

  UINT   GetCtrlId   ();     //return the child window id
  void   SetCtrlData (LPARAM dwData);     
         // set a global user data to the control
  LPARAM GetCtrlData ();     
        //return the global user data associated to the control
  void   SetToolTip  (DWORD ttstyle);      
       //enable items tooltip (ttstyle is a TOOLTIP style)
  void   SetCursor   (HCURSOR hCursor);    
        //set the window cursor with a specific one 
  void   SetRedraw   (BOOL bResize);       
        //disable or enable items drawing process
  void   Activate    (BOOL bFlag);   
       //hide (bFlag=FALSE) or show (bFlag=TRUE) the control's window

Items

  void   SetItemCount   (int nItems);      
  //set the number of items in a control
  int    GetItemCount   ();                
  //retrieve the current items count
  DWORD  GetItemState   (int nItem);       
    //retrieve the item state
               //ACIS_NORMAL   none of the follow (item is normal)
               //ACIS_SELECTED item is been selected
               //ACIS_VISIBLE  item is visible 
                   //(totally or partially) in the current view 
               //ACIS_HIDDEN   item is hidden (out of current view)
  int    GetRowIndex    (int nItem);       
    //return the item row index (in the current arrangement)
  int    GetRowIndex    ();                
    //same as above but for selected item
  int    GetColumnIndex (int nItem);       
    //return the item column index (in the current arrangement) 
  int    GetColumnIndex ();                
    //same as above but for selected item
  void   AddItem        (int nItem, LPARAM dwData); 
    //insert an item into control
  void   AddItem        (LPARAM dwData)    
    //add an item to the bottom
  void   DrawItem       (int nItem);       
    //force an item redraw
  void   RemoveItem     (int nItem);      
     //delete an item from the control (items will be rearranged)
  void   RemoveAllItems ();               
    //delete all items from the control
  LPARAM SetItemData    (int nItem, LPARAM dwData);
     // associate user data to an item
  LPARAM GetItemData    (int nItem);       
    //retrieve the user data from an item

Sizing and dimensioning

  void SetItemSize   (int width, int height); //set the item size
  void SetItemSize   (CSize* pSize);       //set the item size
  void SetDimension  (int nCount, int obj);   
     // set a dimension to be fixed, obj is the dimension object
     //ACDT_COLUMNS  columns must be fixed to given number
     //ACDT_ROWS     rows must be fixed to given number
  void SetDimension  (int nCount);    //set the current dimension to be fixed
  int  GetDimension  (int* dimtype);  //get the dimension count and type
  int  GetWidth      ();     //get the control's window width
  int  GetHeight     ();    // get the control's window height
  void GetItemSize   (CSize* pSize);       //get the item size
  int  GetItemWidth  ();     //get the item width
  int  GetItemHeight ();     //get the item height
  void SetColumns    (int nCol);           
   //set the columns to be fixed to given number
  void SetRows       (int nRow);           
   //set the rows to be fixed to given number
  int  GetColumns    ();     //get the number of columns
  int  GetRows       ();     //get the number of rows 

Colouring

  void     SetBkColor   (COLORREF crBack);    
   //set the background color of the control (and the item)
  void     SetGridColor (COLORREF crGrid);    //set the gridlines color
  void     SetColors    (COLORREF crBack, COLORREF crGrid); 
     //set the color of background and the gridlines (together)
  COLORREF GetBkColor   ();    // get the background color
  COLORREF GetGridColor ();     //get the gridlines color
  void     SetTipColor  (COLORREF crBkg, COLORREF crTxt); 
     //set the tooltip background and foreground colors

Selection and Scrolling

  void SelectItem      (int nItem);             
    //set the item state to selected
  void ActivateItem    (int nItem);             
    //activate an item (send LBUTTONDBLCLK message to control)
  void ActivateItem    ();        //same as above but for selected item
  int  GetSelectedItem ();        //get the item that was been selected 
  int  GetHitItem      ();        //get the item under the mouse pointer
  void SetScrollSize   (int nSBVers, int nSBObj, int nSize); 
    //set the scrolling amount value
                       //nSBVers  SB_VERT
                  //SB_HORZ
                       //nSBObj   ACSO_LINE
                  //ACSO_PAGE 

  int  GetScrollSize   (int nSBVers, int nSBObj); 
    //get the amount of the scroll component
  void Scroll          (int nSBVers, UINT nSBCode); 
    //send a scroll event to control (amount is default)
                       //nSBCode  SB_TOP
//               SB_BOTTOM
//               SB_LEFT
//               SB_RIGHT
//               SB_PAGEUP 
//               SB_PAGEDOWN 
//               SB_LINEUP 
//               SB_LINEDOWN 
  void Scroll          (int nSBVers, UINT nSBCode, UINT nPos); 
    //send a scroll event to control with amount specified
  void VertScroll      (UINT nSBCode);          
    //send a vertical scroll event to control (amount is default)
  void VertScroll      (UINT nSBCode, UINT nPos); 
    //send a vertical scroll event to control with amount specified
  void HorzScroll      (UINT nSBCode);          
    //send an horizontal scroll event to control (amount is default)
  void HorzScroll      (UINT nSBCode, UINT nPos); 
    //send an horizontal scroll event to control with amount specified
  void EnsureVisible   (int nItem);             
    //ensure that item is visible and scroll control to make this
  BOOL IsVisible       (int nItem);             
    //verify if item is on current view

Grid Lines

  void SetGridLines     (BOOL bActive);       
    //activate or deactivate gridlines
  BOOL GetGridLines     ();     
    //get gridlines activation status
  void SetGridThickness (int nThickness);     
    //set the thickness of the gridlines
  int  GetGridThickness ();     
    //get the thickness of the gridlines

Notification process

Control send to parent window some notification messages using the WM_NOTIFY form. It is sent by control to its parent window when an event has occurred or the control requires some information. Events which notification is required are listed below:

• mouse action over control
• item draw
• item deletion
• tooltip event

You can mapping the message by

      ON_NOTIFY(wNotifyCode, CtrlId, memberFunction)
or
      ON_NOTIFY_RANGE(wNotifyCode, CtrlIdFirst, CtrlIdLast, memberFunction)

Your member functions must be declared with the following prototypes:

   afx_msg void memberFunction(NMHDR* pNotifyStruct, 
     LRESULT* result);
or
   afx_msg void memberFunction(UINT CtrlId, NMHDR* pNotifyStruct, 
     LRESULT* result);

where the parameters are:

CtrlId        the child identifier of the control that sent the notification.
pNotifyStruct a pointer to the notification structure, as described above.
result        a pointer to the result code you’ll set before you return.

WM_NOTIFY messages contain the ID of the control sending the message in wParam and a pointer to an NMHDR structure in lParam. This structure is followed by a related event structure that has an NMHDR structure as its first member. Note that since the NMHDR member is first, a pointer to this structure can be used as either a pointer to an NMHDR or as a pointer to the structure depending on what type of event is, and you must cast it to proper structure.

For mouse activation events control send an ACITEMACTIVATE which have this declaration:

typedef struct tagACITEMACTIVATE
{
  NMHDR       hdr;        // standard header
  CArrayCtrl* pControl;   // control object pointer
  int         nItem;      // item activate
  DWORD       dwState;    // item state
  int         nRow;       // row (relative to current arrangement)
  int         nColumn;    // column (relative to current arrangement)
  CPoint      ptAction;   // mouse pointer location at event
  UINT        nKeyFlags;  // modifier key that were pressed
  LPARAM      dwParam;    // user data
}
  ACITEMACTIVATE, *LPACITEMACTIVATE;

The field code of the NMHDR structure will report the event id:

ACN_CLICK        // User clicked left mouse button in the control
ACN_RCLICK       // User clicked right mouse button in the control
ACN_DBCLICK      // User double-clicked left mouse button in the control

For item draw and deletion events control send an ACITEMINFO which have this declaration:

typedef struct tagACITEMINFO
{
  NMHDR       hdr;       // standard header
  CArrayCtrl* pControl;  // control pointer
  int         nItem;     // item to be draw
  DWORD       dwState;   // item state
  int         nRow;      // row (relative to current arrangement)
  int         nColumn;   // column (relative to current arrangement)
  CDC*        pDC;       // DC to be draw the item
  int         nWidth;    // width of the given DC
  int         nHeight;   // height of the given DC
  LPARAM      dwParam;   // user data
}
  ACITEMINFO, *LPACITEMINFO;

The field code of the NMHDR structure will report the event id:

ACN_DRAWITEM     //  Item must be drawn
ACN_DELETEITEM  //   Item is been deleted

On item deletion only pControl, nItem and dwParam fields are filled with meaningful information. For tooltip events control send an ACTOOLTIPINFO which have this declaration:

typedef struct tagACTOOLTIPINFO
{
  NMHDR       hdr;          // standard header
  CArrayCtrl* pControl;     // control pointer
  int         nItem;        // item for which tooltip text is required
  DWORD       dwState;      // item state
  int         nRow;         // row (relative to current arrangement)
  int         nColumn;      // column (relative to current arrangement)
  LPTSTR      lpszTipText;
        // address of need text buffer (max size is MAX_PATH)
  LPARAM      dwParam;      // user data
}
  ACTOOLTIPINFO, *LPACTOOLTIPINFO;

For the time being, the field code of the NMHDR structure will only report the event id:

ACN_NEEDTIPTEXT    Tooltip require a text

The demo program

Demo program creates four controls to show any kind of operation performed with Array control. zbr> First and second control are CArrayCtrl which show images, icons and text loaded by selecting a folder. Images will be shown as thumbnail, while icons and text will be shown as they are. A CxImage class, by Davide Pizzolato (see his article), is used to load images. I have used the related LIB built on my computer and I have included the original header file. The right button of the mouse show two menus: one if pointer is over an item and another if pointer is over a control but not over an item (know as item-menu and control-menu) that enable user to choose various operation.

Third control show an image selected from above controls and splashed on it. Selected icon will be shown using IconEdit program (.ico file extension must be associated to this via desktop) and text using Notepad. Other stuff can be chosen. There isn't menu associated to this control. Fourth control is a TabCtrl used for contrasting color test. It has ten items that specify the color Brightness value, and each item has an array control which items specify the Saturation and Hue values. This is a 3-dimensional control. By select an item, a new window will be displayed. In this window you can see two rectangle coloured with contrasting color of the background color: left rectangle is computed by alucardx algorithm (see article on general section) and right rectangle is computed by my own. At the side of each there are related color information. Two small icons rating the goodness of algorithms.

Enhancements and improvements

This is a list of open issues about CArrayCtrl control:

• Make internal use of TabControl to implement 3-D array (this isn't a real limitation)
• Use Vector template to manage user data
• Sending WM_NOTIFY for mouse movements
• Make item management more complex (with more to use defaults)
• Implement items hot-tracking
• Make each item a mini-window with a own life
• Link each item to a thread to perform asynchronous operation

History

• This is the version 1 modification 0. I don't believe that all bugs were discovered.