From ea318d1431c89e647598c510c4245c6571aa5f46 Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Thu, 26 Jan 2012 23:32:43 -0600 Subject: Update to latest tqt3 automated conversion --- doc/html/ntqsettings.html | 626 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 626 insertions(+) create mode 100644 doc/html/ntqsettings.html (limited to 'doc/html/ntqsettings.html') diff --git a/doc/html/ntqsettings.html b/doc/html/ntqsettings.html new file mode 100644 index 000000000..f827d3619 --- /dev/null +++ b/doc/html/ntqsettings.html @@ -0,0 +1,626 @@ + + + + + +TQSettings Class + + + + + + + +

TQSettings Class Reference

+ +

The TQSettings class provides persistent platform-independent application settings. +More... +

#include <ntqsettings.h> +

List of all member functions. +

Public Members

enum Format { Native = 0, Ini }
enum System { Unix = 0, Windows, Mac }
enum Scope { User, Global }
TQSettings ()
TQSettings ( Format format )
~TQSettings ()
bool writeEntry ( const TQString & key, bool value )
bool writeEntry ( const TQString & key, double value )
bool writeEntry ( const TQString & key, int value )
bool writeEntry ( const TQString & key, const TQString & value )
bool writeEntry ( const TQString & key, const TQStringList & value )
bool writeEntry ( const TQString & key, const TQStringList & value, const TQChar & separator ) (obsolete)
TQStringList entryList ( const TQString & key ) const
TQStringList subkeyList ( const TQString & key ) const
TQStringList readListEntry ( const TQString & key, bool * ok = 0 ) const
TQStringList readListEntry ( const TQString & key, const TQChar & separator, bool * ok = 0 ) const (obsolete)
TQString readEntry ( const TQString & key, const TQString & def = TQString::null, bool * ok = 0 ) const
int readNumEntry ( const TQString & key, int def = 0, bool * ok = 0 ) const
double readDoubleEntry ( const TQString & key, double def = 0, bool * ok = 0 ) const
bool readBoolEntry ( const TQString & key, bool def = FALSE, bool * ok = 0 ) const
bool removeEntry ( const TQString & key )
void insertSearchPath ( System s, const TQString & path )
void removeSearchPath ( System s, const TQString & path )
void setPath ( const TQString & domain, const TQString & product, Scope scope = Global )
void beginGroup ( const TQString & group )
void endGroup ()
void resetGroup ()
TQString group () const

Detailed Description

+ + +The TQSettings class provides persistent platform-independent application settings. +

+ + +

On Unix systems, TQSettings uses text files to store settings. On Windows +systems, TQSettings uses the system registry. On Mac OS X, TQSettings uses +the Carbon preferences API. +

Each setting comprises an identifying key and the data associated with +the key. A key is a unicode string which consists of two or more +subkeys. A subkey is a slash, '/', followed by one or more unicode +characters (excluding slashes, newlines, carriage returns and equals, +'=', signs). The associated data, called the entry or value, may be a +boolean, an integer, a double, a string or a list of strings. Entry +strings may contain any unicode characters. +

If you want to save and restore the entire desktop's settings, i.e. +which applications are running, use TQSettings to save the settings +for each individual application and TQSessionManager to save the +desktop's session. +

Example settings: +

+    /MyCompany/MyApplication/background color
+    /MyCompany/MyApplication/foreground color
+    /MyCompany/MyApplication/geometry/x
+    /MyCompany/MyApplication/geometry/y
+    /MyCompany/MyApplication/geometry/width
+    /MyCompany/MyApplication/geometry/height
+    /MyCompany/MyApplication/recent files/1
+    /MyCompany/MyApplication/recent files/2
+    /MyCompany/MyApplication/recent files/3
+

+ +Each line above is a complete key, made up of subkeys. +

A typical usage pattern for reading settings at application +startup: +

+    TQSettings settings;
+    settings.setPath( "MyCompany.com", "MyApplication" );
+
+    TQString bgColor = settings.readEntry( "/colors/background", "white" );
+    int width = settings.readNumEntry( "/geometry/width", 640 );
+    // ...
+

+ +

A typical usage pattern for saving settings at application exit or +'save preferences': +

+    TQSettings settings;
+    settings.setPath( "MyCompany.com", "MyApplication" );
+
+    settings.writeEntry( "/colors/background", bgColor );
+    settings.writeEntry( "/geometry/width", width );
+    // ...
+

+ +

A key prefix can be prepended to all keys using beginGroup(). The +application of the prefix is stopped using endGroup(). For +example: +

+    TQSettings settings;
+
+    settings.beginGroup( "/MainWindow" );
+        settings.beginGroup( "/Geometry" );
+            int x = settings.readEntry( "/x" );
+            // ...
+        settings.endGroup();
+        settings.beginGroup( "/Toolbars" );
+            // ...
+        settings.endGroup();
+    settings.endGroup();
+

+ +

You can get a list of entry-holding keys by calling entryList(), and +a list of key-holding keys using subkeyList(). +

+    TQStringList keys = settings.entryList( "/MyApplication" );
+    // keys contains 'background color' and 'foreground color'.
+
+    TQStringList keys = settings.entryList( "/MyApplication/recent files" );
+    // keys contains '1', '2' and '3'.
+
+    TQStringList subkeys = settings.subkeyList( "/MyApplication" );
+    // subkeys contains 'geometry' and 'recent files'
+
+    TQStringList subkeys = settings.subkeyList( "/MyApplication/recent files" );
+    // subkeys is empty.
+

+ +

Since settings for Windows are stored in the registry there are +some size limitations as follows: +

A subkey may not exceed 255 characters. +
An entry's value may not exceed 16,300 characters. +
All the values of a key (for example, all the 'recent files' +subkeys values), may not exceed 65,535 characters. +

These limitations are not enforced on Unix or Mac OS X. +

Warning: Creating multiple, simultaneous instances of TQSettings writing +to a text file may lead to data loss! This is a known issue which will +be fixed in a future release of TQt. +

Notes for Mac OS X Applications +

The location where settings are stored is not formally defined by +the CFPreferences API. +

At the time of writing settings are stored (either on a global or +user basis, preferring locally) into a plist file in $ROOT/System/Library/Preferences (in XML format). TQSettings will +create an appropriate plist file (com.<first group name>.plist) +out of the full path to a key. +

For further information on CFPreferences see +Apple's Specifications +

Notes for Unix Applications +

There is no universally accepted place for storing application +settings under Unix. In the examples the settings file will be +searched for in the following directories: +

SYSCONF - the default value is INSTALL/etc/settings +
/opt/MyCompany/share/etc +
/opt/MyCompany/share/MyApplication/etc +
$HOME/.qt +

+When reading settings the files are searched in the order shown +above, with later settings overriding earlier settings. Files for +which the user doesn't have read permission are ignored. When saving +settings TQSettings works in the order shown above, writing +to the first settings file for which the user has write permission. +(INSTALL is the directory where TQt was installed. This can be +modified by using the configure script's -prefix argument ) +

If you want to put the settings in a particular place in the +filesystem you could do this: +

+    settings.insertSearchPath( TQSettings::Unix, "/opt/MyCompany/share" );
+

+ +

But in practice you may prefer not to use a search path for Unix. +For example the following code: +

+    settings.writeEntry( "/MyApplication/geometry/width", width );
+

+ +will end up writing the "geometry/width" setting to the file +$HOME/.qt/myapplicationrc (assuming that the application is +being run by an ordinary user, i.e. not by root). +

For cross-platform applications you should ensure that the +Windows size limitations are not exceeded. +

Warning: TQSettings doesn't write the settings until it is destroyed so +you should construct the TQSettings object on the stack. +

Member Type Documentation

TQSettings::Format

+ +

TQSettings::Native - Store the settings in a platform dependent location +
TQSettings::Ini - Store the settings in a text file +

TQSettings::Scope

+ +

TQSettings::Global - Save settings as global as possible +
TQSettings::User - Save settings in user space +

TQSettings::System

+ +

TQSettings::Mac - Macintosh execution environments +
TQSettings::Unix - Mac OS X, Unix, Linux and Unix-like execution environments +
TQSettings::Windows - Windows execution environments +

Member Function Documentation

TQSettings::TQSettings () +

+Creates a settings object. +

Be aware that you must call setPath() or insertSearchPath() before +you can use the TQSettings object. + +

TQSettings::TQSettings ( Format format ) +

+Creates a settings object. If format is 'Ini' the settings will +be stored in a text file, using the Unix strategy (see above). If format +is 'Native', the settings will be stored in a platform specific way +(ie. the Windows registry). +

Be aware that you must call setPath() or insertSearchPath() before +you can use the TQSettings object. + +

TQSettings::~TQSettings () +

+Destroys the settings object. All modifications made to the settings +will automatically be saved. +

void TQSettings::beginGroup ( const TQString & group ) +

+Appends group to the current key prefix. +

+    TQSettings settings;
+    settings.beginGroup( "/MainWindow" );
+    // read values
+    settings.endGroup();
+

+ + +

void TQSettings::endGroup () +

+Undo previous calls to beginGroup(). Note that a single beginGroup("a/b/c") is undone +by a single call to endGroup(). +

+    TQSettings settings;
+    settings.beginGroup( "/MainWindow/Geometry" );
+    // read values
+    settings.endGroup();
+

+ + +

TQStringList TQSettings::entryList ( const TQString & key ) const +

+Returns a list of the keys which contain entries under key. Does not return any keys that contain subkeys. +

Example settings: +

+    /MyCompany/MyApplication/background color
+    /MyCompany/MyApplication/foreground color
+    /MyCompany/MyApplication/geometry/x
+    /MyCompany/MyApplication/geometry/y
+    /MyCompany/MyApplication/geometry/width
+    /MyCompany/MyApplication/geometry/height
+

+ +

+    TQStringList keys = settings.entryList( "/MyCompany/MyApplication" );
+

+ +

In the above example, keys will contain 'background color' and +'foreground color'. It will not contain 'geometry' because this key +contains subkeys not entries. +

To access the geometry values, you could either use subkeyList() +to read the keys then read each entry, or simply read each entry +directly by specifying its full key, e.g. +"/MyCompany/MyApplication/geometry/y". +

TQString TQSettings::group () const +

+Returns the current key prefix, or a null string if there is no key prefix set. +

void TQSettings::insertSearchPath ( System s, const TQString & path ) +

+Inserts path into the settings search path. The semantics of path depends on the system s. It is usually easier and better to +use setPath() instead of this function. +

When s is Windows and the execution environment is not +Windows the function does nothing. Similarly when s is Unix and +the execution environment is not Unix the function does nothing. +

When s is Windows, and the execution environment is Windows, the +search path list will be used as the first subfolder of the "Software" +folder in the registry. +

When reading settings the folders are searched forwards from the +first folder (listed below) to the last, returning the first +settings found, and ignoring any folders for which the user doesn't +have read permission. +

HKEY_CURRENT_USER/Software/MyCompany/MyApplication +
HKEY_LOCAL_MACHINE/Software/MyCompany/MyApplication +
HKEY_CURRENT_USER/Software/MyApplication +
HKEY_LOCAL_MACHINE/Software/MyApplication +

+  TQSettings settings;
+  settings.insertSearchPath( TQSettings::Windows, "/MyCompany" );
+  settings.writeEntry( "/MyApplication/Tip of the day", TRUE );
+

+ +The code above will write the subkey "Tip of the day" into the first of the registry folders listed below that is found and for +which the user has write permission. +

HKEY_LOCAL_MACHINE/Software/MyCompany/MyApplication +
HKEY_CURRENT_USER/Software/MyCompany/MyApplication +
HKEY_LOCAL_MACHINE/Software/MyApplication +
HKEY_CURRENT_USER/Software/MyApplication +

+If a setting is found in the HKEY_CURRENT_USER space, this setting +is overwritten independently of write permissions in the +HKEY_LOCAL_MACHINE space. +

When s is Unix, and the execution environment is Unix, the +search path list will be used when trying to determine a suitable +filename for reading and writing settings files. By default, there are +two entries in the search path: +

SYSCONF - where SYSCONF is a directory specified when +configuring TQt; by default it is INSTALL/etc/settings. +
$HOME/.qt/ - where $HOME is the user's home directory. +

All insertions into the search path will go before $HOME/.qt/. +For example: +

+  TQSettings settings;
+  settings.insertSearchPath( TQSettings::Unix, "/opt/MyCompany/share/etc" );
+  settings.insertSearchPath( TQSettings::Unix, "/opt/MyCompany/share/MyApplication/etc" );
+  // ...
+

+ +Will result in a search path of: +

SYSCONF +
/opt/MyCompany/share/etc +
/opt/MyCompany/share/MyApplication/etc +
$HOME/.qt +

Note that paths in the file system are not created by this +function, so they must already exist to be useful. +

Settings under Unix are stored in files whose names are based on the +first subkey of the key (not including the search path). The algorithm +for creating names is essentially: lowercase the first subkey, replace +spaces with underscores and add 'rc', e.g. +/MyCompany/MyApplication/background color will be stored in +myapplicationrc (assuming that /MyCompany is part of +the search path). +

bool TQSettings::readBoolEntry ( const TQString & key, bool def = FALSE, bool * ok = 0 ) const +

+ +

Reads the entry specified by key, and returns a bool, or the +default value, def, if the entry couldn't be read. +If ok is non-null, *ok is set to TRUE if the key was read, FALSE +otherwise. +

See also readEntry(), readNumEntry(), readDoubleEntry(), writeEntry(), and removeEntry(). + +

double TQSettings::readDoubleEntry ( const TQString & key, double def = 0, bool * ok = 0 ) const +

+ +

Reads the entry specified by key, and returns a double, or the +default value, def, if the entry couldn't be read. +If ok is non-null, *ok is set to TRUE if the key was read, FALSE +otherwise. +

See also readEntry(), readNumEntry(), readBoolEntry(), writeEntry(), and removeEntry(). + +

TQString TQSettings::readEntry ( const TQString & key, const TQString & def = TQString::null, bool * ok = 0 ) const +

+ +

Reads the entry specified by key, and returns a TQString, or the +default value, def, if the entry couldn't be read. +If ok is non-null, *ok is set to TRUE if the key was read, FALSE +otherwise. +

See also readListEntry(), readNumEntry(), readDoubleEntry(), readBoolEntry(), writeEntry(), and removeEntry(). + +

TQStringList TQSettings::readListEntry ( const TQString & key, bool * ok = 0 ) const +

+ +Reads the entry specified by key as a string. If ok is not +0, *ok is set to TRUE if the key was read, otherwise *ok is +set to FALSE. +

Note that if you want to iterate over the list, you should iterate +over a copy, e.g. +

+    TQStringList list = mySettings.readListEntry( "recentfiles" );
+    TQStringList::Iterator it = list.begin();
+    while( it != list.end() ) {
+        myProcessing( *it );
+        ++it;
+    }
+

+ +

See also readEntry(), readDoubleEntry(), readBoolEntry(), writeEntry(), removeEntry(), and TQStringList::split(). + +

TQStringList TQSettings::readListEntry ( const TQString & key, const TQChar & separator, bool * ok = 0 ) const +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code. +

Reads the entry specified by key as a string. The separator +is used to create a TQStringList by calling TQStringList::split(separator, entry). If ok is not 0: *ok is set to TRUE +if the key was read, otherwise *ok is set to FALSE. +

Warning: As the documentation states, TQStringList::split() will +omit empty strings from the list. Because of this, it is +impossible to retrieve identical list data with this function. We +recommend using the readListEntry() and writeEntry() overloads +that do not take a separator argument. +

Note that if you want to iterate over the list, you should iterate +over a copy, e.g. +

+    TQStringList list = mySettings.readListEntry( "size", " " );
+    TQStringList::Iterator it = list.begin();
+    while( it != list.end() ) {
+        myProcessing( *it );
+        ++it;
+    }
+

+ +

See also readEntry(), readDoubleEntry(), readBoolEntry(), writeEntry(), removeEntry(), and TQStringList::split(). + +

int TQSettings::readNumEntry ( const TQString & key, int def = 0, bool * ok = 0 ) const +

+ +

Reads the entry specified by key, and returns an integer, or the +default value, def, if the entry couldn't be read. +If ok is non-null, *ok is set to TRUE if the key was read, FALSE +otherwise. +

See also readEntry(), readDoubleEntry(), readBoolEntry(), writeEntry(), and removeEntry(). + +

bool TQSettings::removeEntry ( const TQString & key ) +

+Removes the entry specified by key. +

Returns true if the entry was successfully removed; otherwise +returns false. Note that removing the last entry in any given +folder, will also remove the folder. +

See also readEntry() and writeEntry(). + +

void TQSettings::removeSearchPath ( System s, const TQString & path ) +

+Removes all occurrences of path (using exact matching) from the +settings search path for system s. Note that the default search +paths cannot be removed. +

void TQSettings::resetGroup () +

+Set the current key prefix to the empty string. + +

void TQSettings::setPath ( const TQString & domain, const TQString & product, Scope scope = Global ) +

+Insert platform-dependent paths from platform-independent information. +

The domain should be an Internet domain name +controlled by the producer of the software, eg. Trolltech products +use "trolltech.com". +

The product should be the official name of the product. +

The scope should be +TQSettings::User for user-specific settings, or +TQSettings::Global for system-wide settings (generally +these will be read-only to many users). +

Not all information is relevant on all systems. + +

TQStringList TQSettings::subkeyList ( const TQString & key ) const +

+Returns a list of the keys which contain subkeys under key. Does not return any keys that contain entries. +

Example settings: +

+    /MyCompany/MyApplication/background color
+    /MyCompany/MyApplication/foreground color
+    /MyCompany/MyApplication/geometry/x
+    /MyCompany/MyApplication/geometry/y
+    /MyCompany/MyApplication/geometry/width
+    /MyCompany/MyApplication/geometry/height
+    /MyCompany/MyApplication/recent files/1
+    /MyCompany/MyApplication/recent files/2
+    /MyCompany/MyApplication/recent files/3
+

+ +

+    TQStringList keys = settings.subkeyList( "/MyCompany/MyApplication" );
+

+ +

In the above example, keys will contain 'geometry' and +'recent files'. It will not contain 'background color' or +'foreground color' because those keys contain entries not +subkeys. To get a list of keys that contain entries rather than +subkeys use entryList() instead. +

Warning: In the above example, if TQSettings is writing to an Ini file, +then a call to +

 subkeyList("/MyCompany")

+ +will return an empty list. This happens because a key like +

 /MyCompany/MyApplication/background color

+ +is written to the file "mycompanyrc", under the section [MyApplication]. +This call is therefore a request to list the sections in an ini file, which +is not supported in this version of TQSettings. This is a known issue which +will be fixed in TQt-4. +

bool TQSettings::writeEntry ( const TQString & key, bool value ) +

+Writes the boolean entry value into key key. The key is +created if it doesn't exist. Any previous value is overwritten by value. +

If an error occurs the settings are left unchanged and FALSE is +returned; otherwise TRUE is returned. +

Warning: On certain platforms, keys are required to contain at least +two components (e.g., "/foo/bar"). This limitation does not apply to +TQt 4. +

See also readListEntry(), readNumEntry(), readDoubleEntry(), readBoolEntry(), and removeEntry(). + +

Example: chart/chartform.cpp. +

bool TQSettings::writeEntry ( const TQString & key, double value ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Writes the double entry value into key key. The key is +created if it doesn't exist. Any previous value is overwritten by value. +

If an error occurs the settings are left unchanged and FALSE is +returned; otherwise TRUE is returned. +

See also readListEntry(), readNumEntry(), readDoubleEntry(), readBoolEntry(), and removeEntry(). + +

bool TQSettings::writeEntry ( const TQString & key, int value ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Writes the integer entry value into key key. The key is +created if it doesn't exist. Any previous value is overwritten by value. +

If an error occurs the settings are left unchanged and FALSE is +returned; otherwise TRUE is returned. +

See also readListEntry(), readNumEntry(), readDoubleEntry(), readBoolEntry(), and removeEntry(). + +

bool TQSettings::writeEntry ( const TQString & key, const TQString & value ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Writes the string entry value into key key. The key is +created if it doesn't exist. Any previous value is overwritten by value. If value is an empty string or a null string the key's +value will be an empty string. +

If an error occurs the settings are left unchanged and FALSE is +returned; otherwise TRUE is returned. +

See also readListEntry(), readNumEntry(), readDoubleEntry(), readBoolEntry(), and removeEntry(). + +

bool TQSettings::writeEntry ( const TQString & key, const TQStringList & value ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Writes the string list entry value into key key. The key +is created if it doesn't exist. Any previous value is overwritten +by value. +

If an error occurs the settings are left unchanged and FALSE is +returned; otherwise returns TRUE. +

See also readListEntry(), readNumEntry(), readDoubleEntry(), readBoolEntry(), and removeEntry(). + +

bool TQSettings::writeEntry ( const TQString & key, const TQStringList & value, const TQChar & separator ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code. +

Writes the string list entry value into key key. The key +is created if it doesn't exist. Any previous value is overwritten +by value. The list is stored as a sequence of strings separated +by separator (using TQStringList::join()), so none of the +strings in the list should contain the separator. If the list is +empty or null the key's value will be an empty string. +

Warning: The list should not contain empty or null strings, as +readListEntry() will use TQStringList::split() to recreate the +list. As the documentation states, TQStringList::split() will omit +empty strings from the list. Because of this, it is impossible to +retrieve identical list data that is stored with this function. +We recommend using the writeEntry() and readListEntry() overloads +that do not take a separator argument. +

If an error occurs the settings are left unchanged and FALSE is +returned; otherwise returns TRUE. +

See also readListEntry(), readNumEntry(), readDoubleEntry(), readBoolEntry(), removeEntry(), and TQStringList::join(). + + +

+ +

Trademarks +

TQt 3.3.8

+ -- cgit v1.2.1