How to Use LVIF_DI_SETITEM on an LVN_GETDISPINFO Notification

• Microsoft Win32 Application Programming Interface (API) included with:

      - Microsoft Windows NT version 3.51
      - Microsoft Windows 95 version 4.0
      - Microsoft Win32s version 1.3
  

SUMMARY

Windows 95 provides two flags, LVIF_DI_SETITEM and TVIF_DI_SETITEM, for the listview and treeview controls respectively. When set, these flags instruct Windows to start storing information for that particular item previously set as a callback item.

MORE INFORMATION

Windows 95 introduces the concept of callback items for the new listview and treeview common controls. A callback item is a listview or treeview item for which the application, not the control, stores the text, icon, or any appropriate information about the item. If the application already maintains this information anyway, setting up callback items could decrease the memory requirements of the control. Callback items are just as useful for items that display constantly changing information. Setting these items up as callback items allows the application to display the most current values appropriate for that item.

Take for example a SPY application that displays information in a hierarchical form (or a treeview) about the window being browsed or spied on. One of the things it displays is the window rectangle, or the dimensions of the window.

Because the user could resize this window at any time, this particular item is a good candidate for a callback item because it displays constantly changing information.

The application defines a callback item by specifying LPSTR_TEXTCALLBACK for the pszText member of the TV_ITEM structure. Whenever the item needs to be displayed, Windows requests the callback information by sending the treeview's parent a TVN_GETDISPINFO notification in the form of a WM_NOTIFY message. The parent window then fills the pszText member of the TV_ITEM structure as the following sample code demonstrates:

   LRESULT MsgNotify(HWND   hwnd,
                     UINT   uMessage,
                     WPARAM wparam,
                     LPARAM lparam)
   {
       TV_DISPINFO *ptvdi = (TV_DISPINFO *)lparam;

       switch (ptvdi->hdr.code)
       {
          case TVN_GETDISPINFO:

            if (ptvdi.mask & TVIF_TEXT)
            {
               RECT  rect;
               char  szBuf [30];

               GetWindowRect (hWndToBrowse, &rect);

               // where FormatRectText formats the rect information
               // in a nice <WindowRect: (x,y):cx,cy> format
               // and stores it in szBuf.
               FormatRectText (&rect, szBuf, sizeof (szBuf));

               lstrcpy (ptvdi.pszText, szBuf);
            }
            :

           default: break;

        }
   return 0;
   }

   case TVN_GETDISPINFO:

      if (ptvdi.mask & TVIF_TEXT)
      {
         RECT  rect;
         char  szBuf [30];

         GetWindowRect (hWndToBrowse, &rect);

        // where FormatRectText formats the rect information
        // in a nice <WindowRect: (x,y):cx,cy> format
        // and stores it in szBuf.
         FormatRectText (&rect, szBuf, sizeof (szBuf));

         lstrcpy (ptvdi.pszText, szBuf);
         plvdi->item.mask = plvdi->item.mask | TVIF_DI_SETITEM;
      }

The same holds true for listview controls when the mask is ORed with the LVIF_DI_SETITEM flag. However, note that setting the LVIF_DI_SETITEM flag for listviews works only for the first column of text (iSubItem ==0).

If an application specifies LPSTR_TEXTCALLBACK therefore for a column other than 0 in report view, LVIF_DI_SETITEM does not store the text information for that listview item column.

For more information on other members of the LV_ITEM and TV_ITEM structures that can be set up for callback, refer to the documentation on LV_DISPINFO and TV_DISPINFO structures.