Skip to content
Permalink
Browse files

added documentation to the QgsStyleV2 functions

  • Loading branch information
tecoholic committed Aug 22, 2012
1 parent a205034 commit 4db68570c0d9ef91854e4b9580c41932cd970a76
Showing with 153 additions and 44 deletions.
  1. +153 −44 src/core/symbology-ng/qgsstylev2.h
@@ -33,6 +33,26 @@ class QDomElement;

typedef QMap<QString, QgsVectorColorRampV2* > QgsVectorColorRampV2Map;
typedef QMap<int, QString> QgsSymbolGroupMap;

/*!
* A multimap to hold the smart group conditions as constraint and parameter pairs.
* Both the key and the value of the map are QString. The key is the constraint of the condition and the value is the parameter which is applied for the constraint.
*
* The supported constraints are:
* tag -> symbol has the tag matching the parameter
* !tag -> symbol doesnot have the tag matching the parameter
* group -> symbol belongs to group specified by the parameter
* !group -> symbol doesn't belong to the group specified by the parameter
* name -> symbol has a part of its name matching the parameter
* !name -> symbol doesn't have any part of the name matching the parameter
*
* Example Usage:
* QgsSmartConditionMap conditions;
* conditions.insert( "tag", "red" ); // adds the condition: Symbol has the tag red
* conditions.insert( "!name", "way" ); // add the condition: Symbol doesn't have any part of its name matching `way`
*
* \note This is a Multimap, which means it will contain multiple values for the same key.
*/
typedef QMultiMap<QString, QString> QgsSmartConditionMap;

// enumerators representing sqlite DB columns
@@ -43,7 +63,12 @@ enum TagmapTable { TagmapTagId, TagmapSymbolId };
enum ColorrampTable { ColorrampId, ColorrampName, ColorrampXML, ColorrampGroupId };
enum SmartgroupTable { SmartgroupId, SmartgroupName, SmartgroupXML };

// Enums for types
//! Enum for Entities involved in a style
/*!
The enumarator is used for identifying the entity being operated on when generic
database functions are being run.
\sa group(), rename(), remove(), symbolsOfGroup(), symbolsWithTag(), symbolsOfSmartgroup()
*/
enum StyleEntity { SymbolEntity, GroupEntity, TagEntity, ColorrampEntity, SmartgroupEntity };

class CORE_EXPORT QgsStyleV2
@@ -53,15 +78,80 @@ class CORE_EXPORT QgsStyleV2
QgsStyleV2();
~QgsStyleV2();

//! return default application-wide style
static QgsStyleV2* defaultStyle();
//! add color ramp to style. takes ramp's ownership
bool addColorRamp( QString name, QgsVectorColorRampV2* colorRamp );

//! remove all contents of the style
void clear();
//! adds a new group and returns the group's id
/*!
* \param groupname the name of the new group as QString
* \param parent is the id of the parent group when a subgrouo is to be created. By default it is 0 indicating it is not a sub-group
* \return returns an int, which is the DB id of the new group created, 0 if the group couldn't be created
*/
int addGroup( QString groupName, int parent = 0 );

//! adds new smartgroup to the database and returns the id
/*!
* \param name is the name of the new Smart Group to be added
* \param op is the operator between the conditions; AND/OR as QString
* \param conditions are the smart group conditions
*/
int addSmartgroup( QString name, QString op, QgsSmartConditionMap conditions );

//! add symbol to style. takes symbol's ownership
bool addSymbol( QString name, QgsSymbolV2* symbol );

//! adds a new tag and returns the tag's id
/*!
* \param tagName the name of the new tag to be created
* \return returns an int, which is the DB id of the new tag created, 0 if the tag couldn't be created
*/
int addTag( QString tagName );

//! return a map of groupid and names for the given parent
QgsSymbolGroupMap childGroupNames( QString parent = "" );

//! remove all contents of the style
void clear();

//! return a NEW copy of color ramp
QgsVectorColorRampV2* colorRamp( QString name );

//! return count of color ramps
int colorRampCount();

//! return a list of names of color ramps
QStringList colorRampNames();

//! return a const pointer to a symbol (doesn't create new instance)
const QgsVectorColorRampV2* colorRampRef( QString name ) const;

//! return the id in the style database for the given colorramp name
//! returns 0 if not found
int colorrampId( QString name );

//! return default application-wide style
static QgsStyleV2* defaultStyle();

//! tags the symbol with the tags in the list
/*!
* Applies the given tags to the given symbol or colorramp
* \param type is either SymbolEntity or ColorrampEntity
* \param symbol is the name of the symbol or colorramp as QString
* \param tags is the list of the tags that are to be applied as QStringList
* \return returns the success state of the operation
*/
bool tagSymbol( StyleEntity type, QString symbol, QStringList tags );

//! detags the symbol with the given list
/*!
* Removes the given tags for the specified symbol or colorramp
* \param type is either SymbolEntity or ColorrampEntity
* \param symbol is the name of the symbol or colorramp
* \param tags is the list of tags that are to be removed as QStringList
* \return returns the sucess state of the operation
*/
bool detagSymbol( StyleEntity type, QString symbol, QStringList tags );

//! remove symbol from style (and delete it)
bool removeSymbol( QString name );

@@ -84,63 +174,83 @@ class CORE_EXPORT QgsStyleV2
//! return the id in the style database for the given symbol name
//! returns 0 if not found
int symbolId( QString name );
int colorrampId( QString name );

//! return the id in the style database for the given group name
//! return the DB id for the given group name
int groupId( QString group );
//! return the DB id for the given tag name
int tagId( QString tag );
//! return the DB id for the given smartgroup name
int smartgroupId( QString smartgroup );

//! return the all the groups in the style
QStringList groupNames();

//! return a map of groupid and names for the given parent
QgsSymbolGroupMap childGroupNames( QString parent = "" );

//! returns the symbolnames of a given groupid
/*!
* \param type is either SymbolEntity or ColorampEntity
* \param groupid is id of the group to which the symbols belong to, as int
* \return A QStringList of the symbol or colorramp names for the given group id
*/
QStringList symbolsOfGroup( StyleEntity type, int groupid );

//! returns the symbol names with which have the given tag
/*!
* \param type is either SymbolEntity or ColorampEntity
* \param tagid is id of the tag which has been applied over the symbol as int
* \return A QStringList of the symbol or colorramp names for the given tag id
*/
QStringList symbolsWithTag( StyleEntity type, int tagid );
//! adds a new group and returns the group's id
int addGroup( QString groupName, int parent = 0 );
//! adds a new tag and returns the tag's id
int addTag( QString tagName );

//! applies the specifed group to the symbol or colorramp specified by StyleEntity
/*!
* \param type is either SymbolEntity of ColorrampEntity
* \param name is the name of the symbol or coloramp whose group is to be set
* \param groupid is the id of the group to which the entity is assigned
* \return returns the success state as bool
*/
bool group( StyleEntity type, QString name, int groupid );

//! rename the given entity with the specified id
/*!
* \param type is any of the style entites. Refer enum StyleEntity.
* \param id is the DB id of the entity which is to be renamed
* \param newName is the new name of the entity
*/
void rename( StyleEntity type, int id, QString newName );

//! remove the specified entity from the db
/*!
* \param type is any of the style entites. Refer enum StyleEntity.
* \param id is the DB id of the entity to be removed
*/
void remove( StyleEntity type, int id );

//! add the symbol to the DB with the tags
/*!
* \param name is the name of the symbol as QString
* \param symbol is the pointer to the new QgsSymbolV2 being saved
* \param groupid is the id of the group to which the symbol belongs. Pass 0 if it doesn't belong to any group or not known.
* \param tags is a list of tags that are associated with the symbol as a QStringList.
* \return returns the sucess state of the save operation
*/
bool saveSymbol( QString name, QgsSymbolV2* symbol, int groupid, QStringList tags );

//! add the colorramp to the DB
/*!
* \param name is the name of the colorramp as QString
* \param ramp is the pointer to the new QgsVectorColorRampV2 being saved
* \param groupid is the id of the group to which the Color Ramp belongs. Pass 0 if it doesn't belong to any group or not known.
* \param tags is a list of tags that are associated with the color ramp as a QStringList.
* \return returns the sucess state of the save operation
*/
bool saveColorRamp( QString name, QgsVectorColorRampV2* ramp, int groupid, QStringList tags );

//! add color ramp to style. takes ramp's ownership
bool addColorRamp( QString name, QgsVectorColorRampV2* colorRamp );

//! remove color ramp from style (and delete it)
bool removeColorRamp( QString name );

//! change ramp's name
//! @note added in v1.7
bool renameColorRamp( QString oldName, QString newName );

//! return a NEW copy of color ramp
QgsVectorColorRampV2* colorRamp( QString name );

//! return a const pointer to a symbol (doesn't create new instance)
const QgsVectorColorRampV2* colorRampRef( QString name ) const;

//! return count of color ramps
int colorRampCount();

//! return a list of names of color ramps
QStringList colorRampNames();


//! load a file into the style
bool load( QString filename );
@@ -157,19 +267,15 @@ class CORE_EXPORT QgsStyleV2
//! return the names of the symbols which have a matching 'substring' in its defintion
QStringList findSymbols( QString qword );

//! tags the symbol with the tags in the list, the remove flag DE-TAGS
bool tagSymbol( StyleEntity type, QString symbol, QStringList tags );

//! detags the symbol with the given list
bool detagSymbol( StyleEntity type, QString symbol, QStringList tags );

//! return the tags associated with the symbol
/*!
* \param type is either SymbolEntity or ColorrampEntity
* \param symbol is the name of the symbol or color ramp
* \return A QStringList of the tags that have been applied to that symbol/colorramp
*/
QStringList tagsOfSymbol( StyleEntity type, QString symbol );

//! adds the smartgroup to the database and returns the id
int addSmartgroup( QString name, QString op, QgsSmartConditionMap conditions );

//! returns the smart groups map
//! returns the smart groups map with id as key and name as value
QgsSymbolGroupMap smartgroupsListMap();

//! returns the smart groups list
@@ -179,7 +285,7 @@ class CORE_EXPORT QgsStyleV2
QgsSmartConditionMap smartgroup( int id );

//! returns the operator for the smartgroup
//! @note: clumsy implementation TODO create a class for smartgroups
//clumsy implementation TODO create a class for smartgroups
QString smartgroupOperator( int id );

//! returns the symbols for the smartgroup
@@ -205,13 +311,16 @@ class CORE_EXPORT QgsStyleV2

//! convenience function to open the DB and return a sqlite3 object
bool openDB( QString filename );

//! convenience function that would run queries which don't generate return values
//! @param query query to run
//! @param freeQuery release query memory
//! @return success true on success
//! \param query query to run
//! \param freeQuery release query memory
//! \return success true on success
bool runEmptyQuery( char* query, bool freeQuery = true );

//! prepares the complex query for removing a group, so that the children are not abandoned
char* getGroupRemoveQuery( int id );

//! gets the id from the table for the given name from the database, 0 if not found
int getId( QString table, QString name );
};

0 comments on commit 4db6857

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