kconfigbase.h

一种效率高

   * was found.
   */
  QSize readSizeEntry( const char* pKey, const QSize* pDefault = 0L ) const;


  /**
	* Read a QColor.
	*
	* Read the value of an entry specified by rKey in the current group
	* and interpret it as a color.
	*
	* @param pKey		The key to search for.
	* @param pDefault	A default value returned if the key was not found.
	* @return The value for this key or a default color if no value
	* was found.
	*/
  QColor readColorEntry( const char* pKey,
						 const QColor* pDefault = 0L ) const;

  /** Write the key/value pair.
	*
	* This is stored to the most specific config file when destroying the
	* config object or when calling sync().
	*
	*  @param pKey		The key to write.
	*  @param pValue	The value to write.
	*  @param bPersistent	If bPersistent is false, the entry's dirty
	*			flag will not be set and thus the entry will
	*			not be written to disk at deletion time.
	*  @param bGlobal	If bGlobal is true, the pair is not saved to the
	*   application specific config file, but to the global ~/.kderc
	*  @param bNLS	If bNLS is true, the locale tag is added to the key
	*   when writing it back.
	*  @return The old value for this key. If this key did not
	*   exist, a null string is returned.	
*/
  const char* writeEntry( const char* pKey, const char* pValue,
						  bool bPersistent = true, bool bGlobal = false,
						  bool bNLS = false );

  /**
	* writeEntry() overriden to accept a list of strings.
	*
	* Note: Unlike the other writeEntry() functions, the old value is
	* _not_ returned here!
	*
	* @param pKey		The key to write
	* @param list		The list to write
	* @param sep		The list separator
	* @param bPersistent	If bPersistent is false, the entry's dirty flag
	*			will not be set and thus the entry will not be
	*			written to disk at deletion time.
	* @param bGlobal	If bGlobal is true, the pair is not saved to the
	*  application specific config file, but to the global ~/.kderc
	* @param bNLS	If bNLS is true, the locale tag is added to the key
	*  when writing it back.
	*
	* @see #writeEntry
	*/
  void writeEntry ( const char* pKey, QStrList &list, char sep = ',',
					bool bPersistent = true, bool bGlobal = false,
					bool bNLS = false );

  /** Write the key value pair.
	* Same as above, but write a numerical value.
	* @param pKey The key to write.
	* @param nValue The value to write.
	* @param bPersistent If bPersistent is false, the entry's dirty
	* flag will not be set and thus the entry will not be written to
	* disk at deletion time.
	* @param bGlobal	If bGlobal is true, the pair is not saved to the
	*  application specific config file, but to the global ~/.kderc
	* @param bNLS	If bNLS is true, the locale tag is added to the key
	*  when writing it back.
	* @return The old value for this key. If this key did not
	* exist, a null string is returned.	
	*/
  const char* writeEntry( const char* pKey, int nValue,
						  bool bPersistent = true, bool bGlobal = false,
						  bool bNLS = false );

  /** Write the key value pair.
	* Same as above, but write an unsigned numerical value.
	* @param pKey The key to write.
	* @param nValue The value to write.
	* @param bPersistent If bPersistent is false, the entry's dirty
	* flag will not be set and thus the entry will not be written to
	* disk at deletion time.
	* @param bGlobal	If bGlobal is true, the pair is not saved to the
	*  application specific config file, but to the global ~/.kderc
	* @param bNLS	If bNLS is true, the locale tag is added to the key
	*  when writing it back.
	* @return The old value for this key. If this key did not
	* exist, a null string is returned.	
	*/
  const char* writeEntry( const char* pKey, unsigned int nValue,
						  bool bPersistent = true, bool bGlobal = false,
						  bool bNLS = false );

  /** Write the key value pair.
	* Same as above, but write a long numerical value.
	* @param pKey The key to write.
	* @param nValue The value to write.
	* @param bPersistent If bPersistent is false, the entry's dirty
	* flag will not be set and thus the entry will not be written to
	* disk at deletion time.
	* @param bGlobal	If bGlobal is true, the pair is not saved to the
	*  application specific config file, but to the global ~/.kderc
	* @param bNLS	If bNLS is true, the locale tag is added to the key
	*  when writing it back.
	* @return The old value for this key. If this key did not
	* exist, a null string is returned.	
	*/
  const char* writeEntry( const char* pKey, long nValue,
						  bool bPersistent = true, bool bGlobal = false,
						  bool bNLS = false );

  /** Write the key value pair.
	* Same as above, but write an unsigned long numerical value.
	* @param pKey The key to write.
	* @param nValue The value to write.
	* @param bPersistent If bPersistent is false, the entry's dirty
	* flag will not be set and thus the entry will not be written to
	* disk at deletion time.
	* @param bGlobal	If bGlobal is true, the pair is not saved to the
	*  application specific config file, but to the global ~/.kderc
	* @param bNLS	If bNLS is true, the locale tag is added to the key
	*  when writing it back.
	* @return The old value for this key. If this key did not
	* exist, a null string is returned.	
	*/
  const char* writeEntry( const char* pKey, unsigned long nValue,
						  bool bPersistent = true, bool bGlobal = false,
						  bool bNLS = false );

  /** Write the key value pair.
	* Same as above, but write a floating-point value.
	* @param pKey The key to write.
	* @param nValue The value to write.
	* @param bPersistent If bPersistent is false, the entry's dirty
	* flag will not be set and thus the entry will not be written to
	* disk at deletion time.
	* @param bGlobal	If bGlobal is true, the pair is not saved to the
	*  application specific config file, but to the global ~/.kderc
	* @param bNLS	If bNLS is true, the locale tag is added to the key
	*  when writing it back.
	* @return The old value for this key. If this key did not
	* exist, a null string is returned.	
	*/
  const char* writeEntry( const char* pKey, double nValue,
						  bool bPersistent = true, bool bGlobal = false,
						  bool bNLS = false );

  /** Write the key value pair.
	* Same as above, but write a boolean value.
	* @param pKey The key to write.
	* @param bValue The value to write.
	* @param bPersistent If bPersistent is false, the entry's dirty
	* flag will not be set and thus the entry will not be written to
	* disk at deletion time.
	* @param bGlobal	If bGlobal is true, the pair is not saved to the
	*  application specific config file, but to the global ~/.kderc
	* @param bNLS	If bNLS is true, the locale tag is added to the key
	*  when writing it back.
	* @return The old value for this key. If this key did not
	* exist, a null string is returned.	
	*/
  const char* writeEntry( const char* pKey, bool bValue,
						  bool bPersistent = true, bool bGlobal = false,
						  bool bNLS = false );

  /** Write the key value pair.
	* Same as above, but write a font
	* @param pKey The key to write.
	* @param rFont The font value to write.
	* @param bPersistent If bPersistent is false, the entry's dirty
	* flag will not be set and thus the entry will not be written to
	* disk at deletion time.
	* @param bGlobal	If bGlobal is true, the pair is not saved to the
	*  application specific config file, but to the global ~/.kderc
	* @param bNLS	If bNLS is true, the locale tag is added to the key
	*  when writing it back.
	* @return The old value for this key. If this key did not
	* exist, a null string is returned.	
	*/
  const char* writeEntry( const char* pKey, const QFont& rFont,
						  bool bPersistent = true, bool bGlobal = false,
						  bool bNLS = false );

  /** Write the key value pair.
	* Same as above, but write a color
	* @param pKey The key to write.
	* @param rValue The color value to write.
	* @param bPersistent If bPersistent is false, the entry's dirty
	* flag will not be set and thus the entry will not be written to
	* disk at deletion time.
	* @param bGlobal	If bGlobal is true, the pair is not saved to the
	*  application specific config file, but to the global ~/.kderc
	* @param bNLS	If bNLS is true, the locale tag is added to the key
	*  when writing it back.
	* @return The old value for this key. If this key did not
	*  exist, a null string is returned.	
	*/
  void writeEntry( const char* pKey, const QColor& rColor,
				   bool bPersistent = true, bool bGlobal = false,
				   bool bNLS = false );

  /** Write the key value pair.
	* Same as above, but write a rectangle
	* @param pKey The key to write.
	* @param rValue The rectangle value to write.
	* @param bPersistent If bPersistent is false, the entry's dirty
	* flag will not be set and thus the entry will not be written to
	* disk at deletion time.
	* @param bGlobal	If bGlobal is true, the pair is not saved to the
	*  application specific config file, but to the global ~/.kderc
	* @param bNLS	If bNLS is true, the locale tag is added to the key
	*  when writing it back.
	* @return The old value for this key. If this key did not
	*  exist, a null string is returned.	
	*/
  void writeEntry( const char* pKey, const QRect& rColor,
				   bool bPersistent = true, bool bGlobal = false,
				   bool bNLS = false );

  /** Write the key value pair.
	* Same as above, but write a point
	* @param pKey The key to write.
	* @param rValue The point value to write.
	* @param bPersistent If bPersistent is false, the entry's dirty
	* flag will not be set and thus the entry will not be written to
	* disk at deletion time.
	* @param bGlobal	If bGlobal is true, the pair is not saved to the
	*  application specific config file, but to the global ~/.kderc
	* @param bNLS	If bNLS is true, the locale tag is added to the key
	*  when writing it back.
	* @return The old value for this key. If this key did not
	*  exist, a null string is returned.	
	*/
  void writeEntry( const char* pKey, const QPoint& rColor,
						  bool bPersistent = true, bool bGlobal = false,
						  bool bNLS = false );

  /** Write the key value pair.
	* Same as above, but write a size
	* @param pKey The key to write.
	* @param rValue The size value to write.
	* @param bPersistent If bPersistent is false, the entry's dirty
	* flag will not be set and thus the entry will not be written to
	* disk at deletion time.
	* @param bGlobal	If bGlobal is true, the pair is not saved to the
	*  application specific config file, but to the global ~/.kderc
	* @param bNLS	If bNLS is true, the locale tag is added to the key
	*  when writing it back.
	* @return The old value for this key. If this key did not
	*  exist, a null string is returned.	
	*/
  void writeEntry( const char* pKey, const QSize& rColor,
						  bool bPersistent = true, bool bGlobal = false,
						  bool bNLS = false );
  //}


	/** Turns on or off "dollar expansion" when reading config entries.
	 *	@param bExpand if true, dollar expansion is turned on.
	 */
	void setDollarExpansion( bool bExpand = true );

	/** Returns whether dollar expansion is on or off.
	 *	@return true if dollar expansion is on.
	 */
	bool isDollarExpansion() const;

  /** Don't write dirty entries at destruction time. If bDeep is
	* false, only the global dirty flag of the KConfig object gets
	* cleared. If you then call writeEntry again, the global dirty flag
	* is set again and all dirty entries will be written.
	* @param bDeep if
	* true, the dirty flags of all entries are cleared, as well as the
	* global dirty flag.
	*/
  virtual void rollback( bool bDeep = true );

  /** Flush the entry cache. Write back dirty configuration entries to
	* the most specific file. This is called automatically from the
	* destructor.
	* This method must be implemented by the derived classes.
   */
  virtual void sync() = 0;

  /** Check if the key has an entry in the specified group
	  Use this to determine if a key is not specified for the current
	  group (HasKey returns false) or is specified but has no value
	  ("key =EOL"; Has Key returns true, ReadEntry returns an empty
	  string)
	  @param pKey The key to search for.
	  @return if true, the key is available
   */
  bool hasKey( const char* pKey ) const;

  /** Returns an iterator on the list of groups
	  @return The group iterator. The caller is reponsable for
	  deleting the iterator after using it.
  */
  KGroupIterator* groupIterator(void) { return pData->groupIterator(); }

  /** Returns an iterator on the entries in the current group
	  @param pGroup the group to provide an iterator for
	  @return The iterator for the group or 0, if the group does not
	  exist. The caller is responsible for deleting the iterator after
	  using it.
	  */
  KEntryIterator* entryIterator( const char* pGroup );

  /** Reparses all configuration files. This is useful for programms
	  which use standalone graphical configuration tools.
   */
  virtual void reparseConfiguration();
};


/**
  * Helper class to facilitate working with KConfig/KSimpleConfig groups
  *
  * Careful programmers always set the group of a
  * KConfig/KSimpleConfig object to the group they want to read from
  * and set it back to the old one of afterwards. This is usually
  * written as
  *
  * QString oldgroup config->group();
  * config->setGroup( "TheGroupThatIWant" );
  * ...
  * config->writeEntry( "Blah", "Blubb" );
  *
  * config->setGroup( oldgroup );
  *
  * In order to facilitate this task, you can use
  * KConfigGroupSaver. Simply construct such an object ON THE STACK
  * when you want to switch to a new group. Then, when the object goes
  * out of scope, the group will automatically be restored. If you
  * want to use several different groups within a function or method,
  * you can still use KConfigGroupSaver: Simply enclose all work with
  * one group (including the creation of the KConfigGroupSaver object)
  * in one block.
  *
  * @author Kalle Dalheimer <[e-mail]>
  * @version $Id: kconfigbase.h,v 1.1 2003/09/08 19:42:04 jasonk Exp $
  * @see KConfigBase, KConfig, KSimpleConfig
  * @short helper class for easier use of KConfig/KSimpleConfig groups
  */

class KConfigGroupSaver
{
public:
  /** Constructor. You pass a pointer to the KConfig/KSimpleConfig
	* object you want to work with and a string indicating the _new_
	* group.
	* @param config the KConfig/KSimpleConfig object this
	* KConfigGroupSaver works on
	* @param group the new group that the KConfig/KSimpleConfig object
	* should switch to
	*/
  KConfigGroupSaver( KConfigBase* config, QString group )
      : _config(config), _oldgroup(config->group())
	{
	  //	  _config = config;
	  //	  _oldgroup = _config->group();
	  _config->setGroup( group );
	};

  ~KConfigGroupSaver()
	{
	  _config->setGroup( _oldgroup );
	}

private:
  KConfigBase* _config;
  QString _oldgroup;

  KConfigGroupSaver(const KConfigGroupSaver&);
  KConfigGroupSaver& operator=(const KConfigGroupSaver&);
};

#endif