listview.h

mini gui 1.6.8 lib and source

/**
 * \file listview.h
 * \author Wei Yongming <[e-mail]>
 * \date 2002/01/06
 * 
 * The header file of MiniGUI extension library.
 *
 \verbatim
    Copyright (C) 2002-2005 Feynman Software
    Copyright (C) 1998-2002 Wei Yongming

    This file is part of MiniGUI, a compact cross-platform Graphics 
    User Interface (GUI) support system for real-time embedded systems.

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

    If you are using MiniGUI for developing commercial, proprietary, or other
    software not covered by the GPL terms, you must have a commercial license
    for MiniGUI. Please see http://www.minigui.com/product/index.html for 
    how to obtain this. If you are interested in the commercial MiniGUI 
    licensing, please write to [e-mail]. 

 \endverbatim
 */

/*
 * $Id: listview.h,v 1.6 2005/09/04 06:58:21 jpzhang Exp $
 *
 *             MiniGUI for Linux/uClinux, eCos, uC/OS-II, VxWorks, 
 *                     and ThreadX version 1.6.x
 *             Copyright (C) 2002-2005 Feynman Software.
 *             Copyright (C) 1998-2002 Wei Yongming.
 */

#ifndef EXT_LISTVIEW_H
#define EXT_LISTVIEW_H

#ifdef  __cplusplus
extern "C" {
#endif

    /**
     * \addtogroup mgext_fns
     * @{
     */

    /**
     * \addtogroup mgext_controls
     * @{
     */

    /**
     * \defgroup mgext_ctrl_listview ListView control
     * @{
     */

#define CTRL_LISTVIEW       ("ListView")

/** Listview return value */
#define LV_OKAY                 0
#define LV_ERR                  (-1)
#define LV_ERRSPACE             (-2)


typedef GHANDLE HLVITEM;

/** list view item flags */
#define LVIF_FOLD               0x0001L

/** 
 * Structure of the listview item info, contains information about an item.
 * This structure is used for creating or retrieving an item. 
 */
typedef struct _LVITEM
{
    /**
     * the rows of the item
     */
    int nItem;
    /** height of the item */
    int nItemHeight;
    /** attached additional data of this item */
    DWORD itemData;

    /**
     * State flags of the item, can be OR'ed by the following values:
     *
     * - LVIF_FOLD\n
     *   The item is folded.
     *
     * When adding an item to the listview control, only LVIF_FOLD
     * flag is valid.
     */
    DWORD dwFlags;

} LVITEM;
typedef LVITEM *PLVITEM;

/** listview icon flags */
#define LVFLAG_BITMAP	0x0001
#define LVFLAG_ICON	    0x0002

/** 
 * Struct of the listview subitem info, contains information about a subitem.
 * This structure is used for creating or retrieving a subitem.
 */ 
typedef struct _LVSUBITEM
{
    /** flags of the subitem, can be OR'ed by the following values:
     *
     * - LVFLAG_BITMAP
     *   The sub item has a bitmap icon.
     * - LVFLAG_ICON
     *   The sub item has an icon.
     */
    DWORD flags;
    /** the Subitem vertical position(rows) */
    int nItem;
    /** the Subitem horizontal position(columns) */
    int subItem;
    /** text content of this subitem */
    char *pszText;
    /** max text len */
    int nTextMax;
    /** text color of the subitem */
    int nTextColor;
    /** image of the subitem, can be bitmap or icon, determined by flags */
    DWORD image; 
} LVSUBITEM;
typedef LVSUBITEM *PLVSUBITEM;

/** Contains information for sorting listview */
typedef struct _LVSORTDATA
{
    /** Sorting column index */
    int ncol;
    /** low sorted or high sorted */
    int losorted;
    /** listview handle */
    HWND hLV;
} LVSORTDATA;
typedef LVSORTDATA *PLVSORTDATA;

/** type of listview comparision fuction */
typedef int (*PFNLVCOMPARE) (HLVITEM nItem1, HLVITEM nItem2, PLVSORTDATA sortData);


/** Column flags */
/** column text left align, default */
#define LVCF_LEFTALIGN	        0x0000
/** column text right align */
#define LVCF_RIGHTALIGN	        0x0001
/** column text center align */
#define LVCF_CENTERALIGN        0x0002
/** column treeview style */
#define LVCF_TREEVIEW           0x0004

/** header flags */
/** header text left align, default */
#define LVHF_LEFTALIGN		0x0000
/** header text right align */
#define LVHF_RIGHTALIGN		0x0004
/** header text center align */
#define LVHF_CENTERALIGN	0x0008

/** 
 * Struct of the listview column info, contains information about a column.
 * This structure is used for creating or retrieving a column.
 */
typedef struct _LVCOLUMN
{
    /** the horizontal position */
    int nCols;
    /** column's width */
    int width;
    /** the title of this column */
    char *pszHeadText;
    /** max text len */
    int nTextMax;
    /** image of the column header, can be bitmap or icon */
    DWORD image; 
    /** Comparision function associated with the column */
    PFNLVCOMPARE pfnCompare;
    /** Column and header flags */
    DWORD colFlags;
} LVCOLUMN;
typedef LVCOLUMN *PLVCOLUMN;

/** listview search flags */
/** search by text */
#define LVFF_TEXT	    0x0001
/** search by addtional data */
#define LVFF_ADDDATA	0x0002

/** Contains information for finding a certain item info */
typedef struct _LVFINDINFO
{
    /** 
     * Type of search to perform. 
     * This member can be set to one or more of the following values:
     * - LVFF_TEXT
     *   Searches based on the item(subitems) text.
     * - LVFF_ADDDATA
     *   Searches based on the attached additional item data.
     */
    DWORD flags;
    /** Search index to begin with, 0 from the beginning */
    int iStart;
    /** pszInfo containing nCols columns' text */
    int nCols;
    /** all the subitem's content of this item */
    char **pszInfo;
    /** the additional item data */
    DWORD addData;

    /** The found item's row, reserved */
    int nItem;
    /** The found subitem's column, reserved */
    int nSubitem;

} LVFINDINFO;
typedef LVFINDINFO *PLVFINDINFO;

/** Contains listview general notification information */
typedef struct _LVNM_NORMAL
{
    /** wParam parameter of the message */
    WPARAM wParam;
    /** lParam parameter of the message */
    LPARAM lParam;
} LVNM_NORMAL;
typedef LVNM_NORMAL *PLVNM_NORMAL;

/** keydown notification information */
typedef LVNM_NORMAL LVNM_KEYDOWN;
typedef LVNM_KEYDOWN *PLVNM_KEYDOWN;

/** Contains listview notification information when mouse down on the header  */
typedef LVNM_NORMAL LVNM_HEADRDOWN;
typedef LVNM_HEADRDOWN *PLVNM_HEADRDOWN;

/** Contains listview notification information when mouse up on the header  */
typedef LVNM_NORMAL LVNM_HEADRUP;
typedef LVNM_HEADRUP *PLVNM_HEADUP;

/** Contains listview notification information when mouse down on the item area */
typedef LVNM_NORMAL LVNM_ITEMRDOWN;
typedef LVNM_ITEMRDOWN *PLVNM_ITEMRDOWN;

/** Contains listview notification information when mouse up on the item area */
typedef LVNM_NORMAL LVNM_ITEMRUP;
typedef LVNM_ITEMRUP *PLVNM_ITEMRUP;

    /**
     * \defgroup mgext_ctrl_listview_styles Styles of listview control
     * @{
     */

/**
 * \def LVS_UPNOTIFY
 * \brief Notifies the parent window when mouse is up (default is down).
 *
 * Causes the listview to notify the listview parent window 
 * with a notification message when the user make actions, such as clicks, doubleclicks, ...,etc.
 */
#define LVS_UPNOTIFY            0x0001L             /* must be the same with SVS_UPNOTIFY */
#define LVS_NOTIFY              LVS_UPNOTIFY

/**
 * \def LVS_SORT
 * \brief Sorts strings automatically.
 *
 * Causes the listview to sort strings automatically. 
 */
#define LVS_SORT                0x0002L

/**
 * \def LVS_MULTIPLESEL
 * \brief Causes the listview to allow the user to select multiple items.
 */
#define LVS_MULTIPLESEL         0x0008L              /* reserved */

/**
 * \def LVS_CHECKBOX
 * \brief Displays a check box in an item.
 */
#define LVS_CHECKBOX            0x1000L              /* reserved */

/**
 * \def LVS_AUTOCHECK
 * \brief If the list box has LVS_CHECKBOX style, this
 *        style tell the box to auto-switch the check box between 
 *        checked or un-checked when the user click the check mark box of an item.
 */
#define LVS_AUTOCHECK           0x2000L              /* reserved */

#define LVS_AUTOCHECKBOX        (LVS_CHECKBOX | LVS_AUTOCHECK)    /* reserved */

/**
 * \def LVS_TREEVIEW
 * \brief Uses listview in a treeview style.
 */
#define LVS_TREEVIEW            0x4000L

    /** @} end of mgext_ctrl_listview_styles */

    /**
     * \defgroup mgext_ctrl_listview_msgs Messages of ListView control
     * @{
     */

/**
 *  \def LVM_ADDITEM
 *  \brief Adds a item to listview, this item is also called a row. 
 *  
 *  \code 
 *  LVM_ADDITEM
 *  PLVITEM p
 *  HLVITEM parent;
 *
 *  wParam = (WPARAM)parent;
 *  p =(LPARAM)lParam;
 *  \endcode
 *
 *  \param p Pointes to a LVITEM structure that contains the information of 
 *           the new item to be added. nItem member of the LVITEM struct speficied 
 *           the item position in its parent item, beginning with zero.
 *  \param parent handle of the parent item into which the new item is about to insert.
 *           If parent equals zero, the parent item will be the root of listview.
 *
 *  \return Returns the handle of the new item if successful, or 0 otherwise.
 */
#define LVM_ADDITEM            0xF110

/**
 * \def LVM_FILLSUBITEM
 * \brief Sets the content of a subitem, indentified by rows and columns.
 * 
 * \code
 * LVM_FILLSUBITEM
 * PLVSUBITEM p;
 * HLVITEM pi;
 *
 * lParam = (LPARAM)p;
 * wParam = (WPARAM)pi;
 * \endcode
 *
 * \param p  Pointes to a PLVSUBITEM structure that contains the information of 
 *           the subitem to set. If pi is not zero, nItem member of this struct
 *           has no meaning.
 * \param pi handle of the target item.
 *           If pi equals zero, the row position of the target item is 
 *           specified by nItem member of p structure.
 *
 * \return Returns LV_OKAY if successful, or LV_ERR otherwise.
 */
#define LVM_FILLSUBITEM        0xF111

/**
 * \def LVM_ADDCOLUMN
 * \brief Adds a new column to listview, indentified by column.
 * 
 * \code
 *  LVM_ADDCOLUMN
 *  PLVCOLUMN p;
 *
 *  wParam = 0;
 *  lParam =(LPARAM)p;
 * \endcode
 *
 * \param p Pointes to a LVCOLUMN structure that contains the information about the new 
 *          column to be added.
 */
#define LVM_ADDCOLUMN          0xF112

/**
 * \def LVM_DELITEM
 * \brief Deletes an item form listview.
 *
 * \code
 * LVM_DELITEM
 * int nRow;
 * HLVITEM pi;
 *
 * wParam = (WPARAM)nRow;
 * lParam = (LPARAM)pi;
 * \endcode
 *
 * \param nRow If pi is zero, nRow specified the row index of the target item to delete.
 * \param pi handle of the target item.
 *
 * \return Returns LV_OKAY if successful, or LV_ERR otherwise.
 */
#define LVM_DELITEM            0xF113

/**
 * \def LVM_CLEARSUBITEM
 * \brief Clears the content of a subitem.
 * 
 * \code
 * LVM_CLEARSUBITEM
 * PLVSUBITEM p;
 * HLVITEM pi;
 *
 * lParam = (LPARAM)p;
 * wParam = (WPARAM)pi;
 * \endcode
 *
 * \param p  Pointes to a PLVSUBITEM structure that contains the information of 
 *           the subitem to clear. If pi is not zero, nItem member of this struct
 *           has no meaning.
 * \param pi handle of the target item.
 *           If pi equals zero, the row position of the target item is 
 *           specified by nItem member of p structure.
 *
 * \return Returns LV_OKAY if successful, or LV_ERR otherwise.
 */
#define LVM_CLEARSUBITEM       0xF114

/**
 * \def LVM_DELCOLUMN
 * \brief Deletes a column from listview, all subitem in this column will be removed.  
 *
 * \code
 * LVM_DELCOLUMN
 * int nCols;
 *
 * wParam = (WPARAM)nCol;
 * lParam = 0;
 * \endcode
 *
 * \param nCol the index of the column to be removed.
 * \return Returns LV_OKAY if successful, or LV_ERR otherwise.
 */
#define LVM_DELCOLUMN          0xF115

/**
 * \def LVM_COLSORT
 * \brief Sorts all subitems according to a certain column. 
 *
 * \code
 * LVM_COLSORT
 * int ncol;
 *
 * wParam = (WPARAM)ncol;
 * lParam = 0;
 * \endcode
 *
 * \param ncol Index of the column.
 * \return Returns LV_OKAY if successful, or LV_ERR otherwise.
 */
#define LVM_COLSORT            0xF116

/**
 * \def LVM_SETSUBITEMCOLOR
 * \brief Sets the text color of a subitem.
 *
 * \code
 * LVM_SETSUBITEMCOLOR
 * PLVSUBITEM p;
 * HLVITEM pi;
 *
 * lParam = (LPARAM)p;
 * wParam = (WPARAM)pi;
 * \endcode
 *
 * \param p  Pointes to a PLVSUBITEM structure that contains the information of 
 *           the subitem to set. If pi is not zero, nItem member of this struct
 *           has no meaning.
 * \param pi handle of the target item.
 *           If pi equals zero, the row position of the target item is 
 *           specified by nItem member of p structure.
 *
 * \return Always returns 0;
 */
#define LVM_SETSUBITEMCOLOR       0xF117

/**
 * \def LVM_FINDITEM
 *
 * \code
 * LVM_FINDITEM
 * PLVFINDINFO plvfi;
 * HLVITEM parent;
 *
 * wParam = (WPARAM)parent;
 * lParam = (LPARAM)plvfi;
 * \endcode
 *
 * \param parent Handle of the item to search in.
 * \param plvfi Points to a LVFINDINFO structure containing information for searching.
 *              If parent is zero, iStart member of plvfi specifieds the start position
 *              on search.
 *
 * \return Returns the handle of the found item if successful, or 0 otherwise.
 */
#define LVM_FINDITEM           0xF118

/**
 *
 * \def LVM_GETSUBITEMTEXT
 * \brief Retrieves the text of a listview subitem.
 *
 * \code 
 * LVM_GETSUBITEMTEXT
 * PLVSUBITEM p;
 * HLVITEM pi;
 *
 * lParam = (LPARAM)p;
 * wParam = (WPARAM)pi;
 * \endcode
 *
 * \param p  Pointes to a PLVSUBITEM structure that contains the information of 
 *           the subitem to set. If pi is not zero, nItem member of this struct
 *           has no meaning.
 * \param pi handle of the target item.
 *           If pi equals zero, the row position of the target item is 
 *           specified by nItem member of p structure.
 *
 * \return Returns len of the text if successful, -1 otherwise.
 */

#define LVM_GETSUBITEMTEXT         0xF119

/**
 * \def LVM_GETITEMCOUNT
 * \brief Gets the number of all the items(rows) in a listview.
 *
 * \code
 * LVM_GETITEMCOUNT
 *
 * wParam = 0;
 * lParam = 0;
 * \endcode
 *
 * \return The number of the items.
 */
#define LVM_GETITEMCOUNT       0xF11A

/**
 * \def LVM_GETCOLUMNCOUNT
 * \brief Gets the number of all the columns in listview.
 *
 * \code
 * LVM_GETCOLUMNCOUNT
 *
 * wParam = 0;
 * lParam = 0;
 * \endcode
 *
 * \return the number of all the columns in listview.
 */
#define LVM_GETCOLUMNCOUNT     0xF11B

/**
 * \def LVM_GETSELECTEDITEM
 * \brief Gets the current selected item.
 *
 * \code
 * LVM_GETSELECTEDITEM
 *
 * wParam = 0;
 * lParam = 0;
 * \endcode
 *
 * \return handle of the current selected item.
 */
#define LVM_GETSELECTEDITEM    0xF11C

/**
 * \def LVM_DELALLITEM
 * \brief Removes all the items in listview.
 *
 * \code
 * LVM_DEALLITEM
 *
 * wParam = 0;
 * lParam = 0;
 * \endcode
 *
 * \return Returns TRUE if successful, or FALSE otherwise.
 */
#define LVM_DELALLITEM           0xF11D

/**
 * \def LVM_MODIFYHEAD
 * \brief Changes the title of a column.
 *
 * \code
 * LVM_MODIFYHEAD
 * PLVCOLUMN pcol;
 *