[QGIS Commit] r14982 - docs/trunk/english_us/developer_cookbook/source

[svn_qgis at osgeo.org]

Author: wonder
Date: 2010-12-29 12:27:03 -0800 (Wed, 29 Dec 2010)
New Revision: 14982

Added:
   docs/trunk/english_us/developer_cookbook/source/settings.rst
Modified:
   docs/trunk/english_us/developer_cookbook/source/index.rst
Log:
Added a section about saving and loading settings


Modified: docs/trunk/english_us/developer_cookbook/source/index.rst
===================================================================
--- docs/trunk/english_us/developer_cookbook/source/index.rst	2010-12-29 15:29:02 UTC (rev 14981)
+++ docs/trunk/english_us/developer_cookbook/source/index.rst	2010-12-29 20:27:03 UTC (rev 14982)
@@ -21,6 +21,7 @@
    composer
    expressions
    measure
+   settings
    pluginlayer
    plugins
 

Added: docs/trunk/english_us/developer_cookbook/source/settings.rst
===================================================================
--- docs/trunk/english_us/developer_cookbook/source/settings.rst	                        (rev 0)
+++ docs/trunk/english_us/developer_cookbook/source/settings.rst	2010-12-29 20:27:03 UTC (rev 14982)
@@ -0,0 +1,71 @@
+
+.. settings:
+
+Reading And Storing Settings
+============================
+
+Many times it is useful for a plugin to save some variables so that the user does not have to enter or select them again next time the plugin is run.
+
+These variables can be saved a retrieved with help of Qt and QGIS API. For each variable, you should pick a key that will be used to access the
+variable - for user's favourite color you could use key "favourite_color" or any other meaningful string. It is recommended to give some structure
+to naming of keys.
+
+We can make difference between several types of settings:
+
+* **global settings** - they are bound to the user at particular machine. QGIS itself stores a lot of global settings,
+  for example, main window size or default snapping tolerance. This functionality is provided directly by Qt framework by the means of QSettings class.
+  By default, this class stores settings in system's "native" way of storing settings, that is - registry (on Windows), .plist file (on Mac OS X) or .ini file (on Unix).
+  The `QSettings documentation <http://doc.qt.nokia.com/stable/qsettings.html>`_ is comprehensive, so we will provide just a simple example::
+
+    def store():
+      s = QSettings()
+      s.setValue("myplugin/mytext", "hello world")
+      s.setValue("myplugin/myint",  10)
+      s.setValue("myplugin/myreal", 3.14)
+
+    def read():
+      s = QSettings()
+      mytext = s.value("myplugin/mytext", "default text").toString()
+      myint  = s.value("myplugin/myint", 123).toInt()[0]
+      myreal = s.value("myplugin/myreal", 2.71).toDouble()[0]
+  
+  Qt uses QVariant instances for variable values in setValue() and value() methods. Your values are automagically converted from Python to QVariant
+  instances, however the conversion from QVariant to Python is not automatic: that's why we use the to*() methods. Few more things to note here:
+
+  * the second parameter to value() method is optional and states the default value if there is no previous value set
+  * toString() returns a QString instance, not a Python string
+  * toInt() and toDouble() return tuples (value, ok) - the second item indicates True
+    if whether the conversion from QVariant to the number went fine - in this example we ignore that indicator and only take the value.
+  
+
+* **project settings** vary between different projects and therefore they are connected with a project file.
+  Map canvas background or destination coordinate reference system (CRS) are examples - white background and WGS84 might be suitable for one project,
+  while yellow background and UTM projection for another one. An example of usage follows::
+
+    proj = QgsProject.instance()
+
+    # store values
+    proj.writeEntry("myplugin", "mytext", "hello world")
+    proj.writeEntry("myplugin", "myint", 10)
+
+    # read values
+    mytext = proj.readEntry("myplugin", "mytext", "default text")[0]
+    myint = proj.readNumEntry("myplugin", "myint", 123)[0]
+
+  Hopefully the QgsProject class will be updated in future to provide API similar to the one of QSettings class. Due to some limitations of
+  Python bindings, it is not possible to save floating point numbers.
+
+* **map layer settings** - these settings are related to a particular instance of a map layer with a project. They are *not* connected with underlying
+  data source of a layer, so if you create two map layer instances of one shapefile, they will not share the settings. The settings are stored in project
+  file, so if the user opens the project again, the layer-related settings will be there again. This functionality has been
+  added in QGIS v1.4. The API is similar to QSettings - it takes and returns QVariant instances::
+
+   # save a value
+   layer.setCustomProperty("mytext", "hello world")
+
+   # read the value again
+   mytext = layer.customProperty("mytext", "default text").toString()
+
+
+**TODO:**
+   Keys for settings that can be shared among plugins