|
|
Abstract base class for KDE configuration entries.
This class forms the base for all KDE configuration. It is an abstract base class, meaning that you cannot directly instantiate objects of this class. Either use KConfig (for usual KDE configuration) or KSimpleConfig (for special needs as in ksamba), or even KSharedConfig (stores values in shared memory).
All configuration entries are key, value pairs. Each entry also belongs to a specific group of related entries. All configuration entries that do not explicitly specify which group they are in are in a special group called the default group.
If there is a $ character in an entry, KConfigBase tries to expand environment variable and uses its value instead of its name. You can avoid this feature by having two consecutive $ characters in your config file which get expanded to one.
See also: KConfig, KSimpleConfig, KSimpleConfig
|
Construct a KConfigBase object.
~ |
[virtual]
Destructor.
void |
Specify the group in which keys will be searched.
Subsequent calls to readEntry() will look only for keys in the currently activated group.
Switch back to the default group by passing an empty string.
Parameters:
pGroup | The name of the new group. |
void |
Set the group to the "Desktop Entry" group used for desktop configuration files for applications, mime types, etc.
QString |
[const]
Retrieve the name of the group in which we are searching for keys and from which we are retrieving entries.
Returns: The current group.
bool |
[const pure virtual]
Returns true
if the specified group is known about.
Parameters:
_pGroup | The group to search for. |
Returns: Whether the group exists.
QStringList |
[const pure virtual]
Retrieve a list of groups that are known about.
Returns: The list of groups.
QString |
[const]
Retrieve a the current locale.
Returns: A string representing the current locale.
QString |
[const]
Read the value of an entry specified by rKey
in the current group.
Parameters:
aKey | The key to search for. |
aDefault | A default value returned if the key was not found. |
Returns: The value for this key or a null string if no value was found.
QVariant |
[const]
Read the value of an entry specified by aKey
in the current group.
The value is treated as if it is of the given type.
Returns: An empty property or error.
int |
[const]
Read a list of strings.
Parameters:
pKey | The key to search for |
list | In this object, the read list will be returned. |
sep | The list separator (default ",") |
Returns: The number of entries in the list.
QStringList |
[const]
Read a list of strings.
Parameters:
pKey | The key to search for. |
sep | The list separator (default is ","). |
Returns: The list.
QValueList<int> |
[const]
Read a list of Integers.
Parameters:
pKey | The key to search for. |
Returns: The list.
int |
[const]
Read a numerical value.
Read the value of an entry specified by rKey
in the current group
and interpret it numerically.
Parameters:
pKey | The key to search for. |
nDefault | A default value returned if the key was not found. |
Returns: The value for this key or 0 if no value was found.
unsigned int |
[const]
Read a numerical value.
Read the value of an entry specified by rKey
in the current group
and interpret it numerically.
Parameters:
pKey | The key to search for. |
nDefault | A default value returned if the key was not found. |
Returns: The value for this key or 0 if no value was found.
long |
[const]
Read a numerical value.
Read the value of an entry specified by rKey
in the current group
and interpret it numerically.
Parameters:
pKey | The key to search for. |
nDefault | A default value returned if the key was not found. |
Returns: The value for this key or 0 if no value was found.
unsigned long |
[const]
Read a numerical value.
Read the value of an entry specified by rKey
in the current group
and interpret it numerically.
Parameters:
pKey | The key to search for. |
nDefault | A default value returned if the key was not found. |
Returns: The value for this key or 0 if no value was found.
double |
[const]
Read a numerical value.
Read the value of an entry specified by rKey
in the current group
and interpret it numerically.
Parameters:
pKey | The key to search for. |
nDefault | A default value returned if the key was not found. |
Returns: The value for this key or 0 if no value was found.
QFont |
[const]
Read a QFont.
Read the value of an entry specified by rKey
in the current group
and interpret it as a font object.
Parameters:
pKey | The key to search for. |
pDefault | A default value returned if the key was not found. |
Returns: The value for this key or a default font if no value was found.
bool |
[const]
Read a boolean entry.
Read the value of an entry specified by pKey
in the current group
and interpret it as a boolean value. Currently "on" and "true" are
accepted as true, everything else if false.
Parameters:
pKey | The key to search for |
bDefault | A default value returned if the key was not found. |
Returns: The value for this key or a default value if no value was found.
QRect |
[const]
Read a rect entry.
Read the value of an entry specified by pKey in the current group and interpret it as a QRect object.
Parameters:
pKey | The key to search for |
pDefault | A default value returned if the key was not found. |
Returns: The value for this key or a default rectangle if no value was found.
QPoint |
[const]
Read a point entry.
Read the value of an entry specified by pKey
in the current group
and interpret it as a QPoint object.
Parameters:
pKey | The key to search for |
pDefault | A default value returned if the key was not found. |
Returns: The value for this key or a default point if no value was found.
QSize |
[const]
Read a size entry.
Read the value of an entry specified by pKey
in the current group
and interpret it as a QSize object.
Parameters:
pKey | The key to search for |
pDefault | A default value returned if the key was not found. |
Returns: The value for this key or a default point if no value was found.
QColor |
[const]
Read a QColor.
Read the value of an entry specified by rKey
in the current group
and interpret it as a color.
Parameters:
pKey | The key to search for. |
pDefault | A default value returned if the key was not found. |
Returns: The value for this key or a default color if no value was found.
QDateTime |
[const]
Read a QDateTime.
Read the value of an entry specified by rKey
in the current group
and interpret it as a date and time.
Parameters:
pKey | The key to search for. |
pDefault | A default value returned if the key was not found. |
Returns: The value for this key or a currentDateTime() (Qt global function) if no value was found.
QString |
Write the key/value pair.
This is stored in the most specific config file when destroying the config object or when calling sync().
Parameters:
pKey | The key to write. |
pValue | The value to write. |
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.
|
bGlobal | If bGlobal is true, the pair is not saved to the
application specific config file, but to the
global KDE config file.
|
bNLS | If bNLS is true, the locale tag is added to the key
when writing it back.
|
Returns: The old value for this key. If this key did not exist, a null string is returned.
void |
writeEntry() Overridden to accept a property.
Note: Unlike the other writeEntry() functions, the old value is _not_ returned here!
Parameters:
rKey | The key to write |
rValue | The property to write |
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.
|
bGlobal | If bGlobal is true, the pair is not saved to the
application specific config file, but to the
global KDE config file.
|
bNLS | If bNLS is true, the locale tag is added to the key
when writing it back.
|
void |
writeEntry() overriden to accept a list of strings.
Note: Unlike the other writeEntry() functions, the old value is _not_ returned here!
Parameters:
rKey | The key to write |
rValue | The list to write |
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.
|
bGlobal | If bGlobal is true, the pair is not saved to the
application specific config file, but to the
global KDE config file.
|
bNLS | If bNLS is true, the locale tag is added to the key
when writing it back.
|
void |
writeEntry() overridden to accept a list of strings.
Note: Unlike the other writeEntry() functions, the old value is _not_ returned here!
Parameters:
rKey | The key to write |
rValue | The list to write |
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.
|
bGlobal | If bGlobal is true, the pair is not saved to the
application specific config file, but to the
global KDE config file.
|
bNLS | If bNLS is true, the locale tag is added to the key
when writing it back.
|
void |
writeEntry() overridden to accept a list of Integers.
Note: Unlike the other writeEntry() functions, the old value is _not_ returned here!
Parameters:
rKey | The key to write |
rValue | The list to write |
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.
|
bGlobal | If bGlobal is true, the pair is not saved to the
application specific config file, but to the
global KDE config file.
|
bNLS | If bNLS is true, the locale tag is added to the key
when writing it back.
|
QString |
Write the key/value pair.
This is stored to the most specific config file when destroying the config object or when calling sync().
Parameters:
pKey | The key to write. |
pValue | The value to write. |
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.
|
bGlobal | If bGlobal is true, the pair is not saved to the
application specific config file, but to the
global KDE config file.
|
bNLS | If bNLS is true, the locale tag is added to the key
when writing it back.
|
Returns: The old value for this key. If this key did not exist, a null string is returned.
QString |
Write the key value pair. Same as above, but write a numerical value.
Parameters:
pKey | The key to write. |
nValue | The value to write. |
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.
|
bGlobal | If bGlobal is true, the pair is not saved to the
application specific config file, but to the
global KDE config file.
|
bNLS | If bNLS is true, the locale tag is added to the key
when writing it back.
|
Returns: The old value for this key. If this key did not exist, a null string is returned.
QString |
Write the key value pair. Same as above, but write an unsigned numerical value.
Parameters:
pKey | The key to write. |
nValue | The value to write. |
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.
|
bGlobal | If bGlobal is true, the pair is not saved to the
application specific config file, but to the
global KDE config file.
|
bNLS | If bNLS is true, the locale tag is added to the key
when writing it back.
|
Returns: The old value for this key. If this key did not exist, a null string is returned.
QString |
Write the key value pair. Same as above, but write a long numerical value.
Parameters:
pKey | The key to write. |
nValue | The value to write. |
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.
|
bGlobal | If bGlobal is true, the pair is not saved to the
application specific config file, but to the global KDE config file.
|
bNLS | If bNLS is true, the locale tag is added to the key
when writing it back.
|
Returns: The old value for this key. If this key did not exist, a null string is returned.
QString |
Write the key value pair. Same as above, but write an unsigned long numerical value.
Parameters:
pKey | The key to write. |
nValue | The value to write. |
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.
|
bGlobal | If bGlobal is true, the pair is not saved to the
application specific config file, but to the global KDE config file.
|
bNLS | If bNLS is true, the locale tag is added to the key
when writing it back.
|
Returns: The old value for this key. If this key did not exist, a null string is returned.
QString |
Write the key value pair. Same as above, but write a floating-point value.*
Parameters:
pKey | The key to write. |
nValue | The value to write. |
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.
|
bGlobal | If bGlobal is true, the pair is not saved to the
application specific config file, but to the global KDE config file.
|
format | format determines the format to which the value
is converted. Default is 'g'.
|
precision | precision sets the precision with which the
value is converted. Default is 6 as in QString.
|
bNLS | If bNLS is true, the locale tag is added to the key
when writing it back.
|
Returns: The old value for this key. If this key did not exist, a null string is returned.
QString |
Write the key value pair. Same as above, but write a boolean value.
Parameters:
pKey | The key to write. |
bValue | The value to write. |
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.
|
bGlobal | If bGlobal is true, the pair is not saved to the
application specific config file, but to the global KDE config file.
|
bNLS | If bNLS is true, the locale tag is added to the key
when writing it back.
|
Returns: The old value for this key. If this key did not exist, a null string is returned.
QString |
Write the key value pair. Same as above, but write a font
Parameters:
pKey | The key to write. |
rFont | The font value to write. |
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.
|
bGlobal | If bGlobal is true, the pair is not saved to the
application specific config file, but to the global KDE config file.
|
bNLS | If bNLS is true, the locale tag is added to the key
when writing it back.
|
Returns: The old value for this key. If this key did not exist, a null string is returned.
void |
Write the key value pair. Same as above, but write a color.
Note: Unlike the other writeEntry() functions, the old value is _not_ returned here!
Parameters:
pKey | The key to write. |
rValue | The color value to write. |
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.
|
bGlobal | If bGlobal is true, the pair is not saved to the
application specific config file, but to the global KDE config file.
|
bNLS | If bNLS is true, the locale tag is added to the key
when writing it back.
|
void |
Write the key value pair. Same as above, but write a date and time.
Note: Unlike the other writeEntry() functions, the old value is not returned here!
Parameters:
pKey | The key to write. |
rValue | The date and time value to write. |
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.
|
bGlobal | If bGlobal is true, the pair is not saved to the
application specific config file, but to the global KDE config file.
|
bNLS | If bNLS is true, the locale tag is added to the key
when writing it back.
|
void |
Write the key value pair. Same as above, but write a rectangle.
Note: Unlike the other writeEntry() functions, the old value is _not_ returned here!
Parameters:
pKey | The key to write. |
rValue | The rectangle value to write. |
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.
|
bGlobal | If bGlobal is true, the pair is not saved to the
application specific config file, but to the global KDE config file.
|
bNLS | If bNLS is true, the locale tag is added to the key
when writing it back.
|
void |
Write the key value pair. Same as above, but write a point.
Note: Unlike the other writeEntry() functions, the old value is _not_ returned here!
Parameters:
pKey | The key to write. |
rValue | The point value to write. |
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.
|
bGlobal | If bGlobal is true, the pair is not saved to the
application specific config file, but to the global KDE config file.
|
bNLS | If bNLS is true, the locale tag is added to the key
when writing it back.
|
void |
Write the key value pair. Same as above, but write a size.
Note: Unlike the other writeEntry() functions, the old value is _not_ returned here!
Parameters:
pKey | The key to write. |
rValue | The size value to write. |
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.
|
bGlobal | If bGlobal is true, the pair is not saved to the
application specific config file, but to the global KDE config file.
|
bNLS | If bNLS is true, the locale tag is added to the key
when writing it back.
|
void |
Turns on or off "dollar expansion" (see KConfigBase introduction) when reading config entries. Dollar sign expansion is initially OFF.
Parameters:
_bExpand | Tf true, dollar expansion is turned on. |
bool |
[const]
Returns whether dollar expansion is on or off. It is initially OFF.
Returns: true if dollar expansion is on.
void |
[virtual]
Mark the config object as "clean," i.e. 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 at a subsequent sync() call.
Classes that derive from KConfigObject should override this method and implement storage-specific behaviour, as well as calling the KConfigBase::rollback() explicitly in the initializer.
Parameters:
bDeep | If true, the dirty flags of all entries are cleared,
as well as the global dirty flag.
|
void |
[virtual]
Flush all changes that currently reside only in memory back to disk / permanent storage. Dirty configuration entries are written to the most specific file available.
Asks the back end to flush out all pending writes, and then calls
rollback(). No changes are made if the object has readOnly
status.
You should call this from your destructor in derivative classes.
See also: rollback(), isReadOnly()
bool |
[const]
Returns: true
if the config file has any dirty (modified) entries.
void |
[virtual]
Set the config object's read-only status.
Parameters:
_ro | If true, the config object will not write out any
changes to disk even if it is destroyed or sync() is called.
|
bool |
[const]
Queries the read-only status of the config object.
Returns: The read-only status.
bool |
[const pure virtual]
Check whether the key has an entry in the currently active group. Use this to determine whether a key is not specified for the current group (hasKey() returns false). Keys with null data are considered nonexistent.
Parameters:
pKey | The key to search for. |
Returns: If true, the key is available.
QMap<QString, QString> |
[const pure virtual]
Return a map (tree) of entries for all entries in a particular group. Only the actual entry string is returned, none of the other internal data should be included.
Parameters:
pGroup | A group to get keys from. |
Returns: A map of entries in the group specified, indexed by key. The returned map may be empty if the group is not found.
void |
[pure virtual]
Reparses all configuration files. This is useful for programs that use standalone graphical configuration tools. The base method implemented here only clears the group list and then appends the default group.
Derivative classes should clear any internal data structures and then simply call parseConfigFiles() when implementing this method.
enum |
Possible return values for getConfigState().
ConfigState |
[const]
Retrieve the state of the app-config object.
Possible return values are NoAccess (the application-specific config file could not be opened neither read-write nor read-only), ReadOnly (the application-specific config file is opened read-only, but not read-write) and ReadWrite (the application-specific config file is opened read-write).
void |
[protected]
Read the locale and put in the configuration data struct. Note that this should be done in the constructor, but this is not possible due to some mutual dependencies in KApplication::init()
void |
[protected virtual]
Sets the global dirty flag of the config object
Parameters:
_bDirty | How to mark the object's dirty status |
void |
[protected virtual]
Parse all configuration files for a configuration object.
The actual parsing is done by the associated KConfigBackEnd.
KEntryMap |
[protected const pure virtual]
Returns an map (tree) of the entries in the specified group. This may or may not return all entries that belong to the config object. The only guarantee that you are given is that any entries that are dirty (i.e. modified and not yet written back to the disk) will be contained in the map. Some derivative classes may choose to return everything.
Do not use this function, the implementation / return type are subject to change.
Parameters:
pGroup | The group to provide a KEntryMap for. |
Returns: The map of the entries in the group.
KEntryMap |
[protected const pure virtual]
Returns an map (tree) of the entries in the tree.
Do not use this function, the implementation / return type are subject to change.
Returns: A map of the entries in the tree.
void |
[protected pure virtual]
Insert a key,value pair into the internal storage mechanism of the configuration object. Classes that derive from KConfigBase will need to implement this method in a storage-specific manner.
Do not use this function, the implementation / return type are subject to change.
Parameters:
_key | The key to insert. It contains information both on the group of the key and the key itself. If the key already exists, the old value will be replaced. |
_data | the KEntry that is to be stored. |
KEntry |
[protected const pure virtual]
Look up an entry in the config object's internal structure. Classes that derive from KConfigBase will need to implement this method in a storage-specific manner.
Do not use this function, the implementation and return type are subject to change.
Parameters:
_key | The key to look up It contains information both on the group of the key and the entry's key itself. |
Returns: The KEntry value (data) found for the key. KEntry.aValue
will be the null string if nothing was located.
KConfigBackEnd * |
[protected]
A back end for loading/saving to disk in a particular format.