Skip to contents

Add a Background Vector Layer to a QGIS Project

Source: R/rfp_qgs_vector_add.R
rfp_qgs_vector_add.Rd

Writes a <maplayer> and its layer-tree entry into an existing .qgs, so a vector layer added to a project after creation becomes visible without a QGIS Desktop round trip. The counterpart of rfp_qgs_raster_add() for vectors, and of rfp_qgs_form_add() for layers that are not forms.

Usage

rfp_qgs_vector_add(
  qgs,
  gpkg,
  table = NULL,
  name = NULL,
  qml = NULL,
  geometry = NULL,
  subset = NULL,
  group,
  position = c("bottom", "top"),
  visible = TRUE,
  themes = "all",
  above = NULL
)

Arguments

qgs

Character. Path to the project .qgs.

gpkg

Character vector. Path(s) to the GeoPackage(s), absolute or relative to the project directory.

table

Character vector. Table inside each GeoPackage. NULL (default) uses the file stem, which is the rfp split-layout convention (<schema>.<table>.gpkg holds <schema>.<table>).

name

Character vector. Display name in the layer tree. NULL (default) uses table.

qml

Character vector. Style to apply. NULL (default) looks for a .qml beside the GeoPackage.

geometry

Character vector, one of "Point", "Line", "Polygon". NULL (default) reads it from the GeoPackage - from gpkg_geometry_columns when that declares a concrete type, and otherwise from a feature, since most rfp-written layers declare GEOMETRY.

subset

Character vector. A provider filter - the SQL WHERE clause the OGR provider applies, written into the datasource as |subset=<expr>. NULL (default) or NA means no filter. Quote string literals with single quotes: a double-quoted token is an SQL identifier, and one that names no column is refused (#318).

Several filtered views of one table are several layers, so repeat the GeoPackage path - the call is vectorized over gpkg. Each needs its own name: a layer id is a digest of the name and the path, not the subset.

group

Character. Layer-tree group to insert into. Required. It used to default to NULL, documented as inserting at the root; measured, it created an unnamed group at the END of the tree - after every named group and therefore under the basemaps, where nothing draws (#213). There is no correct root-level placement either, so the argument is required and an unknown project is answered with the groups it does have.

position

"bottom" (default) or "top" within the group. Background layers belong under the data they provide context for, which is the opposite of a form.

visible

Logical. Checked in the layer tree.

themes

Character. Map themes to join, or "all".

above

Character. Insert directly above this layer id in the ordering lists - see rfp_qgs_raster_add().

Value

Invisibly, a character vector of the layer ids written (NA for a layer already present).

Details

Vectorized over gpkg: several layers can be added in one call, and each is inserted in the order given.

A layer with no style draws as a default thin line or dot. QGIS stores a style in the project when a layer is added and never re-queries the data, so a layer_styles table in the GeoPackage does not help here (see the styling notes in the package README). Pass qml =, or put a .qml beside the GeoPackage and it is picked up automatically.

See also

Other qgs: rfp_qgs_form_add(), rfp_qgs_layer_rm(), rfp_qgs_preview_set(), rfp_qgs_raster_add(), rfp_qgs_service_add(), rfp_qgs_service_rm(), rfp_qgs_services(), rfp_qgs_style_export(), rfp_qgs_style_set(), rfp_qgs_subset_get(), rfp_qgs_subset_set(), rfp_qgs_theme_add(), rfp_qgs_theme_lookup(), rfp_qgs_theme_names(), rfp_qgs_theme_rm(), rfp_qgs_theme_set(), rfp_qgs_theme_unbury(), rfp_qgs_themes(), rfp_qwc_config_create(), rfp_raster_style_path(), rfp_raster_styles()

Examples

if (FALSE) { # \dontrun{
rfp_qgs_vector_add(
  "project.qgs",
  "background_layers/osm.trail.gpkg",
  name = "Trails",
  group = "Roads,Railways,Pipelines",
  qml = system.file("extdata", "styles", "vector", "osm.trail.qml",
                    package = "rfp")
)
} # }