combobox.h

Go to the documentation of this file.

/**
 * \file mgui/combobox.h
 * \brief MGUI::COMBOBOX definitions
 *
 * \if NODOC
 * $Id: combobox.h_v 1.14 2005/03/31 16:57:07 fileserver!dwilliss Exp $
 *
 * $Log: combobox.h_v $
 * Revision 1.14  2005/03/31 16:57:07  fileserver!dwilliss
 * Rename one of our types to MIUNICODE because it conflicted with a Microsoft #define
 *
 * Revision 1.13  2004/01/02 22:21:19  mju
 * Need to override setenabled for form too.
 *
 * Revision 1.12  2003/12/22 14:16:03  mju
 * Make SetEnabled public.
 *
 * Revision 1.11  2003/12/19 22:07:57  mju
 * Override setenabled for X.
 *
 * Revision 1.10  2003/11/17 18:10:22  mju
 * Add combobox::sizeToContentWidth.
 *
 * 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:20  mju
 * Use cast in IniWrite to resolve ambiguity.
 *
 * Revision 1.6  2003/09/10 21:15:25  mju
 * Use ID for id.
 *
 * Revision 1.5  2003/09/10 16:42:21  mju
 * nc.
 *
 * Revision 1.4  2003/09/05 17:09:43  mju
 * AddItem using const MISTRING&.
 *
 * Revision 1.3  2003/04/09 20:47:44  dwilliss
 * Don't define _T in templates. Mac's ctype.h defines a global _T
 *
 * Revision 1.2  2003/01/16 21:35:32  mju
 * Fix incl guard test.
 *
 * Revision 1.1  2003/01/16 21:13:02  mju
 * Initial revision
 * \endif
**/

#ifndef  INC_MGUI_COMBOBOX_H
#define  INC_MGUI_COMBOBOX_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

//===================================================================================================================
//! ComboBox control.
//! At present this is implemented as an OptionMenu for X.
class CTRL_COMBOBOX : public MGUI::CTRL {
   public:

      enum STYLE {
         STYLE_Default =   0x00,
         STYLE_Sorted =    0x01
         };

      //! Constructor.
      CTRL_COMBOBOX (
         );

      //! Destructor.
      virtual ~CTRL_COMBOBOX (
         );

      //! Add single item with MISTRING or TEXTID.
      //! If control was created with STYLE_Sorted then the combo 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 single item with string from resource lookup.
      //! If control 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
         );

      //! Add items to combobox for unit selection.
      //! Item IDs will be equal to UnitIDs.
      void AddUnitItems (
         int UnitType,                          //!< Unit type
         int DftUnitID = 0                      //!< Default unit ID
         );

      //! Create control.
      void Create (
         MGUI::LAYOUT_PANE_BASE& ParentPane,    //!< Parent pane
         const MGUI::LISTITEMDEF *items = 0,    //!< Initial item set, 0 for none
         int listheight = 7,                    //!< Maximum list height when dropped down in characters
         int width = 0,                         //!< Width in 'typical' characters, 0 for default
         MGUI::LAYOUT_SIZEALIGN sizealign = MGUI::LAYOUT_SIZEALIGN_FixedSize,
         STYLE style = STYLE_Default
         );

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

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

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

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

   #ifdef WIN32_MFC
      //! Get reference to MFC control (MFC only).
      CComboBox& 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                            //!< ID of item to retrieve index of
         ) const;

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

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

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

      //! Get ID of currently selected item.
      //! @return ID or -1 if item was not found or none selected.
      ID GetSelectedItemID (
         ) 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.
      //! 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 combo
         );

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

   #ifdef X_NATIVE
      //! Set whether control is enabled.
      virtual void SetEnabled (
         bool enabled = true
         );
   #endif

      //! Select item using zero-based index.
      //! If item is not visible the list will be scrolled to make it visible.
      void SetSelectedItem (
         int index                           //!< Zero-based index of item, -1 to have no item selected
         );

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

      //! Set whether items are to be sorted or not.
      void SetSorted (
         bool sorted = true
         );

      //! Resize control to be able to show widest item.
      void SizeToContentWidth (
         );

   protected:

      //! Called when user makes selection.
      //! Derived class must call corresponding base class method BEFORE performing its own processing.
      virtual void OnSelection ();

   private:
   #ifndef GENERATING_DOXYGEN_OUTPUT

   #ifdef WIN32_MFC
      class MyComboBox : public CComboBox {
         public:
            MyComboBox (
               MGUI::CTRL_COMBOBOX& guictrl
               ): m_guictrl(guictrl)
               { }
            virtual ~MyComboBox (
               ) { }
         protected:
            afx_msg void OnSelendok ();
            DECLARE_MESSAGE_MAP()
         private:
            MGUI::CTRL_COMBOBOX& m_guictrl;
         };
      friend class MyComboBox;

      MyComboBox m_ctrl;
   #endif

   #ifdef X_NATIVE
      Widget m_text;
      Widget m_arrowpb;
      XMLIST *m_pxmlist;
      Widget m_listshell;
      int m_listheight;

      static void CB_ArrowActivate (Widget, CTRL_COMBOBOX*, void*);
      static void CB_ListBrowseSelect (Widget, CTRL_COMBOBOX*, void*);
      static void EH_Shell (Widget, CTRL_COMBOBOX*, XEvent*, Boolean*);
      void PopdownShell ();
      void PopupShell ();
   #endif

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

DEFINE_ENUM_OPERATORS(MGUI::CTRL_COMBOBOX::STYLE);


//-------------------------------------------------------------------------------------------------------------------
//! Convenience template for COMBOBOX control to allow method in container class to be called.
template <class _CT> class CTRL_COMBOBOX_T : public MGUI::CTRL_COMBOBOX {
   public:
      //! Constructor.
      explicit CTRL_COMBOBOX_T (
         ): m_pContainer(0), m_pfOnSelection(0)
         { }

      //! Create control.
      void Create (
         MGUI::LAYOUT_PANE_BASE& ParentPane,    //!< Parent pane
         _CT *pContainer,                       //!< Pointer to callback container class
         void (_CT::*pfOnSelection)(),          //! Callback function pointer
         const MGUI::LISTITEMDEF *items = 0,    //!< Initial item set, 0 for none
         int listheight = 7,                    //!< Maximum list height when dropped down in characters
         int width = 0,                         //!< Width in 'typical' characters, 0 for default
         MGUI::LAYOUT_SIZEALIGN sizealign = MGUI::LAYOUT_SIZEALIGN_FixedSize,
         STYLE style = STYLE_Default
         ) {
         m_pContainer = pContainer;
         m_pfOnSelection = pfOnSelection;
         CTRL_COMBOBOX::Create(ParentPane,items,listheight,width,sizealign,style);
         }

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

      virtual void OnSelection (
         ) {
         CTRL_COMBOBOX::OnSelection();
         if (m_pContainer != 0) (m_pContainer->*m_pfOnSelection)();
         }
      #endif // GENERATING_DOXYGEN_OUTPUT
   };


//===================================================================================================================
//! Form containing label and Combobox control.
class FORM_COMBOBOX : public MGUI::FORM_COMPOSITE {
   public:

      //! Default constructor.
      FORM_COMBOBOX (
         );

      //! Destructor.
      virtual ~FORM_COMBOBOX (
         );

      //! Add single item with MISTRING or TEXTID.
      //! If control was created with STYLE_Sorted then the combo 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
         ) { return (m_combobox.AddItem(id,string,resize)); }

      //! Add single item with MIUNICODE* string.
      //! If control was created with STYLE_Sorted then the combo 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 MIUNICODE *string,                  //!< String to show in list
         bool resize = true                     //!< Attempt to resize if needed to fit new item string
         ) { return (m_combobox.AddItem(id,string,resize)); }

      //! Add single item with string from resource lookup.
      //! If control 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
         ) { return (m_combobox.AddItem(id,string,resize)); }

      //! 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
         ) { m_combobox.AddItems(items,resize); }

      //! Add items to combobox for unit selection.
      //! Item IDs will be equal to UnitIDs.
      void AddUnitItems (
         int UnitType,                          //!< Unit type
         int DftUnitID = 0                      //!< Default unit ID
         ) { m_combobox.AddUnitItems(UnitType,DftUnitID); }

      //! Create form with label from resource lookup.
      void Create (
         MGUI::LAYOUT_PANE_BASE& ParentPane,    //!< Parent pane
         const char* label,                     //!< Label string for resource lookup
         const MGUI::LISTITEMDEF *items = 0,    //!< Initial item set, 0 for none
         int listheight = 7,                    //!< Maximum list height when dropped down in characters
         int width = 0,                         //!< Width in 'typical' characters, 0 for default
         MGUI::LAYOUT_SIZEALIGN sizealign = MGUI::LAYOUT_SIZEALIGN_FixedSize,
         MGUI::CTRL_COMBOBOX::STYLE style = MGUI::CTRL_COMBOBOX::STYLE_Default,
         MGUI::CTRL_LABEL::STYLE labelstyle = MGUI::CTRL_LABEL::STYLE_LeftNoWrap
         );

      //! Create form with Unicode label.
      void Create (
         MGUI::LAYOUT_PANE_BASE& ParentPane,    //!< Parent pane
         const MISTRING& label,                 //!< Label string
         const MGUI::LISTITEMDEF *items = 0,    //!< Initial item set, 0 for none
         int listheight = 7,                    //!< Maximum list height when dropped down in characters
         int width = 0,                         //!< Width in 'typical' characters, 0 for default
         MGUI::LAYOUT_SIZEALIGN sizealign = MGUI::LAYOUT_SIZEALIGN_FixedSize,
         MGUI::CTRL_COMBOBOX::STYLE style = MGUI::CTRL_COMBOBOX::STYLE_Default,
         MGUI::CTRL_LABEL::STYLE labelstyle = MGUI::CTRL_LABEL::STYLE_LeftNoWrap
         );

      //! Delete all items from control.
      void DeleteAllItems (
         ) { m_combobox.DeleteAllItems(); }

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

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

      //! Get reference to CTRL_COMBOBOX in form.
      CTRL_COMBOBOX& GetComboBox (
         ) { return (m_combobox); }

      //! Get reference to CTRL_COMBOBOX in form.
      const CTRL_COMBOBOX& GetComboBox (
         ) const { return (m_combobox); }

      //! Retrieve number of items in the list.
      int GetCount (
         ) const { return (m_combobox.GetCount()); }

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

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

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

      //! Get label control if any.
      //! Usually the label control is only retrieved for alignment purposes.
      MGUI::CTRL_LABEL& GetLabel (
         ) { return (m_label); }

      //! Get currently selected item.
      //! @return Zero-based index of selected item or -1 if none selected.
      int GetSelectedItem (
         ) const { return (m_combobox.GetSelectedItem()); }

      //! Get ID of currently selected item.
      //! @return ID or -1 if item was not found or none selected.
      ID GetSelectedItemID (
         ) const { return (m_combobox.GetSelectedItemID()); }

      //! Insert item at specified position.
      //! 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 combo
         ) { return (m_combobox.InsertItem(index,id,string)); }

      //! Determine if specified item is selected.
      bool IsItemSelected (
         int index                           //!< Zero-based index of item
         ) const { return (m_combobox.IsItemSelected(index)); }

   #ifdef X_NATIVE
      //! Set whether control is enabled.
      virtual void SetEnabled (
         bool enabled = true
         );
   #endif

      //! Select item using zero-based index.
      //! If item is not visible the list will be scrolled to make it visible.
      void SetSelectedItem (
         int index                           //!< Zero-based index of item, -1 to have no item selected
         ) { m_combobox.SetSelectedItem(index); }

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

      //! Set whether items are to be sorted or not.
      void SetSorted (
         bool sorted = true
         ) { m_combobox.SetSorted(sorted); }

   protected:

      //! Called when user makes selection.
      //! Derived class must call corresponding base class method BEFORE performing its own processing.
      virtual void OnSelection ();

   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT

      MGUI::CTRL_COMBOBOX_T<FORM_COMBOBOX> m_combobox;
      MGUI::CTRL_LABEL m_label;

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


//-------------------------------------------------------------------------------------------------------------------
//! Convenience template for COMBOBOX control to allow method in container class to be called.
template <class _CT> class FORM_COMBOBOX_T : public MGUI::FORM_COMBOBOX {
   public:
      //! Constructor.
      explicit FORM_COMBOBOX_T (
         ): m_pContainer(0), m_pfOnSelection(0)
         { }

      //! Create form with label from resource lookup.
      void Create (
         MGUI::LAYOUT_PANE_BASE& ParentPane,    //!< Parent pane
         const char* label,                     //!< Label string for resource lookup
         _CT *pContainer,                       //!< Pointer to callback container class
         void (_CT::*pfOnSelection)(),          //! Callback function pointer
         const MGUI::LISTITEMDEF *items = 0,    //!< Initial item set, 0 for none
         int listheight = 7,                    //!< Maximum list height when dropped down in characters
         int width = 0,                         //!< Width in 'typical' characters, 0 for default
         MGUI::LAYOUT_SIZEALIGN sizealign = MGUI::LAYOUT_SIZEALIGN_FixedSize,
         MGUI::CTRL_COMBOBOX::STYLE style = MGUI::CTRL_COMBOBOX::STYLE_Default,
         MGUI::CTRL_LABEL::STYLE labelstyle = MGUI::CTRL_LABEL::STYLE_LeftNoWrap
         ) {
         m_pContainer = pContainer;
         m_pfOnSelection = pfOnSelection;
         FORM_COMBOBOX::Create(ParentPane,label,items,listheight,width,sizealign,style);
         }

      //! Create form with Unicode label.
      void Create (
         MGUI::LAYOUT_PANE_BASE& ParentPane,    //!< Parent pane
         const MISTRING& label,                 //!< Label string
         _CT *pContainer,                       //!< Pointer to callback container class
         void (_CT::*pfOnSelection)(),          //! Callback function pointer
         const MGUI::LISTITEMDEF *items = 0,    //!< Initial item set, 0 for none
         int listheight = 7,                    //!< Maximum list height when dropped down in characters
         int width = 0,                         //!< Width in 'typical' characters, 0 for default
         MGUI::LAYOUT_SIZEALIGN sizealign = MGUI::LAYOUT_SIZEALIGN_FixedSize,
         MGUI::CTRL_COMBOBOX::STYLE style = MGUI::CTRL_COMBOBOX::STYLE_Default,
         MGUI::CTRL_LABEL::STYLE labelstyle = MGUI::CTRL_LABEL::STYLE_LeftNoWrap
         ) {
         m_pContainer = pContainer;
         m_pfOnSelection = pfOnSelection;
         FORM_COMBOBOX::Create(ParentPane,label,items,listheight,width,sizealign,style);
         }

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

      virtual void OnSelection (
         ) {
         FORM_COMBOBOX::OnSelection();
         if (m_pContainer != 0) (m_pContainer->*m_pfOnSelection)();
         }
      #endif // GENERATING_DOXYGEN_OUTPUT
   };

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

}  // End namespace MGUI

#endif   // INC_MGUI_COMBOBOX_H

---