Finds and retrieves XML nodes or attributes.
qgisxml(xml, name = NULL, attrname = NULL, extractvalue = TRUE) qgisxml.all(xml) qgisxml(xml, name, attrname = NULL) <- value
| xml | an XML chunk of class |
|---|---|
| name | optional: character string denoting an XML tag or attribute name
to be retrieved from the XML chunk. If none is provided, calls
|
| attrname | optional: if the desired field is stored in an XML attribute
whose name is not unique in the XML chunk, disambiguate the attribute by
providing both the tag ( |
| extractvalue | logical: if |
| value | the new value to set the given setting to (will be treated as a character string) |
For qgisxml.all: a data frame giving all configuration options
found in the XML chunk. Otherwise, the value of the setting with the given
name (or NULL if no setting of that name could be found).
Most project, layer and renderer settings in QGIS are stored and loaded in
XML format. Such configuration chunks can be accessed by functions such as
mapLayer.renderer(), which by default return xml_node objects that can
be manipulated using the functions provided by the xml2 package.
Given that most configuration chunks are quite simple, the qgisxml()
function is provided for convenient access and manipulation of XML options
without having to deal with the XML itself. In particular, this function
unifies access to the three main ways in which settings are stored in QGIS
XML chunks:
as the text content of an XML tag (e.g. <minValue>-0.988</minValue>)
as the XML attribute of a tag (e.g. <sizescale scalemethod="diameter"/>)
as a key/value pair in a prop tag (e.g. <prop k="line_style" v="solid"/>)
Given an xml_node, qgisxml.all() will return a data frame representation
of all the config settings (and their current values) in the given XML
chunk. Individual settings can be accessed using qgisxml() with the
name and attrname identifiers shown in this data frame representation,
which should be unambiguous for most simple QGIS configuration chunks. If
the attribute name is unique, the setting can also be accessed by providing
this second name alone (see examples).
The settings in the XML chunks can also be modified using the
qgisxml(name) <- new value syntax, which can assign any character string.
Assigning a new value only modifies the XML locally without doing any
checking for errors, the updated chunk still needs to be passed back to
QGIS (which might fail if any of the new settings can't be parsed). Types
and valid values for the different settings vary wildly (see the Rendering
vignette for examples). Color specifications for example accept string
specifications in r,g,b,a and #rrggbb format, as well as any English
color name understood by Qt's QColor
class (see here for a
non-exhaustive list).
mapLayer.renderer(), mapLayer.style()
# qgisxml() works on xml_node objects, such as are returned by mapLayer.renderer() # and similar functions. here we create one such object straight from plain text xml: x <- xml2::read_xml([1090 chars quoted with ''']) # list all available settings -- attributes and <prop> settings are displayed uniformly qgisxml(x)#> name attrname value #> 1 renderer-v2 forceraster 0 #> 2 renderer-v2 symbollevels 0 #> 3 renderer-v2 type singleSymbol #> 4 renderer-v2 enableorderby 0 #> 5 symbol alpha 1 #> 6 symbol clip_to_extent 1 #> 7 symbol type marker #> 8 symbol name 0 #> 9 layer pass 0 #> 10 layer class SimpleMarker #> 11 layer locked 0 #> 12 layer angle 0 #> 13 layer color 255,0,0,255 #> 14 layer horizontal_anchor_point 1 #> 15 layer joinstyle bevel #> 16 layer name star #> 17 layer offset 0,0 #> 18 layer offset_map_unit_scale 0,0,0,0,0,0 #> 19 layer offset_unit MM #> 20 layer outline_color 0,0,0,255 #> 21 layer outline_style solid #> 22 layer outline_width 0 #> 23 layer outline_width_map_unit_scale 0,0,0,0,0,0 #> 24 layer outline_width_unit MM #> 25 layer scale_method diameter #> 26 layer size 2 #> 27 layer size_map_unit_scale 0,0,0,0,0,0 #> 28 layer size_unit MM #> 29 layer vertical_anchor_point 1 #> 30 sizescale scalemethod diameter# attribute access qgisxml(x, 'alpha')#> [1] "1"# <prop> access qgisxml(x, 'joinstyle')#> [1] "bevel"# non-unique attribute name simply returns first match qgisxml(x, 'name')#> [1] "0"# more specific access by providing tag/parent name + attribute name qgisxml(x, 'layer', 'name')#> [1] "star"# manipulate settings within the xml chunk using the arrow notation qgisxml(x, 'color') <- 'red' qgisxml(x, 'color')#> [1] "red"# at this point the XML has only been modified locally, the updated chunk still # needs to be passed to QGIS (see mapLayer.renderer())