ctrl.h

Go to the documentation of this file.

/** 
 * \file mgui/ctrl.h
 * \brief Definitions for MGUI::CTRL classes.
 *
 * \if NODOC
 * $Id: ctrl.h_v 1.58 2004/10/13 22:18:04 mju Exp $
 *
 * $Log: ctrl.h_v $
 * Revision 1.58  2004/10/13 22:18:04  mju
 * Use mistring for labels instead of unicode*.
 *
 * Revision 1.57  2004/10/06 23:43:12  dfriberg
 * Fixed ordered list comment (doxygen)
 *
 * Revision 1.56  2004/10/04 15:26:23  mju
 * Use mistring in togglebutton_t.
 *
 * Revision 1.55  2004/08/19 13:46:08  mju
 * Change tooltipctrl to match base create fn to avoid annoying warnings.
 *
 * Revision 1.54  2004/07/27 13:42:09  mju
 * Add groupbox.setlabeltext.
 *
 * Revision 1.53  2004/07/26 15:10:45  mju
 * Add ability to specify width in pixels for text fields.
 *
 * Revision 1.52  2004/06/23 20:51:37  dwilliss
 * Added activate members to edit templates
 *
 * Revision 1.51  2004/05/28 21:43:47  mju
 * Change separator to take length and add create method using text.
 *
 * Revision 1.50  2004/04/08 21:23:19  mju
 * Change setfocus to v_setfocus.
 *
 * Revision 1.49  2004/03/30 17:26:10  vdronov
 * CTRL_SEPARATOR class added
 *
 * Revision 1.48  2004/03/15 17:45:57  dwilliss
 * Added a SetMaxLength() method to edit controls
 *
 * Revision 1.47  2003/12/18 13:43:44  mju
 * Simplify 'edit' templates by making ctor take pContainer and using SetFunc...
 *   methods to set functions.  This allows use of base Create() methods.
 * Add OnUserEdit for edit_number.
 *
 * Revision 1.46  2003/12/12 18:49:36  mju
 * Move 'selection' methods to edit_base.
 * Add set/clear selection methods to ctrl_text.
 *
 * Revision 1.45  2003/12/12 15:30:23  mju
 * Change CB_valuechanged parm.
 *
 * Revision 1.44  2003/12/11 20:57:27  mju
 * Need OnUserEdit in FORM_EDIT_STRING.
 *
 * Revision 1.43  2003/12/11 18:38:58  mju
 * Add OnUserEdit for form_edit_string too.
 *
 * Revision 1.42  2003/12/11 18:27:10  mju
 * Don't call pfOnUserEdit if null.
 *
 * Revision 1.41  2003/12/11 15:40:06  mju
 * For edit controls make base overridables private as don't need to call from derived.
 *
 * Revision 1.40  2003/11/14 16:14:21  dwilliss
 * Added MISTRING versions of label create and set methods to allow TEXTIDs
 * Should deprecate the plain UNICODE versions?  Not sure, leave `em for now.
 *
 * Revision 1.39  2003/11/03 18:47:53  mju
 * Make edit::getValue methods non-inline and non-const so can update to lateset edits.
 *
 * Revision 1.38  2003/10/27 16:16:06  mju
 * For 'edit' controls, move Get/SetModify to base and implement for X also.
 *
 * Revision 1.37  2003/10/02 16:19:23  linux32build!build
 * Doxygen fix
 *
 * Revision 1.36  2003/10/01 22:32:38  dwilliss
 * doxygen
 *
 * Revision 1.35  2003/09/15 13:49:32  fileserver!dwilliss
 * Doxygen
 *
 * Revision 1.34  2003/08/19 22:39:21  msmith
 * CTRL_LABEL for MFC now does multiline text and icons.
 *
 * Revision 1.33  2003/08/01 16:54:03  scowan
 * Added ctrl label create icon methods.
 *
 * Revision 1.32  2003/06/30 15:01:52  scowan
 * Moved ctrl text clear method from an inline.
 *
 * Revision 1.31  2003/04/15 16:42:32  mju
 * Include rect.h.
 *
 * Revision 1.30  2003/04/09 20:48:09  dwilliss
 * Don't use _T in templates.  Mac's ctype.h defines a global _T
 *
 * Revision 1.29  2003/01/27 18:54:19  mju
 * Move POINT defn to layout.h.
 *
 * Revision 1.28  2003/01/16 21:35:11  mju
 * Move listbox/combobox hdrs to end as need ctrl first.
 *
 * Revision 1.27  2003/01/16 21:13:10  mju
 * Move listbox/combobox defns to own headers.
 *
 * Revision 1.24  2002/12/02 17:13:19  mju
 * Add GetBackgroundColor.
 *
 * Revision 1.23  2002/11/18 21:54:05  mju
 * Add listbox X callbacks.
 *
 * Revision 1.22  2002/10/14 19:16:31  mju
 * Only define togglebutton::style_RadioFirst for MFC.
 *
 * Revision 1.21  2002/10/11 19:40:34  dwilliss
 * Get rid of KEYSTATE_Alt
 *
 * Revision 1.20  2002/10/11 16:14:51  mju
 * Change CTRL to have pointer instead of reference to actual control for MFC.
 * This allows the definition of the MFC control to be in the implementation module.
 *
 * Revision 1.19  2002/10/11 14:49:18  dwilliss
 * Moved the KEYSTATE enum to here
 *
 * Revision 1.18  2002/10/09 16:51:18  mju
 * Forward declare TEXTSTYLE.
 *
 * Revision 1.17  2002/10/09 15:33:21  mju
 * Moved to 'mgui' folder.
 *
 * Revision 1.16  2002/10/09 15:26:17  dwilliss
 * Added some methods and a flag to CTRL_TEXT
 *
 * Revision 1.15  2002/09/17 17:13:03  scowan
 * Removed mgui namespace qualifier on a ctor declaration.
 *
 * Revision 1.13  2002/08/09 13:29:57  mju
 * Add const getcombobox method.
 *
 * Revision 1.12  2002/07/09 15:39:58  dwilliss
 * Added an InvalidateRect method to match the MFC one
 *
 * Revision 1.11  2002/06/06 20:56:44  mju
 * Don't inline combo/listbox methods.
 *
 * Revision 1.9  2002/01/03 15:10:16  mju
 * Allow GROUPBOX cast to PANE in X too.
 *
 * Revision 1.8  2001/12/19 21:01:05  mju
 * Change comments for OnPressed regarding base class method.
 *
 * Revision 1.7  2001/12/18 23:07:58  mju
 * Add listheight for X ComboBox so will remember preferred size.
 *
 * Revision 1.6  2001/12/18 18:25:01  mju
 * Add FORM_EDIT_STRING::ClearValue().
 *
 * Revision 1.4  2001/12/14 18:52:11  mju
 * ICONID is now an enum.
 *
 * Revision 1.3  2001/12/13 17:00:05  mju
 * MGUI unification with X.
 *
 * Revision 1.2  2001/12/05 21:55:27  mju
 * Include MFC header when building for such.
 *
 * Revision 1.1  2001/12/03 17:38:38  mju
 * Initial revision
 * \endif
**/

#ifndef  INC_MGUI_CTRL_H
#define  INC_MGUI_CTRL_H

#ifndef INC_MGUI_FORM_H
#include <mgui/form.h>
#endif

#ifndef  INC_MI32_RANGE_H
#include <mi32/range.h>
#endif

#ifndef  INC_MI32_RECT_H
#include <mi32/rect.h>
#endif

#ifndef  INC_MI32_LATLONFM_H
#include <mi32/latlonfm.h>
#endif

#ifndef  INC_MI32_UNITCONV_H
#include <mi32/unitconv.h>
#endif

#ifndef  INC_MI32_SIMPLEAR_H
#include <mi32/simplear.h>
#endif

#ifndef  INC_MI32_ICONID_H
#include <mi32/iconid.h>
#endif

struct TEXTSTYLE;

namespace MGUI {


//===================================================================================================================
//! Enum used to specify which keys are pressed during a message handler.
//! NOTE:  These are exactly equivilant to some Windows constants.
//! The Alt KEYSTATE is not here because there is no mask for it in X
enum KEYSTATE {
   KEYSTATE_None     = 0x0000,
   KEYSTATE_Ctrl     = 0x0002,
   KEYSTATE_Control  = 0x0002,
   KEYSTATE_Shift    = 0x0004
   };

DEFINE_ENUM_OP_BITWISE(MGUI::KEYSTATE);

//===================================================================================================================
//! Base class for "single" graphical user interface controls.
//!
//! There are two basic types of 'controls' which can be used in user interface implementation,
//! controls which the user can interact with and 'static' controls which the user cannot change
//! directly.
//!
//! All controls which the user can manipulate also encapsulate information about the current
//! 'state' of the control (except for MGUI::CTRL_PUSHBUTTON as explained below).  There are three ways
//! to use each of these controls in a program (in order of convenience):
//!
//!      -# If changing the state of a control has no other immediate effect then the control class
//!         may be used directly and the state information retrieved when needed, such as when the
//!         user presses 'OK' on the dialog.  This option is not available for MGUI::CTRL_PUSHBUTTON as
//!         pressing a button must always have some other affect and MGUI::CTRL_PUSHBUTTON contains no
//!         'state' information.
//!      -# Use the template version of the control and specify a callback 'container' and callback
//!         method pointer for the control.  This allows the callback to be a method of the 'container'
//!         class (usually the dialog, page or main window) thus allowing access to other controls in
//!         the container.  This is similar to MFC message maps and avoids the common need to include
//!         a reference or pointer to the container in a subclass.  Templates for controls with a
//!         single On... virtual method will generally include the container and method pointer as
//!         parameters to the Create() methods.  Templates for controls with multiple On... virtual
//!         methods will generally have a SetFunc... method for each corresponding On... virtual
//!         method in their base class and will not override the Create() methods.
//!      -# Inherit from the control class and override the On... virtual method to perform task
//!         specific processing.  This is simplest if no reference to the containing dialog or
//!         window is necessary.  Also for some control types, the template version itself may be
//!         inherited from to override other virtual methods, such as MGUI::CTRL_EDIT_... validation
//!         methods.
//!
class CTRL : public MGUI::FORM {
   public:

      //! Destructor.
      virtual ~CTRL (
         ) = 0;

      //! Get interface 'background' color.
      static const COLOR& GetBackgroundColor (
         );

   #ifdef WIN32_MFC
      //! Get "client rectangle" for the primary control window (MFC only).
      void GetClientRect (
         LPRECT lpRect
         ) const { m_pWnd->GetClientRect(lpRect); }
   #endif

   #ifdef WIN32_MFC
      //! Get the CWnd of the primary control (MFC only).
      CWnd* GetCWnd (
         ) { return (m_pWnd); }
   #endif

   #ifdef X_NATIVE
      //! Get the Widget for the control or container if multiple controls (X only).
      //! The widget should only be used for attachment, do not assume the
      //! widget is of a particular type.
      Widget GetWidget (
         ) { return (m_widget); }
   #endif

   #ifdef WIN32_MFC
      //! Invalidate the entire client area (MFC only).
      //! This will force it to redraw the next WM_PAINT message occurs.
      void Invalidate (
         bool erase = true
         ) { m_pWnd->Invalidate(erase); }
   #endif

   #ifdef WIN32_MFC
      //! Invalidate a rectangle in the client area (MFC only).
      //! This will force it to redraw the next WM_PAINT message occurs.
      void InvalidateRect (
         const LRECT2D& lrect,
         bool erase = true
         ) { 
         CRect rect(lrect.xinit, lrect.yinit, lrect.xlast, lrect.ylast);
         m_pWnd->InvalidateRect(rect, erase); 
         }
   #endif

      //! Determine if control has been created.
      //! @return true if created, false if not.
      virtual bool IsCreated (
         ) const;

      //! Determine if control is enabled for keyboard or mouse input.
      //! @return true if enabled, false if not, or if not yet created.
      virtual bool IsEnabled (
         ) const;

   #ifdef WIN32_MFC
      //! Called to process messages before translation (MFC only).
      //! Allows a control to trap messages before they get passed.  Should return
      //! 'true' if the message was translated and should not be dispatched or
      //! 'false' if the message was not handled and should be dispatched.
      //! The control must also be added to the root layout's pretranslation list via
      //! MGUI::LAYOUT_PANE_BASE::PreTransListAddCtrl().  This should be done in the
      //! control's Create() method.
      virtual bool PreTranslateMessageHook (
         MSG *pMsg
         ) { return (false); }
   #endif

      //! Set whether mouse or keyboard input to control is allowed.
      virtual void SetEnabled (
         bool enabled = true
         );

   #ifdef WIN32_MFC
      //! Allow the window to be redrawn (MFC only).
      void SetRedraw (
         bool redraw = true
         ) { m_pWnd->SetRedraw(redraw); }
   #endif

      //! Set whether control is visible or not.
      virtual void SetVisible (
         bool visible = true
         );

   #ifdef WIN32_MFC
      //! Generate a WM_PAINT message if the window needs to be updated
      void UpdateWindow (
         ) { m_pWnd->UpdateWindow(); }
   #endif

   protected:

   #ifdef WIN32_MFC
      CWnd *m_pWnd;           //!< Pointer to actual control in derived class

      //! Constructor (MFC version).
      CTRL (
         CWnd& wnd
         ): m_pWnd(&wnd) { }

      CTRL (
         CWnd *pWnd
         ): m_pWnd(pWnd) { }

   #endif

   #ifdef X_NATIVE
      Widget m_widget;

      //! Constructor (X version).
      CTRL (
         ): m_widget(0) { }

      //! Add 'Destroy' callback for widget.
      void AddDestroyCallback (
         );

      //! Called if widgets are destroyed before CTRL class instance.
      //! Will not be called if CTRL class instance is destroyed before widgets.
      //! Usually just sets widgets to NULL so won't be referenced in destructor.
      //! Derived class must call corresponding base class method AFTER performing its own processing.
      virtual void OnDestroy (
         );
   #endif

   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT

   #ifdef X_NATIVE
      static void CB_Destroy (Widget, CTRL*, void*);
   #endif

      // MGUI::FORM overrides.
      virtual void v_SetFocus () const;

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


//===================================================================================================================
//! Non-editable label control.
class CTRL_LABEL : public MGUI::CTRL {
   public:

      enum STYLE {
         STYLE_LeftNoWrap,                      //!< Left-justify text without word wrapping
         STYLE_Left,                            //!< Left-justify, MFC may word-wrap if too long
         STYLE_Center,                          //!< Center, MFC may word-wrap if too long
         STYLE_Right                            //!< Right-justify, MFC may word-wrap if too long
         };

      //! Constructor.
      CTRL_LABEL (
         )
      #ifdef WIN32_MFC
         :
         m_icon(0),
         CTRL(m_ctrl)
      #endif
         { }

      ~CTRL_LABEL (
         );

      //! Create control with label from resource lookup.
      void Create (
         MGUI::LAYOUT_PANE_BASE& ParentPane,    //!< Parent pane
         const char* label,                     //!< Label string for resource lookup
         MGUI::LAYOUT_SIZEALIGN sizealign = MGUI::LAYOUT_SIZEALIGN_FixedSize,
         STYLE style = STYLE_LeftNoWrap
         );

      //! Create control with MISTRING or TEXTID label.
      void Create (
         MGUI::LAYOUT_PANE_BASE& ParentPane,    //!< Parent pane
         const MISTRING& label,                 //!< Label string (allows TEXTID)
         MGUI::LAYOUT_SIZEALIGN sizealign = MGUI::LAYOUT_SIZEALIGN_FixedSize,
         STYLE style = STYLE_LeftNoWrap
         );

      //! Create control with ICONID
      void Create (
         MGUI::LAYOUT_PANE_BASE& ParentPane,    //!< Parent pane
         ICONID iconid,                         //!< ICON to use as the label
         const char *tooltip,
         int iconsize = 0
         );

      //! Create control with ICONID with MISTRING or TEXTID tooltip
      void Create (
         MGUI::LAYOUT_PANE_BASE& ParentPane,    //!< Parent pane
         ICONID iconid,                         //!< ICON to use as the label
         const MISTRING& tooltip,               //!< tooltip string (allows TEXTID)
         int iconsize = 0
         );

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

      //! Set new label from resource lookup.
      void SetLabel (
         const char *string
         );

      //! Set new label from Unicode string.
      void SetLabel (
         const MISTRING& string
         );

   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT

   #ifdef WIN32_MFC
      CStatic m_ctrl;
      HICON m_icon;

      void CreateIconWin (
         MGUI::LAYOUT_PANE_BASE& ParentPane,
         ICONID iconid,
         const CString& label,
         int iconsize
         );

      void CreateWin (
         MGUI::LAYOUT_PANE_BASE& ParentPane,
         const CString& label,
         MGUI::LAYOUT_SIZEALIGN sizealign,
         STYLE style
         );
   #endif

   #ifdef X_NATIVE
      bool CreateIcon (
         MGUI::LAYOUT_PANE_BASE& ParentPane,
         ICONID iconid,
         const char *name,
         int iconsize
         );

      void CreateX (
         MGUI::LAYOUT_PANE_BASE& ParentPane,
         XTARGS& args,
         const char *name,
         MGUI::LAYOUT_SIZEALIGN sizealign,
         STYLE style
         );
   #endif

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


//===================================================================================================================
//!   Group Box control, equivalent to XmFrame.
class CTRL_GROUPBOX : public MGUI::CTRL {
   public:

      //! Constructor.
      CTRL_GROUPBOX (
         );

      //! Destructor.
      virtual ~CTRL_GROUPBOX (
         );

      //! Cast to MGUI::LAYOUT_PANE_BASE& for use as parent to other controls.
      operator MGUI::LAYOUT_PANE_BASE& (
         ) { return (m_GroupBoxPane); }

      //! Create control with no label.
      void Create (
         MGUI::LAYOUT_PANE_BASE& ParentPane, //!< Parent pane
         MGUI::LAYOUT_ORIENTATION orientation = MGUI::LAYOUT_ORIENTATION_Vertical,
         MGUI::LAYOUT_SIZEALIGN sizealign = MGUI::LAYOUT_SIZEALIGN_FixedSize,
         int ChildSpacing = 4,               //!< Spacing between children of group box
         int ExtraBorder = 0                 //!< Extra border around inside of group box, in addition to ChildSpacing
         );

      //! Create control with label from resource lookup.
      void Create (
         MGUI::LAYOUT_PANE_BASE& ParentPane, //!< Parent pane
         const char* string,                 //!< Label string for resource lookup
         MGUI::LAYOUT_ORIENTATION orientation = MGUI::LAYOUT_ORIENTATION_Vertical,
         MGUI::LAYOUT_SIZEALIGN sizealign = MGUI::LAYOUT_SIZEALIGN_FixedSize,
         int ChildSpacing = 4,               //!< Spacing between children of group box
         int ExtraBorder = 0                 //!< Extra border around inside of group box, in addition to ChildSpacing
         );

      //! Create control with Unicode label.
      void Create (
         MGUI::LAYOUT_PANE_BASE& ParentPane, //!< Parent pane
         const MISTRING& string,             //!< Label string
         MGUI::LAYOUT_ORIENTATION orientation = MGUI::LAYOUT_ORIENTATION_Vertical,
         MGUI::LAYOUT_SIZEALIGN sizealign = MGUI::LAYOUT_SIZEALIGN_FixedSize,
         int ChildSpacing = 4,               //!< Spacing between children of group box
         int ExtraBorder = 0                 //!< Extra border around inside of group box, in addition to ChildSpacing
         );

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

      //! Get layout pane to invoke options on it.
      MGUI::LAYOUT_PANE_BASE& GetPane (
         ) { return (m_GroupBoxPane); }

      void SetLabelText (
         const MISTRING& label
         );

   private:

      #ifndef GENERATING_DOXYGEN_OUTPUT
      class LAYOUT_PANE : public MGUI::LAYOUT_PANE_BASE {
         public:
            LAYOUT_PANE (
               ) { }
            virtual ~LAYOUT_PANE (
               ) { }
            void Create (
               #ifdef WIN32_MFC
               MGUI::LAYOUT_PANE_BASE& ParentPane,
               CButton& ctrl,
               #else
               Widget FrameWidget,
               #endif
               MGUI::LAYOUT_ORIENTATION orientation,
               MGUI::LAYOUT_SIZEALIGN sizealign,
               int ChildSpacing,
               int ExtraBorder,
               int TopExtra
               );
         private:
            LAYOUT_PANE (const LAYOUT_PANE&);
            LAYOUT_PANE& operator= (const LAYOUT_PANE&);
         };

      LAYOUT_PANE m_GroupBoxPane;

   #ifdef WIN32_MFC
      CButton m_ctrl;

      void CreateWin (
         MGUI::LAYOUT_PANE_BASE& ParentPane,
         const CString& label,
         MGUI::LAYOUT_ORIENTATION orientation,
         MGUI::LAYOUT_SIZEALIGN sizealign,
         int ChildSpacing,
         int ExtraBorder
         );
   #endif   // WIN32_MFC

   #ifdef X_NATIVE
      Widget m_label;
      void CreateX (
         MGUI::LAYOUT_PANE_BASE& ParentPane,
         MGUI::LAYOUT_ORIENTATION orientation,
         MGUI::LAYOUT_SIZEALIGN sizealign,
         int ChildSpacing,
         int ExtraBorder
         );
   #endif

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


//===================================================================================================================
//! PushButton control supporting both text and icon buttons.
class CTRL_PUSHBUTTON : public MGUI::CTRL {
   public:

      //! Constructor.
      CTRL_PUSHBUTTON (
         )
      #ifdef WIN32_MFC
         : CTRL(m_ctrl), m_ctrl(*this), m_hIcon(0)
      #endif
         { }

      //! Destructor.
      virtual ~CTRL_PUSHBUTTON (
         );

      //! Create control with label from resource lookup.
      void Create (
         MGUI::LAYOUT_PANE_BASE& ParentPane,    //!< Parent pane
         const char* label,                     //!< Label string for resource lookup
         bool large = false,                    //!< Create large buttons (for dialogs)
         MGUI::LAYOUT_SIZEALIGN sizealign = MGUI::LAYOUT_SIZEALIGN_FixedSize
         );

      //! Create control with Unicode label.
      void Create (
         MGUI::LAYOUT_PANE_BASE& ParentPane,    //!< Parent pane
         const MISTRING& label,                 //!< Label string
         bool large = false,                    //!< Create large buttons (for dialogs)
         MGUI::LAYOUT_SIZEALIGN sizealign = MGUI::LAYOUT_SIZEALIGN_FixedSize
         );

      //! Create control with icon and ToolTip from resource lookup.
      void Create (
         MGUI::LAYOUT_PANE_BASE& ParentPane,    //!< Parent pane
         ICONID iconid,                         //!< Icon ID
         const char* tooltip,                   //!< ToolTip string for resource lookup
         int iconsize = 0                       //!< Icon size, 0 for default
         );

      //! Create control with icon and ToolTip from resource lookup.
      void Create (
         MGUI::LAYOUT_PANE_BASE& ParentPane,    //!< Parent pane
         ICONID iconid,                         //!< Icon ID
         const MISTRING& tooltip,               //!< ToolTip string
         int iconsize = 0                       //!< Icon size, 0 for default
         );

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

   protected:

      //! Called when button is pushed.
      virtual void OnPressed (
         ) = 0;

   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT

   #ifdef WIN32_MFC
      class MyButton : public CButton {
         public:
            MyButton (
               CTRL_PUSHBUTTON& guictrl
               ): m_guictrl(guictrl)
               { }
         protected:
            afx_msg void OnClicked ();
            DECLARE_MESSAGE_MAP()
         private:
            CTRL_PUSHBUTTON& m_guictrl;
         friend class MGUI::CTRL_PUSHBUTTON;
         };
      friend class MyButton;

      MyButton m_ctrl;
      HICON m_hIcon;
   #endif   // WIN32_MFC

   #ifdef X_NATIVE
      static void CB_PushButton (Widget, CTRL_PUSHBUTTON*, void*);

      bool CreateIcon (
         LAYOUT_PANE_BASE& ParentPane,
         ICONID iconid,
         const char *name,
         int iconsize
         );

      void CreateWidget (
         LAYOUT_PANE_BASE& ParentPane,
         XTARGS& args,
         const char *name,
         bool large = false
         );
   #endif   // X_NATIVE

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


//-------------------------------------------------------------------------------------------------------------------
//! Convenience template for PushButton control to allow method in container class to be called.
//! This template allows a method in a 'container' class to be called when the button is pressed,
//! rather than requiring that a subclass be defined with the OnPressed() virtual method overridden.
template <class _CT> class CTRL_PUSHBUTTON_T : public MGUI::CTRL_PUSHBUTTON {
   public:

      //! Constructor.
      explicit CTRL_PUSHBUTTON_T (
         ): m_pContainer(0), m_pfOnPressed(0) { }

      //! Create control 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::*pfOnPressed)(),            //! Callback function pointer
         bool large = false,                    //!< Create large buttons (for dialogs)
         MGUI::LAYOUT_SIZEALIGN sizealign = MGUI::LAYOUT_SIZEALIGN_FixedSize
         ) {
         m_pContainer = pContainer;
         m_pfOnPressed = pfOnPressed;
         CTRL_PUSHBUTTON::Create(ParentPane,label,large,sizealign);
         }

      //! Create control 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::*pfOnPressed)(),            //! Callback function pointer
         bool large = false,                    //!< Create large buttons (for dialogs)
         MGUI::LAYOUT_SIZEALIGN sizealign = MGUI::LAYOUT_SIZEALIGN_FixedSize
         ) {
         m_pContainer = pContainer;
         m_pfOnPressed = pfOnPressed;
         CTRL_PUSHBUTTON::Create(ParentPane,label,large,sizealign);
         }

      //! Create control with icon and ToolTip from resource lookup.
      void Create (
         MGUI::LAYOUT_PANE_BASE& ParentPane,    //!< Parent pane
         ICONID iconid,                         //!< Icon ID
         const char* tooltip,                   //!< ToolTip string for resource lookup
         _CT *pContainer,                       //!< Pointer to callback container class
         void (_CT::*pfOnPressed)(),               //! Callback function pointer
         int iconsize = 0                       //!< Icon size, 0 for default
         ) {
         m_pContainer = pContainer;
         m_pfOnPressed = pfOnPressed;
         CTRL_PUSHBUTTON::Create(ParentPane,iconid,tooltip,iconsize);
         }

      //! Create control with icon and ToolTip from resource lookup.
      void Create (
         MGUI::LAYOUT_PANE_BASE& ParentPane,    //!< Parent pane
         ICONID iconid,                         //!< Icon ID
         const MISTRING& tooltip,               //!< ToolTip string
         _CT *pContainer,                       //!< Pointer to callback container class
         void (_CT::*pfOnPressed)(),            //! Callback function pointer
         int iconsize = 0                       //!< Icon size, 0 for default
         ) {
         m_pContainer = pContainer;
         m_pfOnPressed = pfOnPressed;
         CTRL_PUSHBUTTON::Create(ParentPane,iconid,tooltip,iconsize);
         }

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

      virtual void OnPressed (
         ) { (m_pContainer->*m_pfOnPressed)(); }
      #endif // GENERATING_DOXYGEN_OUTPUT
   };


//===================================================================================================================
//! Toggle button control supporting both "checkbox" and "radio" behavior with text and icon buttons.
//! Note that in the X version radio behavior between buttons is NOT enforced by this control.  For
//! portability it is recommended that the MGUI::FORM_RADIOBUTTONS class be used to manage a set of
//! radio buttons or that the code enforce radio behavior itself for more complex cases.
class CTRL_TOGGLEBUTTON : public MGUI::CTRL {
   public:

      enum STYLE {
         STYLE_Check,                           //!< Checkbox style
         STYLE_Radio,                           //!< Radiobutton style
   #ifdef WIN32_MFC
         STYLE_RadioFirst                       //!< Radiobutton style, first in radio group (MFC only)
   #endif
         };

      //! Constructor.
      CTRL_TOGGLEBUTTON (
         )
      #ifdef WIN32_MFC
         : CTRL(m_ctrl), m_ctrl(*this), m_hIcon(0)
      #endif
         { }

      //! Destructor.
      virtual ~CTRL_TOGGLEBUTTON (
         );

      //! Create with label from resource lookup.
      void Create (
         MGUI::LAYOUT_PANE_BASE& ParentPane,    //!< Parent pane
         const char* label,                     //!< Label string for resource lookup
         STYLE style = STYLE_Check,             //!< Toggle style
         bool dftvalue = false,                 //!< Default value
         MGUI::LAYOUT_SIZEALIGN sizealign = MGUI::LAYOUT_SIZEALIGN_FixedSize
         );

      //! Create with Unicode label.
      void Create (
         MGUI::LAYOUT_PANE_BASE& ParentPane,    //!< Parent pane
         const MISTRING& label,                 //!< Label string
         STYLE style = STYLE_Check,             //!< Toggle style
         bool dftvalue = false,                 //!< Default value
         MGUI::LAYOUT_SIZEALIGN sizealign = MGUI::LAYOUT_SIZEALIGN_FixedSize
         );

      //! Create icon togglebutton with ToolTip from resource lookup.
      void Create (
         MGUI::LAYOUT_PANE_BASE& ParentPane,    //!< Parent pane
         ICONID iconid,                         //!< Icon ID
         const char* tooltip,                   //!< ToolTip string
         STYLE style = STYLE_Check,             //!< Toggle style
         bool dftvalue = false,                 //!< Default value
         int iconsize = 0                       //!< Icon size, 0 for default
         );

      //! Create icon togglebutton with Unicode ToolTip.
      void Create (
         MGUI::LAYOUT_PANE_BASE& ParentPane,    //!< Parent pane
         ICONID iconid,                         //!< Icon ID
         const MISTRING& tooltip,                  //!< ToolTip string
         STYLE style = STYLE_Check,             //!< Toggle style
         bool dftvalue = false,                 //!< Default value
         int iconsize = 0                       //!< Icon size, 0 for default
         );

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

      //! Get current toggle setting.
      //! Returns 'false' if control not yet created.
      bool GetValue (
         ) const;

      //! Set control value.
      //! Method has no effect if control has not yet been created.
      void SetValue (
         bool value,                            //!< Value to set
         bool notify = true                     //!< If true call OnChangeValue() if value changed
         );

   protected:

      //! Called when button is pushed.
      virtual void OnPressed (
         );

   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT

   #ifdef WIN32_MFC
      class MyButton : public CButton {
         public:
            MyButton (
               CTRL_TOGGLEBUTTON& guictrl
               ): m_guictrl(guictrl)
               { }
         protected:
            afx_msg void OnClicked ();
            DECLARE_MESSAGE_MAP()
         private:
            CTRL_TOGGLEBUTTON& m_guictrl;
         friend class MGUI::CTRL_TOGGLEBUTTON;
         };
      friend class MyButton;

      MyButton m_ctrl;
      HICON m_hIcon;
   #endif   // WIN32_MFC

   #ifdef X_NATIVE
      static void CB_ToggleButton (Widget, CTRL_TOGGLEBUTTON*, void*);

      bool CreateIcon (
         MGUI::LAYOUT_PANE_BASE& ParentPane,
         ICONID iconid,
         const char *name,
         STYLE style,
         bool dftvalue,
         int iconsize
         );

      void CreateWidget (
         MGUI::LAYOUT_PANE_BASE& ParentPane,
         XTARGS& args,
         const char* label,
         STYLE style,
         bool dftvalue
         );
   #endif   // X_NATIVE

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


//-------------------------------------------------------------------------------------------------------------------
//! Convenience template for Toggle button to allow method in container class to be called.
template <class _CT> class CTRL_TOGGLEBUTTON_T : public MGUI::CTRL_TOGGLEBUTTON {
   public:

      //! Constructor.
      explicit CTRL_TOGGLEBUTTON_T (
         ): m_pContainer(0), m_pfOnPressed(0) { }

      //! Create 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::*pfOnPressed)(),               //! Callback function pointer
         STYLE style = STYLE_Check,             //!< Toggle style
         bool dftvalue = false,                 //!< Default value
         MGUI::LAYOUT_SIZEALIGN sizealign = MGUI::LAYOUT_SIZEALIGN_FixedSize
         ) {
         m_pContainer = pContainer;
         m_pfOnPressed = pfOnPressed;
         CTRL_TOGGLEBUTTON::Create(ParentPane,label,style,dftvalue,sizealign);
         }

      //! Create 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::*pfOnPressed)(),               //! Callback function pointer
         STYLE style = STYLE_Check,             //!< Toggle style
         bool dftvalue = false,                 //!< Default value
         MGUI::LAYOUT_SIZEALIGN sizealign = MGUI::LAYOUT_SIZEALIGN_FixedSize
         ) {
         m_pContainer = pContainer;
         m_pfOnPressed = pfOnPressed;
         CTRL_TOGGLEBUTTON::Create(ParentPane,label,style,dftvalue,sizealign);
         }

      //! Create icon with ToolTip from resource lookup.
      void Create (
         MGUI::LAYOUT_PANE_BASE& ParentPane,    //!< Parent pane
         ICONID iconid,                         //!< Icon ID
         const char* tooltip,                   //!< ToolTip string
         _CT *pContainer,                       //!< Pointer to callback container class
         void (_CT::*pfOnPressed)(),               //! Callback function pointer
         STYLE style = STYLE_Check,             //!< Toggle style
         bool dftvalue = false,                 //!< Default value
         int iconsize = 0                       //!< Icon size, 0 for default
         ) {
         m_pContainer = pContainer;
         m_pfOnPressed = pfOnPressed;
         CTRL_TOGGLEBUTTON::Create(ParentPane,iconid,tooltip,style,dftvalue,iconsize);
         }

      //! Create icon with Unicode ToolTip.
      void Create (
         MGUI::LAYOUT_PANE_BASE& ParentPane,    //!< Parent pane
         ICONID iconid,                         //!< Icon ID
         const MISTRING& tooltip,                  //!< ToolTip string
         _CT *pContainer,                       //!< Pointer to callback container class
         void (_CT::*pfOnPressed)(),               //! Callback function pointer
         STYLE style = STYLE_Check,             //!< Toggle style
         bool dftvalue = false,                 //!< Default value
         int iconsize = 0                       //!< Icon size, 0 for default
         ) {
         m_pContainer = pContainer;
         m_pfOnPressed = pfOnPressed;
         CTRL_TOGGLEBUTTON::Create(ParentPane,iconid,tooltip,style,dftvalue,iconsize);
         }

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

      virtual void OnPressed (
         ) { (m_pContainer->*m_pfOnPressed)(); }
      #endif // GENERATING_DOXYGEN_OUTPUT
   };


//===================================================================================================================
//! Base class for 'edit' controls.
class CTRL_EDIT_BASE : public MGUI::CTRL {
   public:

      //! Constructor.
      CTRL_EDIT_BASE (
         );

      //! Destructor.
      ~CTRL_EDIT_BASE (
         );

      //! Clear the current selection
      void ClearSelection (
         )
      #ifdef WIN32_MFC
         { m_ctrl.Clear(); }
      #endif
         ;

      //! Copy the current selection to the clipboard
      void CopySelection (
         )
      #ifdef WIN32_MFC
         { m_ctrl.Copy(); }
      #endif
         ;

      //! Cut the current selection to the clipboard
      void CutSelection (
         )
      #ifdef WIN32_MFC
         { m_ctrl.Cut(); }
      #endif
         ;

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

      //! Returns true if contents of the edit-control have been modified by user, false if not.
      //! Use SetModify() to reset.
      const bool GetModify (
         ) const {
      #ifdef WIN32_MFC
         return (m_ctrl.GetModify() != FALSE);
      #else
         return (m_UserEdited);
      #endif
         }

      //! Get the current selection of the edit control.
      //!   If nStartChar == nEndChar, nothing is selected.
      void GetSelection (
         int& nStartChar,     //!< Receives the first character in the current selection
         int& nEndChar        //!< Receives the first non-selected character past the end of the current selection
         ) const
      #ifdef WIN32_MFC
         { m_ctrl.GetSel(nStartChar,nEndChar); }
      #endif
         ;

      //! Set the maximim text length in characters
      void SetMaxLength (
         int length
         );

      //! Set or clear the "modified" state of the edit control.
      void SetModify (
         bool modified = true
         ) {
      #ifdef WIN32_MFC
         m_ctrl.SetModify(modified);
      #else
         m_UserEdited = modified;
      #endif
         }

      //! Set whether value is read-only or not.
      void SetReadOnly (
         bool ReadOnly = true                //!< True if read only, false if not
         ) {
      #ifdef WIN32_MFC
         m_ctrl.SetReadOnly(ReadOnly);
      #else
         MxSetTextEditable(m_widget,!ReadOnly);
      #endif
         }

      //! Select range of characters in string.
      void SetSelection (
         int StartChar = 0,                  //!< Starting character position in string, 0 for beginning
         int EndChar = -1,                   //!< Ending character position, -1 for end of string
         bool NoScroll = true                //!< Indicates whether to scroll caret into view
         )
      #ifdef WIN32_MFC
         { m_ctrl.SetSel(StartChar,EndChar,NoScroll); }
      #endif
         ;

      //! Set set of 'valid' or 'invalid' characters.
      //! This does not alter the current contents, if any.
      void SetValidChars (
         const UNICODE* string,              //!< Characters valid or invalid to enter
         bool invert = false                 //!< Allow all but specified characters
         );

   protected:

   #ifdef WIN32_MFC
      class MyEdit : public CEdit {
         public:
            MyEdit (
               CTRL_EDIT_BASE& guictrl
               ): m_guictrl(guictrl)
               { }
            virtual ~MyEdit (
               ) { }
            virtual BOOL PreCreateWindow (CREATESTRUCT& cs);
         protected:
            afx_msg void OnChange ();
            afx_msg void OnKillFocus ();
            DECLARE_MESSAGE_MAP()
         private:
            #ifndef GENERATING_DOXYGEN_OUTPUT
            CTRL_EDIT_BASE& m_guictrl;
            #endif // GENERATING_DOXYGEN_OUTPUT
         };
      friend class MyEdit;
      MyEdit m_ctrl;
   #endif

   #ifdef X_NATIVE
      bool m_UserEdited;
   #endif
      bool m_HasValue;

      //! Check that all characters in string are in valid set.
      //!   @return 'true' if valid, 'false' if not
      bool CheckValidChars (
         MISTRING& string                       //!< String to be checked
         ) const;

      void CreateCtrl (
         LAYOUT_PANE_BASE& ParentPane,
         int width,                             //!< Width in 'typical' characters
         int height,                            //!< Height in text lines, 0 for single-line edit
         bool RightJustify,
         bool ReadOnly,
         bool Opaque,
         bool WidthInPixels,
         LAYOUT_SIZEALIGN sizealign
         );

      bool GetEditStr (
         MISTRING& str
         ) const;

      // Send value change notification via OnChangeValue.
      void NotifyChanged (
         ) { OnChangeValue(); }

      //! Called internally to update text control from specified string.
      void UpdateCtrl (
         const MISTRING& string
         );

      //! Called internally to update control-specific data from edit control.
      //! Derived class must call corresponding base class method AFTER performing its own processing.
      virtual void UpdateValue (bool notify = true);

   private:
   #ifndef GENERATING_DOXYGEN_OUTPUT

   #ifdef X_NATIVE
      Widget m_TraversalWidget;
      XmTraversalDirection m_TraversalDir;
      bool m_InternalModify;
      int m_MaxLength;
   #endif

      bool m_ValidInvert;
      MISTRING m_ValidChars;

   #ifdef X_NATIVE
      static void CB_Activate (Widget, CTRL_EDIT_BASE*, void*);
      static void CB_Focus (Widget, CTRL_EDIT_BASE*, void*);
      static void CB_LosingFocus (Widget, CTRL_EDIT_BASE*, void*);
      static void CB_ModifyVerify (Widget, CTRL_EDIT_BASE*, void*);
      static void CB_ValueChanged (Widget, CTRL_EDIT_BASE*, XmAnyCallbackStruct*);
   #endif

      CTRL_EDIT_BASE (const CTRL_EDIT_BASE&);
      CTRL_EDIT_BASE& operator= (const CTRL_EDIT_BASE&);
   #endif // GENERATING_DOXYGEN_OUTPUT

      // CTRL_EDIT_BASE Overridables

      //! Called when user presses <Enter> in edit control.
      virtual void OnActivate ();

      //! Called when value is changed after validation.
      //! If the user modifies the text in the edit control this will not be called until the control loses "focus".
      virtual void OnChangeValue ();

      //! Called when user modifies the text in the edit control.
      //! The actual value does not get updated until the control loses focus or GetValue() is called.
      virtual void OnUserEdit ();

   };


//===================================================================================================================
//! String 'edit' control.
class CTRL_EDIT_STRING : public MGUI::CTRL_EDIT_BASE {
   public:

      enum FLAGS {
         FLAG_Default =       0x0000,
         FLAG_RightJustify =  0x0001,     //!< Right-justify value, default is to left-justify
         FLAG_ReadOnly =      0x0002,     //!< User cannot change value
         FLAG_Opaque =        0x0004,     //!< Show '*'s for password input
         FLAG_WidthInPixels = 0x0008,     //!< Width specified in pixels
         };

      //! Constructor.
      CTRL_EDIT_STRING (
         );

      //! Destructor.
      virtual ~CTRL_EDIT_STRING (
         );

      //! Clear to empty string.
      void ClearValue (
         bool notify = true                     //!< Call OnChangeValue() if control has already been created
         );

      //! Create control.
      void Create (
         MGUI::LAYOUT_PANE_BASE& ParentPane,    //!< Parent pane
         int maxlen,                            //!< Maximum number of characters allowed in string, not including termination
         int width = 0,                         //!< Width in 'typical' characters, minimum if can expand based on sizealign
         FLAGS flags = FLAG_Default,
         MGUI::LAYOUT_SIZEALIGN sizealign = MGUI::LAYOUT_SIZEALIGN_FixedHeight
         );

      //! Get current string value.
      const MISTRING& GetValue (
         );

      //! Read value 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 OnChangeValue() if control has already been created
         );

      //! Write current value 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,m_value); }

      //! Set current string value with validation.
      //! OnValidate() will be called and if valid, the string will be updated.
      //! No comparison is made with the current string value.
      void SetValue (
         const UNICODE* string,              //!< New string to set
         bool notify = true                  //!< Call OnChangeValue() if string actually updated
         );

   protected:

      //! Validate the string and alter if possible/necessary.
      //! Derived class must call corresponding base class method BEFORE performing its own processing.
      //!   @return 'true' if string could be validated, 'false' if not
      virtual bool OnValidate (
         MISTRING& string                    //!< String to be validated
         );

   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT

      MISTRING m_value;

      //! Called internally to update control-specific data from edit control.
      virtual void UpdateValue (bool notify = true);

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

DEFINE_ENUM_OPERATORS(MGUI::CTRL_EDIT_STRING::FLAGS);


//-------------------------------------------------------------------------------------------------------------------
//! Convenience template for String 'edit' control to allow method in container class to be called.
template <class _CT> class CTRL_EDIT_STRING_T : public MGUI::CTRL_EDIT_STRING {
   public:

      //! Constructor.
      explicit CTRL_EDIT_STRING_T (
         _CT *pContainer
         ): m_pContainer(pContainer), m_pfOnChangeValue(0), m_pfOnUserEdit(0), m_pfOnValidate(0), m_pfOnActivate(0)
         { }

      //! Set container pointer.
      //! Container may also be specified in constructor.
      void SetContainer (
         _CT *pContainer
         ) { m_pContainer = pContainer; }

      //! Set container method to call for OnActivate().
      void SetFuncActivate (
         void (_CT::*pfOnActivate)()
         ) { m_pfOnActivate = pfOnActivate; };

      //! Set container method to call for OnChangeValue().
      void SetFuncChangeValue (
         void (_CT::*pfOnChangeValue)()
         ) { m_pfOnChangeValue = pfOnChangeValue; };

      //! Set container method to call for OnUserEdit().
      void SetFuncUserEdit (
         void (_CT::*pfOnUserEdit)()
         ) { m_pfOnUserEdit = pfOnUserEdit; };

      //! Set container method to call for OnValidate().
      void SetFuncValidate (
         bool (_CT::*pfOnValidate)(MISTRING& string)
         ) { m_pfOnValidate = pfOnValidate; };

   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT
      _CT *m_pContainer;
      void (_CT::*m_pfOnChangeValue)();
      void (_CT::*m_pfOnUserEdit)();
      bool (_CT::*m_pfOnValidate)(MISTRING&);
      void (_CT::*m_pfOnActivate)();

      virtual void OnChangeValue (
         ) { if (m_pfOnChangeValue != 0) (m_pContainer->*m_pfOnChangeValue)(); }

      virtual void OnActivate (
         ) { if (m_pfOnActivate != 0) (m_pContainer->*m_pfOnActivate)(); }

      virtual void OnUserEdit (
         ) { if (m_pfOnUserEdit != 0) (m_pContainer->*m_pfOnUserEdit)(); }

      virtual bool OnValidate (
         MISTRING& str
         ) {
         if (m_pfOnValidate != 0) return((m_pContainer->*m_pfOnValidate)(str));
         return (CTRL_EDIT_STRING::OnValidate(str));
         }
      #endif // GENERATING_DOXYGEN_OUTPUT
   };


//===================================================================================================================
//! Form consisting of label and string edit field.
class FORM_EDIT_STRING : public MGUI::FORM_COMPOSITE {
   public:
      //! Constructor.
      FORM_EDIT_STRING (
         );

      //! Destructor.
      virtual ~FORM_EDIT_STRING (
         );

      //! Clear to empty string.
      void ClearValue (
         bool notify = true                     //!< Call OnChangeValue() if control has already been created
         ) { m_editctrl.ClearValue(notify); }

      //! Create form with label from resource lookup.
      void Create (
         MGUI::LAYOUT_PANE_BASE& ParentPane,    //!< Parent pane
         const char *label,                     //!< Label
         int maxlen,                            //!< Maximum number of characters allowed in string, not including termination
         int width = 0,                         //!< Width in 'typical' characters, minimum if can expand based on sizing
         MGUI::CTRL_EDIT_STRING::FLAGS flags = MGUI::CTRL_EDIT_STRING::FLAG_Default,
         MGUI::LAYOUT_SIZEALIGN sizealign = MGUI::LAYOUT_SIZEALIGN_FixedHeight,
         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
         int maxlen,                            //!< Maximum number of characters allowed in string, not including termination
         int width = 0,                         //!< Width in 'typical' characters, minimum if can expand based on sizing
         MGUI::CTRL_EDIT_STRING::FLAGS flags = MGUI::CTRL_EDIT_STRING::FLAG_Default,
         MGUI::LAYOUT_SIZEALIGN sizealign = MGUI::LAYOUT_SIZEALIGN_FixedHeight,
         MGUI::CTRL_LABEL::STYLE labelstyle = MGUI::CTRL_LABEL::STYLE_LeftNoWrap
         );

      //! Retrieve string "edit" control for form.
      MGUI::CTRL_EDIT_STRING& GetEditCtrl (
         ) { return (m_editctrl); }

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

      //! Get current string value.
      const MISTRING& GetValue (
         ) { return (m_editctrl.GetValue()); }

      //! Read value 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 OnChangeValue() if control has already been created
         ) { m_editctrl.IniRead(IniHandle,IniGroup,IniField,notify); }

      //! Write current value to INI file.
      void IniWrite (
         INIHANDLE IniHandle,                //!< Handle to INI file to write to, 0 for default
         const char *IniGroup,               //!< INI group to write to
         const char *IniField                //!< INI field to write to
         ) const { m_editctrl.IniWrite(IniHandle,IniGroup,IniField); }

      //! Set label text using string from resource lookup.
      void SetLabel (
         const char *label                   //!< New label text
         ) { m_label.SetLabel(label); }

      //! Set label text from Unicode string.
      void SetLabel (
         const MISTRING& label                  //!< New label text
         ) { m_label.SetLabel(label); }

      //! Select range of characters in string.
      void SetSelection (
         int StartChar = 0,                  //!< Starting character position in string, 0 for beginning
         int EndChar = -1,                   //!< Ending character position, -1 for end of string
         bool NoScroll = true                //!< Indicates whether to scroll caret into view
         ) { m_editctrl.SetSelection(StartChar,EndChar,NoScroll); }

      //! Set set of 'valid' or 'invalid' characters.
      //! This does not alter the current contents, if any.