listbox.h

有了操作系统、TCP/IP协议栈、文件系统

/**
 * \file listbox.h
 * \author Wei Yongming <[e-mail]>
 * \date 2001/12/29
 * 
 \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: listbox.h,v 1.2 2005/02/15 05:00:08 weiym Exp $
 *
 *             MiniGUI for Linux/uClinux, eCos, uC/OS-II, VxWorks, 
 *                     and ThreadX version 1.6.x
 *             Copyright (C) 2002-2005 Feynman Software.
 *             Copyright (C) 1999-2002 Wei Yongming.
 */

#ifndef _MGUI_CTRL_LISTBOX_H
#define _MGUI_CTRL_LISTBOX_H
 
#ifdef __cplusplus
extern "C" {
#endif  /* __cplusplus */

    /**
     * \addtogroup controls
     * @{
     */

    /**
     * \defgroup ctrl_listbox ListBox control
     * @{
     */

/**
 * \def CTRL_LISTBOX
 * \brief The class name of listbox control.
 */
#define CTRL_LISTBOX        ("listbox")

/* Listbox return value */
#define LB_OKAY                 0
#define LB_ERR                  (-1)
#define LB_ERRSPACE             (-2)

#define CMFLAG_BLANK            0x0000
#define CMFLAG_CHECKED          0x0001
#define CMFLAG_PARTCHECKED      0x0002
#define CMFLAG_MASK             0x000F

#define IMGFLAG_BITMAP          0x0010

/** Structrue of the listbox item info */
typedef struct _LISTBOXITEMINFO
{
    /** Item string */
    char* string;

    /** 
     * Check mark and image flag. It can be one of the following values:
     * - CMFLAG_BLANK
     *   The item is blank.
     * - CMFLAG_CHECKED
     *   The item is checked.
     * - CMFLAG_PARTCHECKED
     *   The item is partly checked.
     *
     * For LBS_ICON list box, if you want to display bitmap other than icon, 
     * you can OR'd \a cmFlag whit \a IMGFLAG_BITMAP.
     */
    DWORD   cmFlag;         /* check mark flag */

    /** Handle to the icon (or pointer to bitmap object) of the item */
    HICON   hIcon;          /* handle to icon */
} LISTBOXITEMINFO;

/** 
 * \var typedef LISTBOXITEMINFO* PLISTBOXITEMINFO;
 * \brief Data type of the pointer to a LISTBOXITEMINFO.
 */
typedef LISTBOXITEMINFO* PLISTBOXITEMINFO;

    /**
     * \defgroup ctrl_listbox_styles Styles of listbox control
     * @{
     */

/**
 * \def LBS_NOTIFY
 * \brief Notifies the parent window.
 *
 * Causes the list box to notify the list box parent window 
 * with a notification message when the user clicks or doubleclicks an item.
 */
#define LBS_NOTIFY              0x0001L

/**
 * \def LBS_SORT
 * \brief Sorts strings alphabetically.
 *
 * Causes the list box to sort strings alphabetically that are 
 * added to the list box with an LB_ADDSTRING message.
 */
#define LBS_SORT                0x0002L

/**
 * \def LBS_MULTIPLESEL
 * \brief Causes the list box to allow the user to select multiple items.
 */
#define LBS_MULTIPLESEL         0x0008L

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

/**
 * \def LBS_USEICON
 * \brief Displays an icon or bitmap in an item.
 */
#define LBS_USEICON             0x2000L

/**
 * \def LBS_AUTOCHECK
 * \brief If the list box has LBS_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 LBS_AUTOCHECK           0x4000L
#define LBS_AUTOCHECKBOX        (LBS_CHECKBOX | LBS_AUTOCHECK)

/**
 * \def LBS_SBALWAYS
 * \brief The list box with LBS_SBALWAYS style will always show vertical scrollbar.
 */
#define LBS_SBALWAYS            0x8000L


#define LBS_OWNERDRAWFIXED      0x0010L
#define LBS_OWNERDRAWVARIABLE   0x0020L
#define LBS_USETABSTOPS         0x0080L
#define LBS_MULTICOLUMN         0x0200L
#define LBS_WANTKEYBOARDINPUT   0x0400L
#define LBS_NOREDRAW            0x0004L
#define LBS_HASSTRINGS          0x0040L
#define LBS_NOINTEGRALHEIGHT    0x0100L
#define LBS_EXTENDEDSEL         0x0800L

    /** @} end of ctrl_listbox_styles */

    /**
     * \defgroup ctrl_listbox_msgs Messages of listbox control
     * @{
     */

/**
 * \def LB_ADDSTRING
 * \brief Appends the specified string.
 *
 * An application sends an LB_ADDSTRING message to append an item
 * specified in the lParam parameter to a list box.
 *
 * For a text-only list box:
 *
 * \code
 * LB_ADDSTRING
 * const char* text;
 *
 * wParam = 0;
 * lParam = (LPARAM)text;
 * \endcode
 *
 * \param text Pointer to the string of the item to be added.
 *
 * For a list box with check box or icon 
 * (with LBS_CHECKBOX or LBS_USEICON styles):
 *
 * \code
 * LB_ADDSTRING
 * PLISTBOXITEMINFO plbii;
 *
 * wParam = 0;
 * lParam = (LPARAM)plbii;
 * \endcode
 *
 * \param plbii Pointer to the listbox item info to be added.
 *
 * \return The index of the new item on success, else the one of
 *         the following error codes:
 *
 *         - LB_ERRSPACE    No memory can be allocated for new item.
 *         - LB_ERR         Invalid passed arguments.
 *
 */
#define LB_ADDSTRING            0xF180

/**
 * \def LB_INSERTSTRING
 * \brief Inserts an item to the list box.
 *
 * An application sends an LB_INSERTSTRING message to insert an item 
 * into a list box. Unlike LB_ADDSTRING message, the LB_INSERTSTRING
 * message do not cause the list to be sorted.
 *
 * For a text-only list box:
 *
 * \code
 * LB_INSERTSTRING
 * const char* text;
 *
 * wParam = index;
 * lParam = (LPARAM)text;
 * \endcode
 *
 * \param index Specifies the index of the position at which to insert the item.
 * \param text Pointer to the string of the item to be inserted.
 *
 * For a list box with check box or icon 
 * (with LBS_CHECKBOX or LBS_USEICON styles):
 *
 * \code
 * LB_INSERTSTRING
 * int index;
 * PLISTBOXITEMINFO plbii;
 *
 * wParam = (WPARAM)index;
 * lParam = (LPARAM)plbii;
 * \endcode
 * 
 * \param index Specifies the index of the position at which to insert the item.
 * \param plbii Pointer to the listbox item info to be inserted.
 *
 * \return The index of the new item on success, else the one of
 *         the following error codes:
 *
 *         - LB_ERRSPACE    No memory can be allocated for new item.
 *         - LB_ERR         Invalid passed arguments.
 *
 */
#define LB_INSERTSTRING         0xF181

/**
 * \def LB_DELETESTRING
 * \brief Removes an item from the list box.
 *
 * An application sends an LB_DELETESTRING message to a list box 
 * to remove from the list box.
 *
 * \code
 * LB_DELETESTRING
 * int delete;
 *
 * wParam = (WPARAM)delete;
 * lParam = 0;
 * \endcode
 *
 * \param delete The index of the listbox item to be deleted.
 *
 * \return LB_OKAY on success, else LB_ERR to indicate you passed an invalid index.
 */
#define LB_DELETESTRING         0xF182

#define LB_SELITEMRANGEEX       0xF183

/**
 * \def LB_RESETCONTENT
 * \brief Removes the contents of a list box.
 *
 * An application sends an LB_RESETCONTENT message to remove the all items
 * in a list box.
 *
 * \code
 * LB_RESETCONTENT
 *
 * wParam = 0;
 * lParam = 0;
 * \endcode
 *
 * \return Always be zero.
 */
#define LB_RESETCONTENT         0xF184

/**
 * \def LB_GETSEL
 * \brief Gets the selected state for an specified item.
 *
 * An application sends an LB_GETSEL message to a list box to get the selected 
 * state for an item specified in the wParam parameter.
 *
 * \code
 * LB_GETSEL
 * int index;
 *
 * wParam = (WPARAM)index;
 * lParam = 0;
 * \endcode
 *
 * \param index The index of the specified item.
 *
 * \return The state of the specified item:
 *         - 0\n        Not selected.
 *         - >0\n       Selected.
 *         - LB_ERR\n   Invalid index.
 */
#define LB_GETSEL               0xF187

/**
 * \def LB_SETSEL
 * \brief Selects an item in a multiple-selection list box.
 *
 * An application sends an LB_SETSEL message to select an item 
 * in a multiple-selection list box and scroll it into view if necessary.
 *
 * \code
 * LB_SETSEL
 * int index, sel
 *
 * wParam = (WPARAM)sel;
 * lParam = (LPARAM)index;
 * \endcode
 *
 * \param sel Indicates the changes to be made to the listbox item, 
 *        can be one of the following values:
 *             - -1\n      If the item has been selected, makes it unselected, vice versa.
 *             - 0\n       Makes the item unselected. 
 *             - other\n   Makes the item selected. 
 * \param index The index of the item.
 *
 * \return LB_OKAY on success, else LB_ERR to indicate you passed an invalid index
 *         or the list box has no LBS_MULTIPLESEL style.
 */
#define LB_SETSEL               0xF185

/**
 * \def LB_GETCURSEL
 * \brief Gets the index of the currently selected or highlighted item.
 *
 * An application sends an LB_GETCURSEL message to a list box to get the index of 
 * the currently selected item, if there is one, in a single-selection list box.
 * For multiple-selection list box, appliction send an LB_GETCURSEL message to a 
 * list box to get the index of the current highlighted item.
 *
 * \code
 * LB_GETCURSEL
 *
 * wParam = 0;
 * lParam = 0;
 * \endcode
 *
 * \return The index of the currently selected item for single-selection list box;
 *         Eles the index of the highlighted item for multiple-selection list box.
 */
#define LB_GETCURSEL            0xF188

/**
 * \def LB_SETCURSEL
 * \brief Selects an item.
 *
 * An application sends an LB_SETCURSEL message to a list box to 
 * select an item and scroll it into view, if necessary.
 *
 * \code
 * LB_SETCURSEL
 * int cursel;
 *
 * wParam = (WPARAM)cursel;
 * lParam = 0;
 * \endcode
 *
 * \param cursel The index of the item to be selected and hilighted.
 *
 * \return The old index of the item selected on error, else LB_ERR to
 *         indicate an error occurred.
 */
#define LB_SETCURSEL            0xF186

/**
 * \def LB_GETTEXT
 * \brief Retrieves the text of an item in list box.
 *
 * An application sends an LB_GETTEXT message to a list box to retrieve the text
 * of an item.
 *
 * \code
 * LB_GETTEXT
 * int index;
 * char *string;
 *
 * wParam = (WPARAM)index;
 * lParam = (LPARAM)string;
 * \endcode
 *
 * \param index The index of the selected item.
 * \param string Pointer to the string buffer. The buffer should be large enough
 *        to contain the text of the item.
 *
 * \return One of the following values:
 *         - LB_OKAY\n  Success.
 *         - LB_ERR\n   Invalid item index.
 *
 * \sa LB_GETTEXTLEN
 */
#define LB_GETTEXT              0xF189

/**
 * \def LB_GETTEXTLEN
 * \brief Gets the length of text of item specified in a list box.
 *
 * An application sends an LB_GETTEXTLEN message to a list box to get the length 
 * of text of the item specified in the \a wParam parameter.
 *
 * \code
 * LB_GETTEXTLEN
 * int index;
 *
 * wParam = (WPARAM)index;
 * lParam = 0;
 * \endcode
 *
 * \param index The index of the specified item.
 *
 * \return The length of the strings on success, else LB_ERR to indicate invalid index.
 */
#define LB_GETTEXTLEN           0xF18A

/**
 * \def LB_GETCOUNT
 * \brief Gets the number of items in the list box.
 *
 * An application sends an LB_GETCOUNT message to a list box to get the number 
 * of items in the list box.
 *
 * \code
 * LB_GETCOUNT
 *
 * wParam = 0;
 * lParam = 0;
 * \endcode
 *
 * \return The number of items in the listbox.
 */
#define LB_GETCOUNT             0xF18B

#define LB_SELECTSTRING         0xF18C
#define LB_DIR                  0xF18D

/**
 * \def LB_GETTOPINDEX
 * \brief Gets the index to the first visible item in the list box.
 *
 * An application sends an LB_GETTOPINDEX message to get the index to the first 
 * visible item in the list box. Initially, the first visible item is item 0, but 
 * this changes as the list box is scrolled. 
 *
 * \code
 * LB_GETTOPINDEX
 *
 * wParam = 0;
 * lParam = 0;
 * \endcode
 *
 * \return The index of the first visible item in the listbox.
 */
#define LB_GETTOPINDEX          0xF18E

/**
 * \def LB_FINDSTRING
 * \brief Searchs a specified string.
 *
 * An application sends an LB_FINDSTRING message to search a list box for an item 
 * that begins with the characters specified in the lParam parameter. The wParam 
 * parameter specifies the zero-based index of the item before the first item to 
 * be searched; The lParam parameter specifies a pointer to a null-terminated 
 * string that contains the prefix to search for.
 *
 * \code
 * LB_FINDSTRING
 * int index;
 * char *string;
 *
 * wParam = (WPARAM)index;
 * lParam = (LPARAM)string;
 * \endcode
 *
 * \param index The index of the item to be searched.
 * \param string The string of the item to be searched.