.. index:: настройки; чтение, настройки; сохранение

.. settings:

Чтение и сохранение настроек
============================

Часто бывает полезным сохранить некоторые параметры расширения, чтобы
пользователю не приходилось заново вводить или выбирать их при каждом
запуске расширения.

Эти параметры можно сохранять и получать при помощи Qt и QGIS API.
Для каждого параметра необходимо выбрать ключ, который будет использоваться
для доступа к переменной --- так, для предпочитаемого цвета можно использовать
ключ "favorite_color" или любую другую подходящую по смыслу строку. Рекомендуется
придерживаться некоторой системы в именовании ключей.

Необходимо различать следующие типы настроек:

.. index:: настройки; глобальные

* **глобальные настройки** --- они свои для каждого пользователя компьютера.
  QGIS сама хранит множество глобальных настроек, например, размер главного
  окна или порог прилипания. Эта функциональность обеспечивается Qt, точнее
  входящим в ее состав классом :class:`QSettings`. По умолчанию, этот класс
  хранит настройки в "родном" для системы виде --- реестр (для Windows), файл
  .plist (на Mac OS X) или .ini файл (в Unix). Описание `QSettings documentation
  <http://doc.qt.nokia.com/stable/qsettings.html>`_ достаточно обширное,
  поэтому ограничимся простым примером::

    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 использует экземпляры QVariant для значений переменных в методах setValue()
  и value(). Значения переменных автоматически конвертируются из переменных
  Python в экземпляры QVariant, однако обратное преобразование из QVariant
  в Python таковым не является: поэтому используются методы to*(). Также обратите
  внимание на следующие моменты:

  * второй параметр метода value() опциональный и содержит значение по умолчанию,
    на случай если по каким-либо причинам считать значение не удастся
  * toString() возвращает экземпляр QString, а не строку Python
  * toInt() и toDouble() возвращают кортеж (value, ok) --- второй элемент
    имеет значение True если преобразование из QVariant в число прошло
    успешно --- в примере мы игнорируем этот флаг и получаем только значение.

.. index:: настройки; проекта

* **настройки проекта** разные для каждого проекта и поэтому они связаны
  с файлом проекта. Примером могут служить цвет фона карты и используемая
  система координат (CRS) --- в одном проекте может быть белый фон и WGS84,
  а в другом желтый фон и проекция UTM. Пример использования ниже::

    proj = QgsProject.instance()

    # сохранение значение
    proj.writeEntry("myplugin", "mytext", "hello world")
    proj.writeEntry("myplugin", "myint", 10)

    # чтение значений
    mytext = proj.readEntry("myplugin", "mytext", "default text")[0]
    myint = proj.readNumEntry("myplugin", "myint", 123)[0]

  Возможно, в дальнейшем класс :class:`QgsProject` будет обновлен, с тем
  чтобы предоставлять API, похожее на класс :class:`QSettings`. Из-за некоторых
  ограничений привязок Python сохранение чисел с плавающей запятой не возможно.

.. index:: настройки; слоя

* **настройки слоя** --- эти настройки относятся к отдельному экземпляру слоя
  карты. Они *не* связаны с определеным источником данных слоя, поэтому если
  создано два экземпляра слоя из одного shape-файла, они не будут использовать
  эти настройки совместно. Настройки хранятся в файле проекта, поэтому при
  открытии проекта настройки слоя будут восстановлены. Этот функционал добавлен
  в QGIS v1.4. API похоже на используемое в QSettings --- для чтения и записи
  настроек используются экземпляры QVariant::

   # сохранить значение
   layer.setCustomProperty("mytext", "hello world")

   # прочитать значение
   mytext = layer.customProperty("mytext", "default text").toString()


**TODO:**
   Keys for settings that can be shared among plugins