scrollview.h

minigui_1.6.9在WINDOWS32下的原代码,是嵌入式GUI产品,是北京飞漫公司的正式版本.

/**
 * \file scrollview.h
 * \author Wei Yongming <[e-mail]>
 * \date 2001/12/29
 * 
 \verbatim

    Copyright (C) 2002-2006 Feynman Software.
    Copyright (C) 1998-2002 Wei Yongming.

    All rights reserved by Feynman Software.

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

 \endverbatim
 */

/*
 * $Id: scrollview.h,v 1.11 2006/06/11 04:16:16 weiym Exp $
 *
 *             MiniGUI for Linux/uClinux, eCos, uC/OS-II, VxWorks, 
 *                     pSOS, ThreadX, NuCleus, OSE, and Win32.
 *
 *             Copyright (C) 2002-2006 Feynman Software.
 *             Copyright (C) 1999-2002 Wei Yongming.
 */

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

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

    /**
     * \defgroup ctrl_scrollview ScrollView control
     * @{
     *
     * Scrollview control is a scrollable window, which has a visible area and
     * normally a larger content area, user can browse content area using scrollbar.
     * Contents of the content area is totally user-defined, you can add controls in it,
     * add customed listed items, or anything you want.
     *
     * In fact, you can build a control needing scrolled window support on scrollview.
     */

/**
 * \def CTRL_SCROLLVIEW
 * \brief The class name of scrollview control, uses this name to create a scrollable
 *        window that consists of items.
 *
 */
#define CTRL_SCROLLVIEW           ("scrollview")

/**
 * \def CTRL_SCROLLWND
 * \brief The class name of scrollwnd control, uses this name to create a scrollable
 *        window to which you can add controls.
 *
 */
#define CTRL_SCROLLWND            ("scrollwnd")

/** Default container window procedure 
 * \sa DefaultDialogProc 
 */
MG_EXPORT int GUIAPI DefaultContainerProc (HWND hWnd, int message, WPARAM wParam, LPARAM lParam);

/** Scrollview item object, use this handle to access a scrollview item */
typedef GHANDLE HSVITEM;

/**
 * Structure which defines a container.
 */
typedef struct _CONTAINERINFO
{
#if 0
    DWORD       dwStyle;                /** style of the container */
    DWORD       dwExStyle;              /** extended style of the container */
    int         x, y, w, h;             /** position and size of the container */
#endif
    /** User-defined window procedure of the container */
    WNDPROC     user_proc;              
    /** Number of controls */
    int         controlnr;              
    /** Pointer to control array */
    PCTRLDATA   controls;               
    /** Additional data */
    DWORD       dwAddData;              
} CONTAINERINFO;
/** Data type of pointer to a CONTAINERINFO */
typedef CONTAINERINFO* PCONTAINERINFO;

/** 
 * \fn DWORD mglist_get_item_adddata (GHANDLE hi)
 * \brief Use this to get additional data from a list item in a control, such as
 *        scrollview and iconview.
 */
MG_EXPORT DWORD mglist_get_item_adddata (GHANDLE hi);

/** 
 * \fn DWORD scrollview_get_item_adddata (HSVITEM hsvi)
 * \brief Use this to get additional data from scrollview item 
 */
MG_EXPORT DWORD scrollview_get_item_adddata (HSVITEM hsvi);

/**
 * \fn int scrollview_get_item_index (HWND hWnd, HSVITEM hsvi);
 * \brief To get item index
 */ 
MG_EXPORT int scrollview_get_item_index (HWND hWnd, HSVITEM hsvi);

/**
 * \fn int scrollview_is_item_hilight (HWND hWnd, HSVITEM hsvi)
 * \brief To decide whether an item is the current hilighted item
 */
MG_EXPORT BOOL scrollview_is_item_hilight (HWND hWnd, HSVITEM hsvi);

/**
 * \fn int scrollview_is_item_selected (HSVITEM hsvi)
 * \brief To decide whether an item is a selected
 */
MG_EXPORT BOOL scrollview_is_item_selected (HSVITEM hsvi);

/**
 * \fn int scrollview_set_item_height (HWND hWnd, HSVITEM hsvi, int height)
 * \brief Sets the height of an item
 */
MG_EXPORT int scrollview_set_item_height (HWND hWnd, HSVITEM hsvi, int height);

/**
 * \var typedef void (* SVITEM_INITFUNC)(HWND hWnd, HSVITEM hsvi)
 * \brief Type of the scrollview item initialization callback procedure.
 *
 * \param hWnd Handle of the scrollview control .
 * \param hsvi Scrollview item handle.
 *
 * \return Zero on success; otherwise -1.
 */
typedef int  (*SVITEM_INITFUNC)    (HWND hWnd, HSVITEM hsvi);

/**
 * \var typedef void (* SVITEM_DESTROYFUNC)(HWND hWnd, HSVITEM hsvi)
 * \brief Type of the scrollview item destroy callback procedure.
 *
 * \param hWnd Handle of the scrollview control .
 * \param hsvi Scrollview item handle.
 */
typedef void (*SVITEM_DESTROYFUNC) (HWND hWnd, HSVITEM hsvi);

/**
 * \var typedef void (*SVITEM_DRAWFUNC)(HWND hWnd, HSVITEM hsvi, HDC hdc, RECT *rcDraw)
 * \brief Type of the scrollview item drawing callback procedure.
 *
 * \param hWnd Handle of the scrollview control.
 * \param hsvi Scrollview item handle.
 * \param hdc  Drawing device context.
 * \param rcDraw Drawing rect area.
 */
typedef void (*SVITEM_DRAWFUNC) (HWND hWnd, HSVITEM hsvi, HDC hdc, RECT *rcDraw);

/**
 * \var typedef int (*SVITEM_CMP) (HSVITEM hsvi1, HSVITEM hsvi2)
 * \brief Type of the scrollview item compare function
 */
typedef int (*SVITEM_CMP) (HSVITEM hsvi1, HSVITEM hsvi2);

/** Structure of item operations */
typedef struct _svitem_operations
{
    /** Called when an scrollview item is created */
    SVITEM_INITFUNC     initItem;     
    /** Called when an item is destroied */
    SVITEM_DESTROYFUNC  destroyItem;  
    /** Call this to draw an item */
    SVITEM_DRAWFUNC     drawItem;     
} SVITEMOPS;
/** Data type of pointer to a SVITEMOPS */
typedef SVITEMOPS* PSVITEMOPS;

/** Structure of the scrollview item info */
typedef struct _SCROLLVIEWITEMINFO
{
    /** Index of item */
    int        nItem;           
    /** Height of an item */
    int        nItemHeight;     
    /** Item additional data */
    DWORD      addData;         
} SVITEMINFO;
/** Data type of pointer to a SVITEMINFO */
typedef SVITEMINFO* PSVITEMINFO;

    /**
     * \defgroup ctrl_scrollview_styles Styles of scrollview control
     * @{
     */

/**
 * \def SVS_UPNOTIFY
 * \brief Sends the notification messages to parent window when the keys is up. 
 */
#define SVS_UPNOTIFY            0x0001L

#define SVS_NOTIFY              0x0002L

/**
 * \def SVS_AUTOSORT
 * \brief Automatically sorts strings entered in the scrollview control. 
 */
#define SVS_AUTOSORT            0x0004L

/**
 * \def SVS_LOOP
 * \brief Loops the item automatically when user select item with down or up key.
 */
#define SVS_LOOP                0x0008L

    /** @} end of ctrl_scrollview_styles */

    /**
     * \defgroup ctrl_scrollview_msgs Messages of scrollview control
     * @{
     */

/**
 * \def SVM_ADDITEM
 * \brief Adds an item in the scrollview.
 *
 * \code
 * SVM_ADDITEM
 * SVITEMINFO svii;
 * HSVITEM *phsvi;
 *
 * wParam = (WPARAM)phsvi;
 * lParam = (LPARAM)&svii;
 * \endcode
 *
 * \param &svii Pointer to a scrollview item information structure.
 * \param phsvi Pointer to a HSVITEM var, used to store the item handle
 *              returned.
 *
 * \return Index of the scrollview item on success; otherwise -1.
 */
#define SVM_ADDITEM             0xF300

/**
 * \def SVM_DELITEM
 * \brief Deletes an item from the scrollview.
 *
 * \code
 * SVM_DELITEM
 * int nItem;
 * HSVITEM hsvi;
 *
 * wParam = (WPARAM)nItem;
 * lParam = (LPARAM)hsvi;
 * \endcode
 *
 * \param nItem Scrollview item index to delete.
 *              If hsvi is not zero, nItem will be ignored.
 * \param hsvi Scrollview item handle to delete.
 *
 * \return Zero on success; otherwise -1.
 */
#define SVM_DELITEM             0xF301

/**
 * \def SVM_SETITEMDRAW
 * \brief Sets the drawing operation of an item.
 *
 * Scrollview item drawing function will be called when doing with MSG_PAINT message,
 * scrollview window should define this function if it want to draw an customed item.
 *
 * \code
 * SVM_SETITEMDRAW
 * SVITEM_DRAWFUNC pfn;
 *
 * wParam = 0;
 * lParam = (LPARAM)pfn;
 * \endcode
 *
 * \param pfn Scrollview item drawing function.
 *
 * \return Old drawing function pointer; otherwise 0.
 */
#define SVM_SETITEMDRAW         0xF302

/**
 * \def SVM_ADDCTRLS
 * \brief Adds controls to the scrollview.
 *
 * \code
 * SVM_ADDCTRLS
 * int itemNr;
 * PCTRLDATA pctrls;
 *
 * wParam = (WPARAM)itemNr;
 * lParam = (LPARAM)pctrls;
 * \endcode
 *
 * \param ctrlNr Control number in the pctrls control array.
 * \param pctrls Points to a CTRLDATA array that defines controls.
 *
 * \return Zero on success; otherwise -1.
 */
#define SVM_ADDCTRLS            0xF303

/**
 * \def SVM_SETCONTWIDTH
 * \brief Sets the scrollview content area (scrollable area) width.
 *
 * Scrollable area of a scrolled window is always larger than the visible area.
 *
 * \code
 * SVM_SETCONTWIDTH
 * int cont_w;
 *
 * wParam = (WPARAM)cont_w;
 * lParam = 0;
 * \endcode
 *
 * \param cont_w Scrollview content width.
 *
 * \return Zero on success; otherwise -1.
 */
#define SVM_SETCONTWIDTH        0xF306

/**
 * \def SVM_SETCONTHEIGHT
 * \brief Sets the scrollview content area (scrollable area) height.
 *
 * Scrollable area of a scrolled window is always larger than the visible area.
 *
 * \code
 * SVM_SETCONTHEIGHT
 * int cont_h;
 *
 * wParam = (WPARAM)cont_h;
 * lParam = 0;
 * \endcode
 *
 * \param cont_h Scrollview content height.
 *
 * \return Zero on success; otherwise -1.
 */
#define SVM_SETCONTHEIGHT       0xF307

/**
 * \def SVM_GETCTRL
 * \brief Gets the control handle in the scrollview window by control id.
 *
 * \code
 * SVM_GETCTRL
 * int id;
 *
 * wParam = (WPARAM)id;
 * lParam = 0;
 * \endcode
 *
 * \param id Control id.
 *
 * \return Control window handle on success; otherwise 0.
 */
#define SVM_GETCTRL             0xF308

/**
 * \def SVM_RESETCONTENT
 * \brief Clears all the controls and the items added to the scrollview window.
 *
 * \code
 * SVM_RESETCONTENT
 *
 * wParam = 0;
 * lParam = 0;
 * \endcode
 *
 * \return Zero on success; otherwise -1.
 */
#define SVM_RESETCONTENT        0xF309

/**
 * \def SVM_SETITEMOPS
 * \brief Sets the item operations of the items in the scrollview.
 *
 * Normally item operations should be set before adding items.
 *
 * \code
 * SVM_SETITEMOPS
 * SVITEMOPS *iop;
 *
 * wParam = 0;
 * lParam = (LPARAM)iop;
 * \endcode
 *
 * \param iop Points to a SVITEMOPS structure that defines item operations
 *
 * \return Zero on success; otherwise -1.
 */
#define SVM_SETITEMOPS          0xF30a

/**
 * \def SVM_GETMARGINS
 * \brief Gets the margin values of the scrollview.
 *
 * Application should use a RECT structure to get left, top, right, and bottom margins.
 *
 * \code
 * SVM_GETMARGINS
 * RECT rcMargin;
 *
 * wParam = 0;
 * lParam = (LPARAM)&rcMargin;
 * \endcode
 *
 * \param rcMargin A RECT for storing 4 margin values.
 *
 * \return 0 on success.
 */
#define SVM_GETMARGINS            0xF30b

/**
 * \def SVM_SETMARGINS
 * \brief Sets the margin values of the scrollview.
 *
 * Application should use a RECT structure to give left, top, right, and bottom margins.
 * If you want to change a margin value, give a value large than zero, or else -1.
 *
 * \code
 * SVM_SETMARGINS
 * RECT *rcMargin;
 *
 * wParam = 0;
 * lParam = (LPARAM)rcMargin;
 * \endcode
 *
 * \param rcMargin A RECT Containing 4 margin values.
 *
 * \return 0 on success.
 */
#define SVM_SETMARGINS            0xF311

/**
 * \def SVM_GETLEFTMARGIN
 * \brief Gets the left margin value of the scrollview.
 *
 * \code
 * SVM_GETLEFTMARGIN
 *
 * wParam = 0;
 * lParam = 0;
 * \endcode
 *
 * \return Left margin value on success, otherwise -1.
 */
#define SVM_GETLEFTMARGIN         0xF312

/**
 * \def SVM_GETTOPMARGIN
 * \brief Gets the top margin value of the scrollview.
 *
 * \code
 * SVM_GETTOPMARGIN
 *
 * wParam = 0;
 * lParam = 0;
 * \endcode
 *
 * \return Top margin value on success, otherwise -1.
 */
#define SVM_GETTOPMARGIN          0xF313

/**
 * \def SVM_GETRIGHTMARGIN
 * \brief Gets the right margin value of the scrollview.
 *
 * \code
 * SVM_GETRIGHTMARGIN
 *
 * wParam = 0;
 * lParam = 0;
 * \endcode
 *
 * \return Right margin value on success, otherwise -1.
 */
#define SVM_GETRIGHTMARGIN        0xF314

/**
 * \def SVM_GETBOTTOMMARGIN
 * \brief Gets the bottom margin value of the scrollview.
 *
 * \code
 * SVM_GETBOTTOMMARGIN
 *
 * wParam = 0;
 * lParam = 0;
 * \endcode
 *
 * \return Bottom margin value on success, otherwise -1.
 */
#define SVM_GETBOTTOMMARGIN       0xF315

/**
 * \def SVM_GETVISIBLEWIDTH
 * \brief Gets the width of the visible content area.
 *
 * \code
 * SVM_GETVISIBLEWIDTH
 *
 * wParam = 0;
 * lParam = 0;
 * \endcode
 *
 * \return Width of the visible content area on success, otherwise -1.
 */
#define SVM_GETVISIBLEWIDTH       0xF316

/**
 * \def SVM_GETVISIBLEHEIGHT
 * \brief Gets the height of the visible content area.
 *
 * \code
 * SVM_GETVISIBLEHEIGHT
 *
 * wParam = 0;
 * lParam = 0;
 * \endcode
 *
 * \return Height of the visible content area on success, otherwise -1.
 */
#define SVM_GETVISIBLEHEIGHT      0xF317

/**
 * \def SVM_GETCONTWIDTH
 * \brief Gets the width of the content area.
 *
 * \code
 * SVM_GETCONTWIDTH
 *
 * wParam = 0;
 * lParam = 0;
 * \endcode