Outdated version of the documentation. Find the latest one here.

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

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

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

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

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

    • второй параметр метода value() опциональный и содержит значение по умолчанию, на случай если по каким-либо причинам считать значение не удастся

    • toString() возвращает экземпляр QString, а не строку Python

    • toInt() и toDouble() возвращают кортеж (value, ok) — второй элемент имеет значение True если преобразование из QVariant в число прошло успешно — в примере мы игнорируем этот флаг и получаем только значение.

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

    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]
    

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

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

    # 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