listbox.h

Go to the documentation of this file.

/**
 * \file mgui/listbox.h
 * \brief MGUI::CTRL_LISTBOX definitions
 *
 * \if NODOC
 * $Id: listbox.h_v 1.12 2004/11/10 01:46:12 dfriberg Exp $
 *
 * $Log: listbox.h_v $
 * Revision 1.12  2004/11/10 01:46:12  dfriberg
 * Initialize double-click function pointer in convenience class.
 *
 * Revision 1.11  2004/11/08 18:41:23  dwilliss
 * Added ExpandIfNeeded style
 *
 * Revision 1.10  2004/11/05 23:46:19  dwilliss
 * Added a STYLE value for ResizeIfPossible
 * Template version now lets you set OnDoubleClick
 *
 * Revision 1.9  2003/10/03 19:58:19  linux32build!build
 * Doxygen
 *
 * Revision 1.8  2003/09/15 13:49:32  fileserver!dwilliss
 * Doxygen
 *
 * Revision 1.7  2003/09/11 17:05:59  mju
 * Use cast in iniwrite to resolve ambiguity.
 *
 * Revision 1.6  2003/09/10 21:15:29  mju
 * Use ID for id.
 *
 * Revision 1.5  2003/09/10 16:42:23  mju
 * nc.
 *
 * Revision 1.4  2003/09/05 17:10:06  mju
 * AddItem using const MISTRING&.
 *
 * Revision 1.3  2003/04/09 20:51:31  dwilliss
 * Don't use _T in templates. Mac's ctype.h defines a global _T
 *
 * Revision 1.2  2003/01/16 21:35:22  mju
 * Use correct incl guard test.
 *
 * Revision 1.1  2003/01/16 21:12:50  mju
 * Initial revision
 * \endif
**/

#ifndef  INC_MGUI_LISTBOX_H
#define  INC_MGUI_LISTBOX_H

#ifndef INC_MGUI_CTRL_H
#include <mgui/ctrl.h>
#endif

#ifndef  INC_MGUI_LISTITEM_H
#include <mgui/listitem.h>
#endif

namespace MGUI {

#ifndef GENERATING_DOXYGEN_OUTPUT
#ifdef X_NATIVE
class XMLIST;
#endif
#endif // GENERATING_DOXYGEN_OUTPUT

//===================================================================================================================
//! Display simple list of items which user can view and select.
//! In a single-selection list box, the user can select only one item.
//! In a multiple-selection list box, a range of items can be selected.
class CTRL_LISTBOX : public MGUI::CTRL {
   public:

      //! Listbox Style used by Create().
      enum STYLE {
         STYLE_Default =         0x00,
         STYLE_Sorted =          0x01,
         STYLE_MultiSelect =     0x02,       //!< Multiple items selectable by simple toggle of each item
         STYLE_ExtendedSelect =  0x04,       //!< Multiple items selectable by SHIFT/CTRL key and mouse.
         STYLE_ResizeIfPossible = 0x08,         //!< Try to expand and shrink to fit widest item. (uses scrollbar if it can't resize)
         STYLE_ExpandIfNeeded =  0x10        //!< Try to expand fit widest item. (uses scrollbar if it can't resize)
         };

      //! Constructor.
      CTRL_LISTBOX (
         );

      //! Destructor.
      virtual ~CTRL_LISTBOX (
         );

      //! Add item to list box with MISTRING or TEXTID.
      //! If list box was created with STYLE_Sorted then the list will be resorted after the item
      //! is added, otherwise the item will be added to the end of the list.
      //! @return Zero-based index of item added or error < 0.
      int AddItem (
         ID id,                                 //!< ID to attach to item
         const MISTRING& string,                //!< String to show in list
         bool resize = true                     //!< Attempt to resize if needed to fit new item string
         );

      //! Add item to list box with UNICODE* string.
      //! If list box was created with STYLE_Sorted then the list will be resorted after the item
      //! is added, otherwise the item will be added to the end of the list.
      //! @return Zero-based index of item added or error < 0.
      int AddItem (
         ID id,                                 //!< ID to attach to item
         const UNICODE *string,                 //!< String to show in list
         bool resize = true                     //!< Attempt to resize if needed to fit new item string
         ) { return (AddItem(id,MISTRING(string),resize)); }

      //! Add item to list box with string from resource lookup
      //! If list box was created with STYLE_Sorted then the list will be resorted after the item
      //! is added, otherwise the item will be added to the end of the list.
      //! @return Zero-based index of item added or error < 0.
      int AddItem (
         ID id,                                 //!< ID to attach to item
         const char *string,                    //!< String for resource lookup
         bool resize = true                     //!< Attempt to resize if needed to fit new item string
         );

      //! Add multiple items.
      void AddItems (
         const MGUI::LISTITEMDEF *items,        //!< Items to add, terminated by item with NULL string
         bool resize = true                     //!< Attempt to resize if needed to fit largest item string
         );

      //! Create the list box control.
      void Create (
         MGUI::LAYOUT_PANE_BASE& ParentPane,    //!< Parent pane
         const MGUI::LISTITEMDEF *items = 0,    //!< Initial item set, 0 for none
         int height = 5,                        //!< Height in characters
         int width = 0,                         //!< Width in 'typical' characters
         MGUI::LAYOUT_SIZEALIGN sizealign = MGUI::LAYOUT_SIZEALIGN_Expand,
         STYLE style = STYLE_Default
         );

      //! Delete all items from list box.
      void DeleteAllItems (
         );

      //! Delete item from list box.
      void DeleteItem (
         int index                              //!< Zero-based index of list box item to delete
         );

      //! Delete item from list box given ID.
      void DeleteItemID (
         ID id                                  //!< ID of item to delete
         );

      //! Deselect all items in multiple-selection list box.
      //! This method should not be used on single-selection list boxes.
      void DeselectAllItems (
         );

      //! Retrieve number of items in the list box.
      int GetCount (
         ) const;

   #ifdef WIN32_MFC
      //! Get reference to MFC control (MFC only).
      CListBox& GetCtrl (
         ) { return (m_ctrl); }
   #endif

      //! Get index to item from ID.
      //! @return Zero-based index or -1 if no matching item found.
      int GetIndexFromID (
         ID id
         ) const;

      //! Get ID associated with list box item.
      //! @return ID specified when item was added.
      ID GetItemID (
         int index                           //!< Zero-based index of list box item
         ) const;

      //! Get text string associated with list box item.
      //! @return String containing text, will be empty if invalid item.
      MISTRING GetItemString (
         int index                           //!< Zero-based index of list box item
         ) const;

      //! Get number of selected items in multiple-selection list box.
      //! @return Number of selected items or 0 if none selected.
      int GetSelectedCount (
         ) const;

      //! Get currently selected item in single-selection list box.
      //! @return Zero-based index of selected item or -1 if none selected.
      int GetSelectedItem (
         ) const;

      //! Get ID of currently selected item in single-selection list box.
      //! @return ID or -1 if none selected.
      ID GetSelectedItemID (
         ) const;

      //! Retrieve indices of selected items in multiple-selection list box.
      ERRVALUE GetSelectedItems (
         SIMPLE_ARRAY<int>& items
         ) const;

      //! Retrieve zero-based index of first visible item in list box.
      int GetTopIndex (
         ) const;

      //! Read setting from INI file.
      //! If Create() has already been performed the control's state will be updated.
      void IniRead (
         INIHANDLE IniHandle,                //!< Handle to INI file to read from, 0 for default
         const char *IniGroup,               //!< INI group to read from
         const char *IniField,               //!< INI field to read from
         bool notify = true                  //!< Call OnSelection() if control has already been created
         );

      //! Write currently selected item ID to INI file.
      void IniWrite (
         INIHANDLE IniHandle,                //!< Handle to INI file to read from, 0 for default
         const char *IniGroup,               //!< INI group to read from
         const char *IniField                //!< INI field to read from
         ) const { ::IniWrite(IniHandle,IniGroup,IniField,static_cast<INT32>(GetSelectedItemID())); }

      //! Insert item at specified position in list box.
      //! Unlike the AddItem method this does not cause the list to be resorted.
      //! @return Zero-based index of item added or error < 0.
      int InsertItem (
         int index,                          //!< Zero-based index of position at which item should be inserted
         ID id,                              //!< ID to attach to item
         const MISTRING& string              //!< String to show in list
         );

      //! Determine if specified item in list box is selected.
      bool IsItemSelected (
         int index                           //!< Zero-based index of list box item
         ) const;

      //! Select or deselect item in multiple-selection list box.
      //! This method should not be used on single-selection list boxes.
      void SetItemSelected (
         int index,                          //!< Zero-based index of list box item.
         bool select = true                  //!< Specifies how to set the selection, true to select, false to deselect.
         );

      //! Select item in single-selection list box.
      //! If item is not visible the list box will be scrolled to make it visible.
      //! This method should not be used on multiple-selection list boxes.
      void SetSelectedItem (
         int index                           //!< Zero-based index of list box item, -1 to have no item selected
         );

      //! Select item in list box using item ID.
      //! If item does not exist then no item will be selected.
      //! If item is not visible the list box will be scrolled to make it visible.
      void SetSelectedItemID (
         ID id                               //!< ID of item to select
         );

      //! Scroll list box until item specified by index is at the top or maximum scroll range reached.
      void SetTopIndex (
         int index                           //!< Zero-based index of list box item
         );
         
   protected:

      //! Derived class must call corresponding base class method BEFORE performing its own processing.
      virtual void OnChangeSelection ();

      //! User has double-clicked on item in list box.
      //! Derived class must call corresponding base class method BEFORE performing its own processing.
      virtual void OnDoubleClick ();

   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT

   #ifdef WIN32_MFC
      class MyListBox : public CListBox {
         public:
            MyListBox (
               MGUI::CTRL_LISTBOX& guictrl
               ): m_guictrl(guictrl)
               { }
            virtual ~MyListBox (
               ) { }
            virtual BOOL PreCreateWindow (CREATESTRUCT& cs);
         protected:
            afx_msg void OnSelChange ();
            DECLARE_MESSAGE_MAP()
         private:
            MGUI::CTRL_LISTBOX& m_guictrl;
         };
      friend class MyListBox;

      MyListBox m_ctrl;
   #endif

   #ifdef X_NATIVE
      XMLIST *m_pxmlist;
      static void CB_ChangeSelection (Widget, CTRL_LISTBOX*, void*);
      static void CB_DoubleClick (Widget, CTRL_LISTBOX*, void*);
   #endif

      CTRL_LISTBOX (const CTRL_LISTBOX&);
      CTRL_LISTBOX& operator= (const CTRL_LISTBOX&);
      #endif // GENERATING_DOXYGEN_OUTPUT
   };

DEFINE_ENUM_OPERATORS(MGUI::CTRL_LISTBOX::STYLE);


//-------------------------------------------------------------------------------------------------------------------
//! Convenience template for List box control to allow method in container class to be called.
template <class _CT> class CTRL_LISTBOX_T : public MGUI::CTRL_LISTBOX {
   public:
      //! Constructor.
      CTRL_LISTBOX_T (
         ): 
         m_pContainer(0), 
         m_pfOnChangeSelection(0), 
         m_pfOnDoubleClick(0)
         { }

      //! Create the list box control.
      void Create (
         MGUI::LAYOUT_PANE_BASE& ParentPane,    //!< Parent pane
         _CT *pContainer,                       //!< Pointer to callback container class
         void (_CT::*pfOnChangeSelection)(),    //! Callback function pointer
         const MGUI::LISTITEMDEF *items = 0,    //!< Initial item set, 0 for none
         int height = 5,                        //!< Height in characters
         int width = 0,                         //!< Width in 'typical' characters
         MGUI::LAYOUT_SIZEALIGN sizealign = MGUI::LAYOUT_SIZEALIGN_Expand,
         STYLE style = STYLE_Default
         ) {
         m_pContainer = pContainer;
         m_pfOnChangeSelection = pfOnChangeSelection;
         CTRL_LISTBOX::Create(ParentPane,items,height,width,sizealign,style);
         }

      void SetFuncDoubleClick (
         void (_CT::*pfOnDoubleClick)()
         ) {
         m_pfOnDoubleClick = pfOnDoubleClick;
         }

   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT
      _CT *m_pContainer;
      void (_CT::*m_pfOnChangeSelection)();
      void (_CT::*m_pfOnDoubleClick)();

      virtual void OnChangeSelection (
         ) {
         CTRL_LISTBOX::OnChangeSelection();
         if (m_pContainer != 0 && m_pfOnChangeSelection != 0) (m_pContainer->*m_pfOnChangeSelection)();
         return;
         }

      virtual void OnDoubleClick (
         ) {
         CTRL_LISTBOX::OnDoubleClick();
         if (m_pContainer != 0 && m_pfOnDoubleClick != 0) (m_pContainer->*m_pfOnDoubleClick)();
         return;
         }
      #endif // GENERATING_DOXYGEN_OUTPUT
   };

//===================================================================================================================

}  // End namespace MGUI

#endif   //INC_MGUI_LISTBOX_H

---