/***************************************************************************
                          SIMPLY POWERFUL TOOLKIT (SPTK)
                          CDataSource.h  -  description
                             -------------------
    begin                : Jun 20 2003
    copyright            : (C) 1999-2006 by Alexey Parshin
    email                : alexeyp@gmail.com
 ***************************************************************************/

/***************************************************************************
   This library is free software; you can redistribute it and/or modify it 
   under the terms of the GNU Library General Public License as published by
   the Free Software Foundation; either version 2 of the License, or (at 
   your option) any later version.

   This library is distributed in the hope that it will be useful, but 
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library
   General Public License for more details.

   You should have received a copy of the GNU Library General Public License
   along with this library; if not, write to the Free Software Foundation, 
   Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.

   Please report all bugs and problems to "alexeyp@gmail.com"
 ***************************************************************************/

#ifndef __CDATASOURCE_H__
#define __CDATASOURCE_H__

#include <sptk3/CVariant.h>
#include <sptk3/CFieldList.h>
#include <sptk3/cxml>

class Fl_Group;

namespace sptk {

   /// @addtogroup gui GUI Classes
   /// @{

   /// @brief Universal data source for many SPTK widgets.
   ///
   /// It's designed as a base class for multiple datasources available in SPTK.
   /// The main idea is to provide the simple interface that allows to open the datasource
   /// with certain parameters and read or write the datasource fields. And don't you forget to close it :)
	class CDataSource {
		friend class Fl_Group;

	protected:
      /// Loads datasource data. Should be implemented in derived class
		virtual bool loadData() { return true; } 
      /// Saves data from datasource. Should be implemented in derived class
		virtual bool saveData() { return true; } 

	public:
      /// Default constructor
		CDataSource() {}

      /// Destructor
		virtual ~CDataSource() {}

	public:
      /// Field access by the field index, const version. 
      /// Purely virtual. Should be implemented in derived class
      /// @param fieldIndex int, field index
      /// @returns field reference
		virtual const CField& operator [] (int fieldIndex) const = 0;

      /// Field access by the field index, non-const version
      /// Purely virtual. Should be implemented in derived class
      /// @param fieldIndex int, field index
      /// @returns field reference
		virtual CField&       operator [] (int fieldIndex) = 0;

      /// Field access by the field name, const version. 
      /// Purely virtual. Should be implemented in derived class
      /// @param fieldName const char *, field name
      /// @returns field reference
		virtual const CField& operator [] (const char *fieldName) const = 0;

      /// Field access by the field name, const version. 
      /// Purely virtual. Should be implemented in derived class
      /// @param fieldName const char *, field name
      /// @returns field reference
		virtual CField&       operator [] (const char *fieldName) = 0;

      /// Returns field count in the datasource. 
      /// Purely virtual. Should be implemented in derived class
      /// @returns field count
		virtual unsigned      fieldCount() const = 0;
	public:

      /// Returns record count in the datasource. 
      /// Purely virtual. Should be implemented in derived class
      /// @returns record count
		virtual unsigned      recordCount() const = 0;

      /// Returns user_data associated with the datasource.
		virtual void         *user_data() const { return 0L; } 
	public:
      /// Reads the field by name from the datasource.
      /// Purely virtual. Should be implemented in derived class
      /// @param fieldName const char *, field name
      /// @param fieldValue CVariant, field value 
		virtual bool          readField(const char *fieldName,CVariant& fieldValue) = 0;

      /// Writes the field by name from the datasource.
      /// Purely virtual. Should be implemented in derived class
      /// @param fieldName const char *, field name
      /// @param fieldValue CVariant, field value 
		virtual bool          writeField(const char *fieldName,const CVariant& fieldValue) = 0;
	public:

      /// Opens the datasource. Implemented in derved class.
		virtual bool          open()  { return false; }

      /// Closes the datasource. Implemented in derved class.
		virtual bool          close() { return false; }

      /// Moves to the first record of the datasource. Implemented in derved class.
		virtual bool          first() { return false; }

      /// Moves to the next record of the datasource. Implemented in derved class.
		virtual bool          next()  { return false; }

      /// Moves to the prior record of the datasource. Implemented in derved class.
		virtual bool          prior() { return false; }

      /// Moves to the last record of the datasource. Implemented in derved class.
		virtual bool          last()  { return false; }

      /// Moves to the specified record position of the datasource. Implemented in derved class.
		virtual bool          find(CVariant position) { return false; }

      /// Returns true if there are no more records in the datasource. Implemented in derved class.
		virtual bool          eof() const  { return false; }

      /// Loads data into the datasource
		bool load();

      /// Saves data from the datasource
		bool save();

      /// @brief Saves dataset row data into XML
      ///
      /// If the compactXmlMode is true, the node would have fields presented as attributues.
      /// Otherwise, the fields are stored as subnodes.
      /// @param node CXmlNode&, the XML node to fill in
      /// @param compactXmlMode bool, compact XML flag
		void rowToXML(CXmlNode& node,bool compactXmlMode) const;

      /// @brief Saves data into XML
      ///
      /// Opens the dataset, reads every row, and closes dataset.
      /// For every row in the dataset, creates the node with the name nodeName.
      /// If the compactXmlMode is true, the nodes would have fields presented as attributues.
      /// Otherwise, the fields are stored as subnodes.
      /// @param parentNode CXmlNode&, the XML node to add subnodes to
      /// @param nodeName std::string, the name for subnodes
      /// @param compactXmlMode bool, compact XML flag
		virtual void toXML(CXmlNode& parentNode,std::string nodeName,bool compactXmlMode);
	};

   /// @}
}
#endif
