Skip to content

Commit 920253d

Browse files
committedApr 12, 2013
Documentation updates
1 parent b0d7be1 commit 920253d

File tree

3 files changed

+242
-223
lines changed

3 files changed

+242
-223
lines changed
 

‎src/core/qgsvectorlayer.h

Lines changed: 225 additions & 212 deletions
Original file line numberDiff line numberDiff line change
@@ -143,8 +143,231 @@ struct CORE_EXPORT QgsVectorJoinInfo
143143

144144

145145
/** \ingroup core
146-
* Vector layer backed by a data source provider.
146+
* Represents a vector layer which manages a vector based data sets.
147+
*
148+
* The QgsVectorLayer is instantiated by specifying the name of a data provider,
149+
* such as postgres or wfs, and url defining the specific data set to connect to.
150+
* The vector layer constructor in turn instantiates a QgsVectorDataProvider subclass
151+
* corresponding to the provider type, and passes it the url. The data provider
152+
* connects to the data source.
153+
*
154+
* The QgsVectorLayer provides a common interface to the different data types. It also
155+
* manages editing transactions.
156+
*
157+
*
158+
* The main data providers supported by QGis are listed below.
159+
*
160+
* \section providers Vector data providers
161+
*
162+
* \subsection memory Memory data providerType (memory)
163+
*
164+
* The memory data provider is used to construct in memory data, for example scratch
165+
* data or data generated from spatial operations such as contouring. There is no
166+
* inherent persistent storage of the data. The data source uri is constructed. The
167+
* url specifies the geometry type ("point", "linestring", "polygon",
168+
* "multipoint","multilinestring","multipolygon"), optionally followed by url parameters
169+
* as follows:
170+
*
171+
* - crs=definition
172+
* Defines the coordinate reference system to use for the layer.
173+
* definition is any string accepted by QgsCoordinateReferenceSystem::createFromString()
174+
*
175+
* - index=yes
176+
* Specifies that the layer will be constructed with a spatial index
177+
*
178+
* - field=name:type(length,precision)
179+
* Defines an attribute of the layer. Multiple field parameters can be added
180+
* to the data provider definition. type is one of "integer", "double", "string".
181+
*
182+
* An example url is "Point?crs=epsg:4326&field=id:integer&field=name:string(20)&index=yes"
183+
*
184+
* \subsection ogr OGR data provider (ogr)
185+
*
186+
* Accesses data using the OGR drivers (http://www.gdal.org/ogr/ogr_formats.html). The url
187+
* is the OGR connection string. A wide variety of data formats can be accessed using this
188+
* driver, including file based formats used by many GIS systems, database formats, and
189+
* web services. Some of these formats are also supported by custom data providers listed
190+
* below.
191+
*
192+
* \subsection spatialite Spatialite data provider (spatialite)
193+
*
194+
* Access data in a spatialite database. The url defines the connection parameters, table,
195+
* geometry column, and other attributes. The url can be constructed using the
196+
* QgsDataSourceURI class.
197+
*
198+
* \subsection postgres Postgresql data provider (postgres)
199+
*
200+
* Connects to a postgresql database. The url defines the connection parameters, table,
201+
* geometry column, and other attributes. The url can be constructed using the
202+
* QgsDataSourceURI class.
203+
*
204+
* \subsection mssql Microsoft SQL server data provider (mssql)
205+
*
206+
* Connects to a Microsoft SQL server database. The url defines the connection parameters, table,
207+
* geometry column, and other attributes. The url can be constructed using the
208+
* QgsDataSourceURI class.
209+
*
210+
* \subsection sqlanywhere SQL Anywhere data provider (sqlanywhere)
211+
*
212+
* Connects to an SQLanywhere database. The url defines the connection parameters, table,
213+
* geometry column, and other attributes. The url can be constructed using the
214+
* QgsDataSourceURI class.
215+
*
216+
* \subsection wfs WFS (web feature service) data provider (wfs)
217+
*
218+
* Used to access data provided by a web feature service.
219+
*
220+
* The url can be a HTTP url to a WFS 1.0.0 server or a GML2 data file path.
221+
* Examples are http://foobar/wfs or /foo/bar/file.gml
222+
*
223+
* If a GML2 file path is provided the driver will attempt to read the schema from a
224+
* file in the same directory with the same basename + “.xsd”. This xsd file must be
225+
* in the same format as a WFS describe feature type response. If no xsd file is provide
226+
* then the driver will attempt to guess the attribute types from the file.
227+
*
228+
* In the case of a HTTP URL the ‘FILTER’ query string parameter can be used to filter
229+
* the WFS feature type. The ‘FILTER’ key value can either be a QGIS expression
230+
* or an OGC XML filter. If the value is set to a QGIS expression the driver will
231+
* turn it into OGC XML filter before passing it to the WFS server. Beware the
232+
* QGIS expression filter only supports” =, != ,<,> ,<= ,>= ,AND ,OR ,NOT, LIKE, IS NULL”
233+
* attribute operators, “BBOX, Disjoint, Intersects, Touches, Crosses, Contains, Overlaps, Within”
234+
* spatial binary operators and the QGIS local “geomFromWKT, geomFromGML”
235+
* geometry constructor functions.
236+
*
237+
* Also note:
238+
*
239+
* - You can use various functions available in the QGIS Expression list,
240+
* however the function must exist server side and have the same name and arguments to work.
241+
*
242+
* - Use the special $geometry parameter to provide the layer geometry column as input
243+
* into the spatial binary operators e.g intersects($geometry, geomFromWKT('POINT (5 6)'))
244+
*
245+
* \subsection delimitedtext Delimited text file data provider (delimitedtext)
246+
*
247+
* Accesses data in a delimited text file, for example CSV files generated by
248+
* spreadsheets. The contents of the file are split into columns based on specified
249+
* delimiter characters. Each record may be represented spatially either by an
250+
* X and Y coordinate column, or by a WKT (well known text) formatted columns.
251+
*
252+
* The url defines the filename, the formatting options (how the
253+
* text in the file is divided into data fields, and which fields contain the
254+
* X,Y coordinates or WKT text definition. The options are specified as url query
255+
* items.
256+
*
257+
* At its simplest the url can just be the filename, in which case it will be loaded
258+
* as a CSV formatted file.
259+
*
260+
* The url may include the following items:
261+
*
262+
* - encoding=UTF-8
263+
*
264+
* Defines the character encoding in the file. The default is UTF-8. To use
265+
* the default encoding for the operating system use "System".
266+
*
267+
* - type=(csv|regexp|whitespace|plain)
268+
*
269+
* Defines the algorithm used to split records into columns. Records are
270+
* defined by new lines, except for csv format files for which quoted fields
271+
* may span multiple records. The default type is csv.
272+
*
273+
* -- "csv" splits the file based on three sets of characters:
274+
* delimiter characters, quote characters,
275+
* and escape characters. Delimiter characters mark the end
276+
* of a field. Quote characters enclose a field which can contain
277+
* delimiter characters, and newlines. Escape characters cause the
278+
* following character to be treated literally (including delimiter,
279+
* quote, and newline characters). Escape and quote characters must
280+
* be different from delimiter characters. Escape characters that are
281+
* also quote characters are treated specially - they can only
282+
* escape themselves within quotes. Elsewhere they are treated as
283+
* quote characters. The defaults for delimiter, quote, and escape
284+
* are ',', '"', '"'.
285+
* -- "regexp" splits each record using a regular expression (see QRegExp
286+
* documentation for details).
287+
* -- "whitespace" splits each record based on whitespace (on or more whitespace
288+
* characters. Leading whitespace in the record is ignored.
289+
* -- "plain" is provided for backwards compatibility. It is equivalent to
290+
* CSV except that the default quote characters are single and double quotes,
291+
* and there is no escape characters.
292+
*
293+
* - delimiter=characters
294+
*
295+
* Defines the delimiter characters used for csv and plain type files, or the
296+
* regular expression for regexp type files. It is a literal string of characters
297+
* except that "\t" may be used to represent a tab character.
298+
*
299+
* - quote=characters
300+
*
301+
* Defines the characters that are used as quote characters for csv and plain type
302+
* files.
303+
*
304+
* - escape=characters
305+
*
306+
* Defines the characters used to escape delimiter, quote, and newline characters.
307+
*
308+
* - skipLines=n
309+
*
310+
* Defines the number of lines to ignore at the beginning of the file (default 0)
311+
*
312+
* - useHeader=(yes|no)
313+
*
314+
* Defines whether the first record in the file (after skipped lines) contains
315+
* column names (default yes)
316+
*
317+
* - xField=column yField=column
318+
*
319+
* Defines the name of the columns holding the x and y coordinates for XY point geometries.
320+
* If the useHeader is no (ie there are no column names), then this is the column
321+
* number (with the first column as 1).
322+
*
323+
* - decimalPoint=c
324+
*
325+
* Defines a character that is used as a decimal point in the X and Y columns.
326+
* The defualt is '.'.
327+
*
328+
* - wktField=column
329+
*
330+
* Defines the name of the columns holding the WKT geometry definition for WKT geometries.
331+
* If the useHeader is no (ie there are no column names), then this is the column
332+
* number (with the first column as 1).
333+
*
334+
* - geomType=(point|line|polygon|none)
335+
*
336+
* Defines the geometry type for WKT type geometries. QGis will only display one
337+
* type of geometry for the layer - any others will be ignored when the file is
338+
* loaded. By default the provider uses the type of the first geometry in the file.
339+
* Use geomType to override this type.
340+
*
341+
* geomType can also be set to none, in which case the layer is loaded without
342+
* geometries.
343+
*
344+
* - crs=crsstring
345+
*
346+
* Defines the coordinate reference system used for the layer. This can be
347+
* any string accepted by QgsCoordinateReferenceSystem::createFromString()
348+
*
349+
* - quiet
350+
*
351+
* Errors encountered loading the file will not be reported in a user dialog if
352+
* quiet is included (They will still be shown in the output log).
353+
*
354+
* \subsection gpx GPX data provider (gpx)
355+
*
356+
* Provider reads tracks, routes, and waypoints from a GPX file. The url
357+
* defines the name of the file, and the type of data to retrieve from it
358+
* ("track", "route", or "waypoint").
359+
*
360+
* An example url is "/home/user/data/holiday.gpx?type=route"
361+
*
362+
* \subsection grass Grass data provider (grass)
363+
*
364+
* Provider to display vector data in a GRASS GIS layer.
365+
*
366+
*
367+
*
147368
*/
369+
370+
148371
class CORE_EXPORT QgsVectorLayer : public QgsMapLayer
149372
{
150373
Q_OBJECT
@@ -240,223 +463,13 @@ class CORE_EXPORT QgsVectorLayer : public QgsMapLayer
240463
*
241464
* The QgsVectorLayer is constructed by instantiating a data provider. The provider
242465
* interprets the supplied path (url) of the data source to connect to and access the
243-
* data. Some providers and url formats are described below.
466+
* data.
244467
*
245468
* @param path The path or url of the parameter. Typically this encodes
246469
* parameters used by the data provider as url query items.
247470
* @param baseName The name used to represent the layer in the legend
248471
* @param providerLib The name of the data provider, eg "memory", "postgres"
249472
*
250-
* Data providers
251-
* ==============
252-
*
253-
* Memory data providerType (memory)
254-
* ------------------------
255-
*
256-
* The memory data provider is used to construct in memory data, for example scratch
257-
* data or data generated from spatial operations such as contouring. There is no
258-
* inherent persistent storage of the data. The data source uri is constructed. The
259-
* url specifies the geometry type ("point", "linestring", "polygon",
260-
* "multipoint","multilinestring","multipolygon"), optionally followed by url parameters
261-
* as follows:
262-
*
263-
* - crs=definition
264-
* Defines the coordinate reference system to use for the layer.
265-
* definition is any string accepted by QgsCoordinateReferenceSystem::createFromString()
266-
*
267-
* - index=yes
268-
* Specifies that the layer will be constructed with a spatial index
269-
*
270-
* - field=name:type(length,precision)
271-
* Defines an attribute of the layer. Multiple field parameters can be added
272-
* to the data provider definition. type is one of "integer", "double", "string".
273-
*
274-
* An example url is "Point?crs=epsg:4326&field=id:integer&field=name:string(20)&index=yes"
275-
*
276-
* OGR data provider (ogr)
277-
* -----------------
278-
*
279-
* Accesses data using the OGR drivers (http://www.gdal.org/ogr/ogr_formats.html). The url
280-
* is the OGR connection string.
281-
*
282-
* GDAL data provider (gdal)
283-
* ------------------
284-
*
285-
* Access raster data using the GDAL drivers (http://www.gdal.org/formats_list.html)
286-
*
287-
* Spatialite data provider (spatialite)
288-
* ------------------------
289-
*
290-
* Access data in a spatialite database. The url defines the connection parameters, table,
291-
* geometry column, and other attributes. The url can be constructed using the
292-
* QgsDataSourceURI class.
293-
*
294-
* Postgresql data provider (postgres)
295-
* -------------------------
296-
*
297-
* Connects to a postgresql database. The url defines the connection parameters, table,
298-
* geometry column, and other attributes. The url can be constructed using the
299-
* QgsDataSourceURI class.
300-
*
301-
* Microsoft SQL server data provider (mssql)
302-
* ----------------------------------
303-
*
304-
* Connects to a Microsoft SQL server database. The url defines the connection parameters, table,
305-
* geometry column, and other attributes. The url can be constructed using the
306-
* QgsDataSourceURI class.
307-
*
308-
* SQL Anywhere data provider (sqlanywhere)
309-
* -------------------------
310-
*
311-
* Connects to an SQLanywhere database. The url defines the connection parameters, table,
312-
* geometry column, and other attributes. The url can be constructed using the
313-
* QgsDataSourceURI class.
314-
*
315-
* WMS (web mapping service) data provider (wms)
316-
* ---------------------------------------
317-
*
318-
* Provider for raster data in a supplied by a web mapping service.
319-
*
320-
* The url is the connection string for the WMS service.
321-
*
322-
* WFS (web feature service) data provider (wfs)
323-
* ---------------------------------------
324-
*
325-
* Provider for vector data in a supplied by a web feature service.
326-
*
327-
* The url is the connection string for the WFS service.
328-
*
329-
* WCS (web coverage service) data provider (wcs)
330-
* ----------------------------------------
331-
*
332-
* The url is the connection string for the WCS service.
333-
*
334-
* Delimited text file data provider (delimitedtext)
335-
* ---------------------------------
336-
*
337-
* Access data in a delimited text file, for example CSV files generated by
338-
* spreadsheets. The contents of the file are split into columns based on specified
339-
* delimiter characters. Each record may be represented spatially either by an
340-
* X and Y coordinate column, or by a WKT (well known text) formatted columns.
341-
*
342-
* The url defines the filename, the formatting options (how the
343-
* text in the file is divided into data fields, and which fields contain the
344-
* X,Y coordinates or WKT text definition. The options are specified as url query
345-
* items.
346-
*
347-
* At its simplest the url can just be the filename, in which case it will be loaded
348-
* as a CSV formatted file.
349-
*
350-
* The url may include the following items:
351-
*
352-
* - encoding=UTF-8
353-
*
354-
* Defines the character encoding in the file. The default is UTF-8. To use
355-
* the default encoding for the operating system use "System".
356-
*
357-
* - type=(csv|regexp|whitespace|plain)
358-
*
359-
* Defines the algorithm used to split records into columns. Records are
360-
* defined by new lines, except for csv format files for which quoted fields
361-
* may span multiple records. The default type is csv.
362-
*
363-
* + "csv" splits the file based on three sets of characters:
364-
* delimiter characters, quote characters,
365-
* and escape characters. Delimiter characters mark the end
366-
* of a field. Quote characters enclose a field which can contain
367-
* delimiter characters, and newlines. Escape characters cause the
368-
* following character to be treated literally (including delimiter,
369-
* quote, and newline characters). Escape and quote characters must
370-
* be different from delimiter characters. Escape characters that are
371-
* also quote characters are treated specially - they can only
372-
* escape themselves within quotes. Elsewhere they are treated as
373-
* quote characters. The defaults for delimiter, quote, and escape
374-
* are ',', '"', '"'.
375-
* + "regexp" splits each record using a regular expression (see QRegExp
376-
* documentation for details).
377-
* + "whitespace" splits each record based on whitespace (on or more whitespace
378-
* characters. Leading whitespace in the record is ignored.
379-
* + "plain" is provided for backwards compatibility. It is equivalent to
380-
* CSV except that the default quote characters are single and double quotes,
381-
* and there is no escape characters.
382-
*
383-
* - delimiter=characters
384-
*
385-
* Defines the delimiter characters used for csv and plain type files, or the
386-
* regular expression for regexp type files. It is a literal string of characters
387-
* except that "\t" may be used to represent a tab character.
388-
*
389-
* - quote=characters
390-
*
391-
* Defines the characters that are used as quote characters for csv and plain type
392-
* files.
393-
*
394-
* - escape=characters
395-
*
396-
* Defines the characters used to escape delimiter, quote, and newline characters.
397-
*
398-
* - skipLines=n
399-
*
400-
* Defines the number of lines to ignore at the beginning of the file (default 0)
401-
*
402-
* - useHeader=(yes|no)
403-
*
404-
* Defines whether the first record in the file (after skipped lines) contains
405-
* column names (default yes)
406-
*
407-
* - xField=column yField=column
408-
*
409-
* Defines the name of the columns holding the x and y coordinates for XY point geometries.
410-
* If the useHeader is no (ie there are no column names), then this is the column
411-
* number (with the first column as 1).
412-
*
413-
* - decimalPoint=c
414-
*
415-
* Defines a character that is used as a decimal point in the X and Y columns.
416-
* The defualt is '.'.
417-
*
418-
* - wktField=column
419-
*
420-
* Defines the name of the columns holding the WKT geometry definition for WKT geometries.
421-
* If the useHeader is no (ie there are no column names), then this is the column
422-
* number (with the first column as 1).
423-
*
424-
* - geomType=(point|line|polygon|none)
425-
*
426-
* Defines the geometry type for WKT type geometries. QGis will only display one
427-
* type of geometry for the layer - any others will be ignored when the file is
428-
* loaded. By default the provider uses the type of the first geometry in the file.
429-
* Use geomType to override this type.
430-
*
431-
* geomType can also be set to none, in which case the layer is loaded without
432-
* geometries.
433-
*
434-
* - crs=crsstring
435-
*
436-
* Defines the coordinate reference system used for the layer. This can be
437-
* any string accepted by QgsCoordinateReferenceSystem::createFromString()
438-
*
439-
* - quiet
440-
*
441-
* Errors encountered loading the file will not be reported in a user dialog if
442-
* quiet is included (They will still be shown in the output log).
443-
*
444-
* GPX data provider (gps)
445-
* -----------------
446-
*
447-
* Provider reads tracks, routes, and waypoints from a GPX file. The url
448-
* defines the name of the file, and the type of data to retrieve from it
449-
* ("track", "route", or "waypoint").
450-
*
451-
* An example url is "/home/user/data/holiday.gpx?type=route"
452-
*
453-
* Grass data provider (grass)
454-
* -------------------
455-
*
456-
* Provider to display raster data in a GRASS GIS layer.
457-
*
458-
*
459-
*
460473
*/
461474
QgsVectorLayer( QString path = QString::null, QString baseName = QString::null,
462475
QString providerLib = QString::null, bool loadDefaultStyleFlag = true );

‎src/providers/delimitedtext/qgsdelimitedtextfile.cpp

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -126,9 +126,13 @@ bool QgsDelimitedTextFile::setFromUrl( QUrl &url )
126126

127127
// Prefer simple "type" for delimiter type, but include delimiterType
128128
// as optional name for backwards compatibility
129-
if( url.hasQueryItem("type") )
129+
if( url.hasQueryItem("type") || url.hasQueryItem("delimiterType") )
130130
{
131-
type = url.queryItemValue("type");
131+
if( url.hasQueryItem("type"))
132+
type = url.queryItemValue("type");
133+
else if( url.hasQueryItem("delimiterType") )
134+
type = url.queryItemValue("delimiterType");
135+
132136
// Support for previous version of Qgs - plain chars had
133137
// quote characters ' or "
134138
if( type == "plain" )
@@ -137,10 +141,6 @@ bool QgsDelimitedTextFile::setFromUrl( QUrl &url )
137141
escape="";
138142
}
139143
}
140-
else if( url.hasQueryItem("delimiterType") )
141-
{
142-
type = url.queryItemValue("delimiterType");
143-
}
144144
if( url.hasQueryItem("delimiter") )
145145
{
146146
delimiter = url.queryItemValue("delimiter");
@@ -254,7 +254,7 @@ void QgsDelimitedTextFile::setTypeRegexp( QString regexp )
254254
mDelimRegexp.setPattern(regexp);
255255
mDelimDefinition=regexp;
256256
mParser=&QgsDelimitedTextFile::parseRegexp;
257-
mDefinitionValid = mDelimRegexp.isValid();
257+
mDefinitionValid = regexp.size() > 0 && mDelimRegexp.isValid();
258258
if( ! mDefinitionValid )
259259
{
260260
QgsDebugMsg("Invalid regular expression in delimited text file delimiter: "+regexp);

‎src/providers/delimitedtext/qgsdelimitedtextprovider.h

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -35,13 +35,19 @@ class QgsDelimitedTextFile;
3535
\brief Data provider for delimited text files.
3636
*
3737
* The provider needs to know both the path to the text file and
38-
* the delimiter to use. Since the means to add a layer is farily
38+
* the delimiter to use. Since the means to add a layer is fairly
3939
* rigid, we must provide this information encoded in a form that
4040
* the provider can decipher and use.
41-
* The uri must contain the path and delimiter in this format:
42-
* /full/path/too/delimited.txt?delimiter=<delimiter>
4341
*
44-
* Example uri = "/home/foo/delim.txt?delimiter=|"
42+
* The uri must defines the file path and the parameters used to
43+
* interpret the contents of the file.
44+
*
45+
* Example uri = "/home/foo/delim.txt?delimiter=|"*
46+
*
47+
* For detailed information on the uri format see the QGSVectorLayer
48+
* documentation.
49+
*
50+
4551
*/
4652
class QgsDelimitedTextProvider : public QgsVectorDataProvider
4753
{

0 commit comments

Comments
 (0)
Please sign in to comment.