//*****************************************************************************
//
// listbox.h - Prototypes for the listbox widget.
//
// Copyright (c) 2008-2010 Texas Instruments Incorporated.  All rights reserved.
// Software License Agreement
// 
// Texas Instruments (TI) is supplying this software for use solely and
// exclusively on TI's microcontroller products. The software is owned by
// TI and/or its suppliers, and is protected under applicable copyright
// laws. You may not combine this software with "viral" open-source
// software in order to form a larger program.
// 
// THIS SOFTWARE IS PROVIDED "AS IS" AND WITH ALL FAULTS.
// NO WARRANTIES, WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT
// NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. TI SHALL NOT, UNDER ANY
// CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
// DAMAGES, FOR ANY REASON WHATSOEVER.
// 
// This is part of revision 5821 of the Stellaris Graphics Library.
//
//*****************************************************************************

#ifndef __LISTBOX_H__
#define __LISTBOX_H__

//*****************************************************************************
//
//! \addtogroup listbox_api
//! @{
//
//*****************************************************************************

//*****************************************************************************
//
// If building with a C++ compiler, make all of the definitions in this header
// have a C binding.
//
//*****************************************************************************
#ifdef __cplusplus
extern "C"
{
#endif

//*****************************************************************************
//
//! The structure that describes a listbox widget.
//
//*****************************************************************************
typedef struct
{
    //
    //! The generic widget information.
    //
    tWidget sBase;

    //
    //! The style for this widget.  This is a set of flags defined by
    //! LISTBOX_STYLE_xxx.
    //
    unsigned long ulStyle;

    //
    //! The 24-bit RGB color used as the background for the listbox.
    //
    unsigned long ulBackgroundColor;

    //
    //! The 24-bit RGB color used as the background for the selected entry
    //! in the listbox.
    //
    unsigned long ulSelectedBackgroundColor;

    //
    //! The 24-bit RGB color used to draw text on this listbox.
    //
    unsigned long ulTextColor;

    //
    //! The 24-bit RGB color used to draw the selected text on this listbox.
    //
    unsigned long ulSelectedTextColor;


    //
    //! The 24-bit RGB color used to outline this listbox, if
    //! LISTBOX_STYLE_OUTLINE is selected.
    //
    unsigned long ulOutlineColor;

    //
    //! A pointer to the font used to render the listbox text.
    //
    const tFont *pFont;

    //
    //! A pointer to the array of string pointers representing the contents of
    //! the list box.
    //
    const char **ppcText;

    //
    //! The number of elements in the array pointed to by pccText.
    //
    unsigned short usMaxEntries;

    //
    //! The number of elements in the array pointed to by pccText which are
    //! currently populated with strings.
    //
    unsigned short usPopulated;

    //
    //! The index of the string currently selected in the list box.  If no
    //! selection has been made, this will be set to 0xFFFF (-1).
    //
    short sSelected;

    //
    //! The index of the string that appears at the top of the list box.  This
    //! is used by the widget class to control scrolling of the box content.
    //! This is an internal variable and must not be modified by an application
    //! using this widget class.
    //
    unsigned short usStartEntry;

    //
    //! The index of the oldest entry in the ppcText array.  This is used by the
    //! widget class to determine where to add a new string if the array is
    //! full and the listbox has style LISTBOX_STYLE_WRAP.  This is an internal
    //! variable and must not be modified by an application using this widget
    //! class.
    //
    unsigned short usOldestEntry;

    //
    //! A flag which we use to determine whether to change the selected element
    //! when the pointer is lifted.  The listbox will change the selection if
    //! no scrolling was performed since the last WIDGET_MSG_PTR_DOWN was
    //! received.  This is an internal variable and must not be modified by
    //! an application using this widget class.
    //
    unsigned short usScrolled;

    //
    //! The Y coordinate of the last pointer position we received.  This is an
    //! internal variable used to manage scrolling of the listbox contents and
    //! must not be modified by an application using this widget class.
    //
    long lPointerY;

    //
    //! A pointer to the application-supplied callback function.  This function
    //! will be called each time the selected element in the list box changes.
    //! The sSelIndex parameter contains the index of the selected string in
    //! ppcText array or, if no element is selected, 0xFFFF (-1).
    //
    void (*pfnOnChange)(tWidget *pWidget, short sSelIndex);
}
tListBoxWidget;

//*****************************************************************************
//
//! This flag indicates that the listbox should be outlined.  If enabled, the
//! widget is drawn with a two pixel border, the outer, single pixel rectangle
//! of which is in the color found in the ulOutlineColor field of the widget
//! structure and the inner rectangle in color ulBackgroundColor.
//
//*****************************************************************************
#define LISTBOX_STYLE_OUTLINE    0x00000001

//*****************************************************************************
//
//! This flag indicates that the listbox is not interactive but merely displays
//! strings.  Scrolling of the listbox content is supported when this flag is
//! set but widgets using this style do not make callbacks to the application
//! and do not support selection and deselection of entries.  This may be used
//! if a listbox is intended, for example, as a text output or status reporting
//! control.
//
//*****************************************************************************
#define LISTBOX_STYLE_LOCKED     0x00000002

//*****************************************************************************
//
//! This flag controls the behavior of the listbox if a new string is added
//! when the string table (ppcText) is already full.  If this style is set, the
//! oldest string in the table is replaced with new one and, if the discarded
//! string was currently displayed, the display positions will be fixed up to
//! ensure that the (new) oldest string remains at the top of the listbox.  If
//! this style is not set, the attempt to set a new string will fail if the
//! table is full.
//
//*****************************************************************************
#define LISTBOX_STYLE_WRAP       0x00000004

//*****************************************************************************
//
//! Declares an initialized listbox widget data structure.
//!
//! \param pParent is a pointer to the parent widget.
//! \param pNext is a pointer to the sibling widget.
//! \param pChild is a pointer to the first child widget.
//! \param pDisplay is a pointer to the display on which to draw the listbox.
//! \param lX is the X coordinate of the upper left corner of the listbox.
//! \param lY is the Y coordinate of the upper left corner of the listbox.
//! \param lWidth is the width of the listbox.
//! \param lHeight is the height of the listbox.
//! \param ulStyle is the style to be applied to the listbox.
//! \param ulBgColor is the background color for the listbox.
//! \param ulSelBgColor is the background color for the selected element in the
//! listbox.
//! \param ulTextColor is the color used to draw text on the listbox.
//! \param ulSelTextColor is the color used to draw the selected element text
//! in the listbox.
//! \param ulOutlineColor is the color used to outline the listbox.
//! \param pFont is a pointer to the font to be used to draw text on the
//! listbox.
//! \param ppcText is a pointer to the string table for the listbox.
//! \param usMaxEntries provides the number of entries in the \e ppcText array
//! and represents the maximum number of strings the listbox can hold.
//! \param usPopulatedEntries indicates the number of entries in the \e ppcText
//! array that currently hold valid string for the listbox.
//! \param pfnOnChange is a pointer to the application callback for the listbox.
//!
//! This macro provides an initialized listbox widget data structure, which can
//! be used to construct the widget tree at compile time in global variables
//! (as opposed to run-time via function calls).  This must be assigned to a
//! variable, such as:
//!
//! \verbatim
//!     tListBoxWidget g_sListBox = ListBoxStruct(...);
//! \endverbatim
//!
//! Or, in an array of variables:
//!
//! \verbatim
//!     tListBoxWidget g_psListBox[] =
//!     {
//!         ListBoxStruct(...),
//!         ListBoxStruct(...)
//!     };
//! \endverbatim
//!
//! \e ulStyle is the logical OR of the following:
//!
//! - \b #LISTBOX_STYLE_OUTLINE to indicate that the listbox should be outlined.
//! - \b #LISTBOX_STYLE_LOCKED to indicate that the listbox should ignore user
//!   input and merely display its contents.
//! - \b #LISTBOX_STYLE_WRAP to indicate that the listbox should discard the
//!   oldest string it contains if asked to add a new string while the string