Skip to content
Permalink
Browse files

Further improvements to QgsProject dox

  • Loading branch information
nyalldawson committed Dec 20, 2020
1 parent e0a2b65 commit 62ed3e2a34b966149df19e2bf967945ff4626bf7
Showing with 129 additions and 47 deletions.
  1. +58 −22 python/core/auto_generated/qgsproject.sip.in
  2. +71 −25 src/core/qgsproject.h
@@ -326,7 +326,7 @@ Writes the project to its current associated file (see fileName() ).

bool writeEntry( const QString &scope, const QString &key, bool value ) /PyName=writeEntryBool/;
%Docstring
Write a boolean entry to the project file.
Write a boolean ``value`` to the project file.

Keys are '/'-delimited entries, implying
a hierarchy of keys and corresponding values
@@ -338,11 +338,13 @@ a hierarchy of keys and corresponding values
.. note::

available in Python bindings as writeEntryBool

.. seealso:: :py:func:`readBoolEntry`
%End

bool writeEntry( const QString &scope, const QString &key, double value ) /PyName=writeEntryDouble/;
%Docstring
Write a double entry to the project file.
Write a double ``value`` to the project file.

Keys are '/'-delimited entries, implying
a hierarchy of keys and corresponding values
@@ -354,98 +356,124 @@ a hierarchy of keys and corresponding values
.. note::

available in Python bindings as writeEntryDouble

.. seealso:: :py:func:`readDoubleEntry`
%End

bool writeEntry( const QString &scope, const QString &key, int value );
%Docstring
Write an integer entry to the project file.
Write an integer ``value`` to the project file.

Keys are '/'-delimited entries, implying
a hierarchy of keys and corresponding values

.. note::

The key string must be valid xml tag names in order to be saved to the file.

.. seealso:: :py:func:`readNumEntry`
%End

bool writeEntry( const QString &scope, const QString &key, const QString &value );
%Docstring
Write a string entry to the project file.
Write a string ``value`` to the project file.

Keys are '/'-delimited entries, implying
a hierarchy of keys and corresponding values

.. note::

The key string must be valid xml tag names in order to be saved to the file.

.. seealso:: :py:func:`readEntry`
%End

bool writeEntry( const QString &scope, const QString &key, const QStringList &value );
%Docstring
Write a string list entry to the project file.
Write a string list ``value`` to the project file.

Keys are '/'-delimited entries, implying
a hierarchy of keys and corresponding values

.. note::

The key string must be valid xml tag names in order to be saved to the file.

.. seealso:: :py:func:`readListEntry`
%End

QStringList readListEntry( const QString &scope, const QString &key, const QStringList &def = QStringList(), bool *ok /Out/ = 0 ) const;
%Docstring
Key value accessors
Reads a string list from the specified ``scope`` and ``key``.

:param scope: entry scope (group) name
:param key: entry key name. Keys are '/'-delimited entries, implying a hierarchy of keys and corresponding values.
:param def: default value to return if the specified ``key`` does not exist within the ``scope``.

keys would be the familiar QgsSettings-like '/' delimited entries,
implying a hierarchy of keys and corresponding values
:return: - entry value as a string list
- ok: set to ``True`` if key exists and has been successfully retrieved as a string list
%End

QString readEntry( const QString &scope, const QString &key, const QString &def = QString(), bool *ok /Out/ = 0 ) const;
%Docstring
Reads a string from the specified ``scope`` and ``key``.

:param def: returned value if key doesn't exist
:param scope: entry scope (group) name
:param key: entry key name. Keys are '/'-delimited entries, implying a hierarchy of keys and corresponding values.
:param def: default value to return if the specified ``key`` does not exist within the ``scope``.

:return: - entry value as string from ``scope`` given its ``key``
- ok: set to ``True`` if key exists and has been successfully retrieved
- ok: set to ``True`` if key exists and has been successfully retrieved as a string value
%End

int readNumEntry( const QString &scope, const QString &key, int def = 0, bool *ok /Out/ = 0 ) const;
%Docstring
Reads an integer from the specified ``scope`` and ``key``.

:param def: returned value if key doesn't exist
:param scope: entry scope (group) name
:param key: entry key name. Keys are '/'-delimited entries, implying a hierarchy of keys and corresponding values.
:param def: default value to return if the specified ``key`` does not exist within the ``scope``.

:return: - entry value as integer from ``scope`` given its ``key``
- ok: set to ``True`` if key exists and has been successfully retrieved
- ok: set to ``True`` if key exists and has been successfully retrieved as an integer
%End

double readDoubleEntry( const QString &scope, const QString &key, double def = 0, bool *ok /Out/ = 0 ) const;
%Docstring
Reads a double from the specified ``scope`` and ``key``.

:param def: returned value if key doesn't exist
:param scope: entry scope (group) name
:param key: entry key name. Keys are '/'-delimited entries, implying a hierarchy of keys and corresponding values.
:param default: value to return if the specified ``key`` does not exist within the ``scope``.

:return: - entry value as double from ``scope`` given its ``key``
- ok: set to ``True`` if key exists and has been successfully retrieved
- ok: set to ``True`` if key exists and has been successfully retrieved as a double
%End

bool readBoolEntry( const QString &scope, const QString &key, bool def = false, bool *ok /Out/ = 0 ) const;
%Docstring
Reads a boolean from the specified ``scope`` and ``key``.

:param def: returned value if key doesn't exist
:param scope: entry scope (group) name
:param key: entry key name. Keys are '/'-delimited entries, implying a hierarchy of keys and corresponding values.
:param default: value to return if the specified ``key`` does not exist within the ``scope``.

:return: - entry value as boolean from ``scope`` given its ``key``
- ok: set to ``True`` if key exists and has been successfully retrieved
- ok: set to ``True`` if key exists and has been successfully retrieved as a boolean
%End


bool removeEntry( const QString &scope, const QString &key );
%Docstring
Remove the given key
Remove the given ``key`` from the specified ``scope``.
%End


QStringList entryList( const QString &scope, const QString &key ) const;
%Docstring
Returns keys with values -- do not return keys that contain other keys
Returns a list of child keys with values which exist within the the specified ``scope`` and ``key``.

This method does not return keys that contain other keys. See :py:func:`~QgsProject.subkeyList` to retrieve keys
which contain other keys.

.. note::

@@ -454,7 +482,10 @@ Returns keys with values -- do not return keys that contain other keys

QStringList subkeyList( const QString &scope, const QString &key ) const;
%Docstring
Returns keys with keys -- do not return keys that contain only values
Returns a list of child keys which contain other keys that exist within the the specified ``scope`` and ``key``.

This method only returns keys with keys, it will not return keys that contain only values. See
:py:func:`~QgsProject.entryList` to retrieve keys with values.

.. note::

@@ -463,6 +494,9 @@ Returns keys with keys -- do not return keys that contain only values


void dumpProperties() const;
%Docstring
Dump out current project properties to stderr
%End

QgsPathResolver pathResolver() const;
%Docstring
@@ -481,7 +515,7 @@ Paths written to the project file should be prepared with this method.

QString readPath( const QString &filename ) const;
%Docstring
Turn filename read from the project file to an absolute path
Transforms a ``filename`` read from the project file to an absolute path.
%End

QString error() const;
@@ -497,7 +531,9 @@ Deletes old handler and takes ownership of the new one.

QString layerIsEmbedded( const QString &id ) const;
%Docstring
Returns project file path if layer is embedded from other project file. Returns empty string if layer is not embedded
Returns the source project file path if the layer with matching ``id`` is embedded from other project file.

Returns an empty string if the matching layer is not embedded.
%End


0 comments on commit 62ed3e2

Please sign in to comment.
You can’t perform that action at this time.