mgui/xmldata.h

Go to the documentation of this file.

/*****************************************************************************
 *
 * \file mgui/xmldata.h
 * \brief 
 * 
 * \if NODOC
 * $Log: xmldata.h_v $
 * Revision 1.6  2003/11/14 18:33:11  dwilliss
 * Added a private enum which is passed to a private method.
 *
 * Revision 1.5  2003/10/03 19:58:19  linux32build!build
 * Doxygen
 *
 * Revision 1.4  2003/09/30 16:53:09  dwilliss
 * Doxygen
 *
 * Revision 1.3  2003/09/15 13:49:32  fileserver!dwilliss
 * Doxygen
 *
 * Revision 1.2  2003/07/08 22:22:23  dwilliss
 * Needed to include colorh
 *
 * Revision 1.1  2003/07/08 17:56:58  dwilliss
 * Initial revision
 *
 * Revision 1.2  2002/10/09 22:41:00  dwilliss
 * Moved to mgui subdirectory
 *
 * Revision 1.1  2002/10/09 22:38:13  dwilliss
 * Initial revision
 *
 * Revision 1.2  2002/09/19 22:34:09  dwilliss
 * Major update.  Almost complete
 *
 * Revision 1.1  2002/09/03 22:38:57  dwilliss
 * Initial revision
 *
 *
 * \endif
 ****************************************************************************/

#ifndef INC_MGUI_XMLDATA_H
#define INC_MGUI_XMLDATA_H


#ifndef INC_MI32_COLOR_H
#include <mi32/color.h>
#endif

#ifndef INC_MI32_XML_H
#include <mi32/xml.h>
#endif

namespace MGUI {


//! Class used to pass data back and forth between programs and MGUI::DLG_XML
//! and MGUI::LAYOUT_PANE_XML.  The actual form data is stored in an XML
//! document which looks something like this...
//!
//! @code
//!   <?xml version="1.0" encoding="utf-8"?>
//!   <struct>
//!      <member id="FirstName">John</member>
//!      <member id="LastName">Doe</member>
//!      <member id="Age" value="45"/>
//!   </struct>
//! @endcode
//!
//! Although I may settle on placing the value always in a "value" attribute 
//! instead of as the content of the <member> tag, or always in the contents
//! of the member tag as a CDATA section
//!
//! <b>Data storage:<b>
//!
//!   - Combo Boxes and single-select lists:
//!      The data in the returned <member> tag will be the "value"
//!      attribute of the selected <item>.  If the selected <item>
//!      does not have a value attribute, it will be the index into
//!      the list of items (with the first item being zero)
//!
//!   - Multi-Select lists:
//!      The data in the returned <member> tag will be a comma-seperated
//!      list of the "value" attriubtes of the selected <item>s.
//!
//!   - Numeric fields:
//!      The returned <member> tag will have a "value" attribute holding
//!      the number, but no content (see example above)
//!
//!      Toggle Buttons:
//!      Toggle buttons are treated as numeric fields with 1 or 0 as
//!      the only possible values.  You can use the XMLNODE Get/Set
//!      property methods which take and return bool to retrieve this.
//!
//!   - Radio Groups:
//!      If a toggle button is in a RadioGroup, the returned record
//!      will have one <member> for the whole group.  The "id" of this
//!      <member> will be the id of the first button in the group.
//!      The "value" attribute of this <member> will be the "value"
//!      attribute of the selected button in the group.
//!
//!   - Color:  (not implemented yet, just planning ahead)
//!      Will have attributes, "red", "green", "blue" and "transp" 
//!         RGB values are from 0 to 65535.  transp values are from
//!         0 to 100 (or is it 255?), but will be omitted if the
//!         control does not have "AllowTransparency" set.
//!
class XMLFORM_DATA : public XMLDOC {
   public:

      enum PROPERTY {
         PROPERTY_Value = 0,           //!< The "value" attribute
         PROPERTY_Min,
         PROPERTY_Max,
         };

      //! Default constructor
      XMLFORM_DATA (
         );

      //! Constructor.
      //! Copies initial values from the given node
      XMLFORM_DATA (
         const XMLNODE* InitialValues
         );

      //! Copy constructor
      XMLFORM_DATA (
         const XMLFORM_DATA&
         );

      //======================= Get Methods ============================
      
      //! Retrieve the value of a single control (MISTRING)
      //! Always stores strings as the <member> tag's contents
      //! @return false if the id wasn't found, true if it was
      bool GetValue (
         const char* id,         //!< ID of the control to get value of
         MISTRING& value         //!< Value returned
         ) const;

      //! Retrieve the value of a single control (double)
      //! Some controls have more than one value.  For example,
      //! a range control would have a PROPERTY_Min and a PROPERTY_Max.
      //! Currently, only numeric controls can have more than one property
      //! @return false if the id wasn't found, true if it was
      bool GetValue (
         const char* id,         //!< ID of the control to get value of
         double& value,          //!< Value returned
         XMLFORM_DATA::PROPERTY property = PROPERTY_Value
         ) const;

      //! Retrieve the value of a single control (INT32)
      //! Some controls have more than one value.  For example,
      //! a range control would have a PROPERTY_Min and a PROPERTY_Max.
      //! Currently, only numeric controls can have more than one property
      //! @return false if the id wasn't found, true if it was
      bool GetValue (
         const char* id,         //!< ID of the control to get value of
         INT32& value,           //!< Value returned
         XMLFORM_DATA::PROPERTY property = PROPERTY_Value
         ) const;

      //! Retrieve the value of a single control (INT32)
      //! @return false if the id wasn't found, true if it was
      bool GetValue (
         const char* id,         //!< ID of the control to get value of
         bool& value             //!< Value returned
         ) const;


      //! Retrieve the value of a single control (INT32)
      //! @return false if the id wasn't found, true if it was
      bool GetValue (
         const char* id,         //!< ID of the control to get value of
         COLOR& value            //!< Value returned
         ) const;


      //! Returns the main record node.
      XMLNODE* GetRecordNode (
         ) const {
         return m_root;
         }

      //======================= Set Methods ============================

      //! Set the value of a single control (MISTRING)
      void SetValue (
         const char* id,         //!< ID of the control to get value of
         const MISTRING& value         //!< Value to set
         );

      //! Set the value of a single control (double)
      void SetValue (
         const char* id,         //!< ID of the control to get value of
         double value,           //!< Value to set
         XMLFORM_DATA::PROPERTY property = PROPERTY_Value
         );

      //! Set the value of a single control (bool)
      void SetValue (
         const char* id,         //!< ID of the control to get value of
         bool value              //!< Value to set
         );

      //! Set the value of a single control (COLOR)
      void SetValue (
         const char* id,         //!< ID of the control to get value of
         const COLOR& value      //!< value to set
         );

   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT

      enum TYPE {
         TYPE_Int,
         TYPE_Double,
         TYPE_String,
         TYPE_Bool,
         TYPE_Color
         };

      XMLNODE* m_root;  //!< The root node of the record

      XMLNODE* FindNode (
         const char* id,
         bool create = false
         ) const;

      void OnDocReplaced();
      
      //! Set the value of a single control (MISTRING)
      void InternalSetValue (
         const char* id,               //!< ID of the control to get value of
         const MISTRING& value,        //!< Value to set
         PROPERTY property,
         TYPE type
         );
      #endif // GENERATING_DOXYGEN_OUTPUT

   };

}     // End of MGUI namespace

#endif

---