% vim:autoindent:set textwidth=78:

\section{Working with Vector Data}\label{label_workingvector}
\index{vector layers|(}

% when the revision of a section has been finalized,
% comment out the following line:
%\updatedisclaimer


QGIS supports vector data in a number of formats, including those
supported by the OGR library data provider plugin, such as ESRI shapefiles,
\index{shapefiles}\index{ESRI!shapefiles}\index{SHP files}
MapInfo MIF (interchange format)\index{MIF files}\index{MapInfo!MIF files}
and MapInfo TAB (native format).\index{TAB files}\index{MapInfo!TAB files}
You find a list of OGR supported vector formats in Appendix~\ref{appdx_ogr}.

QGIS also supports PostGIS\index{PostGIS}\index{PostgreSQL!PostGIS} layers 
in a PostgreSQL database using the PostgreSQL data provider plugin.
Support for additional data types (eg. delimited text) is provided by 
additional data provider plugins.\index{delimited text}

This section describes how to work with several common formats:
ESRI shapefiles, PostGIS layers, and SpatialLite layers. Many of the
features available in QGIS work the same, regardless of the vector data source.
This is by design and includes the identify, select, labeling and attributes
functions.

Working with GRASS vector data is described in Section \ref{sec:grass}.

\subsection{ESRI Shapefiles}
\index{vector layers!ESRI shapefiles}
\index{shapefiles}
\index{ESRI!shapefiles}
\index{SHP files}

The standard vector file format used in QGIS is the ESRI Shapefile. Support 
is provided by the OGR Simple Feature Library (\url{http://www.gdal.org/ogr/})
\index{OGR}. A shapefile actually consists of several files. The following three are required:
\index{shapefile!format}

\begin{itemize}
\item \filename{.shp} file containing the feature geometries.
\item \filename{.dbf} file containing the attributes in dBase format.
\item \filename{.shx} index file.
\end{itemize}

Shapefiles also can include a file with a \filename{.prj} suffix, which contains
the projection information. While it is very useful to have a projection file, it is not mandatory. A shapefile dataset can contain additional files. For further details see the ESRI technical specification at \url{http://www.esri.com/library/whitepapers/pdfs/shapefile.pdf}.
\index{shapefile!specification}.

\subsubsection{Loading a Shapefile}\label{sec:load_shapefile}

\begin{figure}[ht]
   \begin{center}
   \caption{Add Vector Layer Dialog \nixcaption}\label{fig:addvectorlayer}\smallskip
   \includegraphics[clip=true, width=12cm]{addvectorlayerdialog}
\end{center} 
\end{figure}

\begin{figure}[ht]
   \begin{center}
   \caption{Open an OGR Supported Vector Layer Dialog \nixcaption}\label{fig:openshapefile}\smallskip
   \includegraphics[clip=true, width=14cm]{shapefileopendialog}
\end{center} 
\end{figure}

\begin{figure}[ht]
   \begin{center}
   \caption{QGIS with Shapefile of Alaska loaded \nixcaption}\label{fig:loadedshapefile}\smallskip
   \includegraphics[clip=true, width=16cm]{shapefileloaded}
\end{center} 
\end{figure}

\includegraphics[width=0.7cm]{mActionAddNonDbLayer} To load a shapefile, start
QGIS and click on the \toolbtntwo{mActionAddNonDbLayer}{Add a vector layer}
toolbar button\index{shapefile!loading} or simply type \keystroke{V}. 
This will bring up a new window (see Figure\ref{fig:addvectorlayer}).  

From the available options check \radiobuttonon{File}. Click on \button{Browse}. 
That will bring up a standard open file dialog (see Figure
\ref{fig:openshapefile}) which allows you to navigate the file system and load
a shapefile or other supported data source. 
The selection box \selectstring{Files of type}{\ldots} allows you to preselect some OGR supported file formats.

You can also select the Encoding type for the shapefile if desired.

Selecting a shapefile from the list and clicking \button{Open} loads it into QGIS. Figure
\ref{fig:loadedshapefile} shows QGIS after loading the \filename{alaska.shp} file.


\begin{Tip}\caption{\textsc{Layer Colors}}
\qgistip{When you add a layer to the map, it is assigned a random color. When
adding more than one layer at a time, different colors are assigned to each layer. }
\end{Tip}

Once loaded, you can zoom around the shapefile using the map navigation tools.
To change the symbology of a layer, open the \dialog{Layer Properties} dialog by double
clicking on the layer name or by right-clicking on the name in the legend and
choosing \dropmenuopt{Properties} from the popup menu. See
Section \ref{sec:symbology} for more information on setting symbology of
vector layers.
  
\subsubsection{Improving Performance}

To improve the performance of drawing a shapefile, you can create a spatial
index. A \index{spatial index!shapefiles} spatial index will improve the 
speed of both zooming and panning. Spatial indexes used by QGIS have a 
\filename{.qix} extension.

Use these steps to create the index:

\begin{itemize}
\item Load a shapefile.
\item Open the \dialog{Layer Properties} dialog by double-clicking on the
shapefile name in the legend or by right-clicking and choosing
\dropmenuopt{Properties} from the popup menu.
\item In the tab \tab{General} click the \button{Create Spatial Index} button.
\end{itemize}

\subsubsection{Loading a MapInfo Layer}
\index{vector layers!MapInfo}

To load a MapInfo layer, click on the 
\toolbtntwo{mActionAddNonDbLayer}{Add a vector layer}
toolbar bar button or type \keystroke{V}, change the file type filter to
\selectstring{Files of Type}{[OGR] MapInfo (*.mif
*.tab *.MIF *.TAB)} and select the layer you want to load.

\subsubsection{Loading an ArcInfo Binary Coverage}
\index{vector layers!ArcInfo Binary Coverage}

To load an ArcInfo binary coverage click on the 
\toolbtntwo{mActionAddNonDbLayer}{Add a vector layer}
toolbar button or type \keystroke{V} to open the 
\dialog{Add Vector Layer} dialog.  Select \radiobuttonon{Directory}. Change to \selectstring {Type}{Arc/Ingo Binary Coverage}. 
Navigate to the directory that contains the coverage files and select it.

Similarly, you can load directory based  vector files in the UK National Transfer Format as well as the 
raw TIGER Format of the US Census Bureau.

\subsection{PostGIS Layers}
\index{vector layers!PostGIS|see{PostGIS}}
\index{PostGIS!layers}
\label{label_postgis} 

PostGIS layers are stored in a PostgreSQL database. The advantages of PostGIS
are the spatial indexing, filtering and query capabilities it provides. Using PostGIS,
vector functions such as select and identify work more accurately than with
OGR layers in QGIS.

To use PostGIS layers you must:\index{PostgreSQL!loading layers}

\begin{itemize}
\item Create a stored connection in QGIS to the PostgreSQL database (if one is
not already defined).\index{PostgreSQL!connection}
\item Connect to the database.
\item Select the layer to add to the map.
\item Optionally provide a SQL \usertext{where}
clause to define which features
to load from the layer.
\item Load the layer.
\end{itemize}

\subsubsection{Creating a stored
Connection}\index{PostgreSQL!connection}\label{sec:postgis_stored}

\includegraphics[width=0.7cm]{mActionAddLayer} The first time
you use a PostGIS data source, you must create a connection to the PostgreSQL
database that contains the data. Begin by clicking on the
\toolbtntwo{mActionAddLayer}{Add a PostGIS Layer} toolbar button, selecting the
\dropmenuopttwo{mActionAddLayer}{Add a PostGIS Layer...} option from the \mainmenuopt{Layer} menu or typing
\keystroke{D}. You can also open the open the 
\dialog{Add Vector Layer} dialog and select \radiobuttonon{Database}.
The \dialog{Add PostGIS Table(s)} dialog will
be displayed. To access the connection manager\index{PostgreSQL!connection
manager}, click on the \button{New} button to display the \dialog{Create a New
PostGIS Connection} dialog. The parameters required for a connection are shown
in table \ref{tab:postgis_connection_parms}.

\begin{table}[ht]\index{PostgreSQL!connection parameters}
\centering
\caption{PostGIS Connection
Parameters}\label{tab:postgis_connection_parms}\medskip
 \begin{tabular}{|l|p{5in}|}
\hline Name & A name for this connection. Can be the same as \textsl{Database}.
\\
\hline Host \index{PostgreSQL!host}
& Name of the database host. This must be a resolvable host name the same as
would be used to open a telnet connection or ping the host. If the database is 
on the same computer as QGIS, simply enter 'localhost' here. \\
\hline Database \index{PostgreSQL!database} & Name of the database.  \\
\hline Port \index{PostgreSQL!port}& Port number the PostgreSQL database
server listens on. The default port is 5432.\\
\hline Username \index{PostgreSQL!username}& User name used to login to the
database. \\
\hline Password \index{PostgreSQL!password}& Password used with
\textsl{Username} to connect to the database.\\
\hline SSL mode \index{PostgreSQL!sslmode}& How the SSL connection will be negotiated with the server. These are the options: 
\begin {itemize}
\item disable: only try an unencrypted SSL connection;
\item allow: try a non-SSL connection, if that fails, try an SSL connection;
\item prefer (the default): try an SSL connection, if that fails, try a non-SSL connection;
\item require: only try an SSL connection.
\end {itemize}
Note that massive speedups in PostGIS layer rendering can be achieved by disabling SSL in the connection editor. \\
\hline
\end{tabular}
\end{table}

Optional you can activate follwing checkboxes:

\begin{itemize}
\item \checkbox{Save Password}
\item \checkbox{Only look in the geometry\_columns table}
\item \checkbox{Only look in the 'public' schema}
\end{itemize}

Once all parameters and options are set, you can test the connection by
clicking on the \button{Test Connect} button\index{PostgreSQL!connection!testing}.

\begin{Tip}\caption{\textsc{QGIS User Settings and
Security}}\index{settings}\index{security}
\qgistip{Your customized settings for QGIS are stored based on the operating
system. \nix, the settings are stored in your home directory in
\filename{.qt/qgisrc}. \win, the settings are stored in the registry. Depending on
your computing environment, storing passwords in your QGIS settings may be a
security risk.
}
\end{Tip}

\subsubsection{Loading a PostGIS Layer}\index{PostgreSQL!loading layers}

\includegraphics[width=0.7cm]{mActionAddLayer} Once you have one or more
connections defined, you can load layers from the PostgreSQL database. Of
course this requires having data in PostgreSQL. See Section
\ref{sec:loading_postgis_data} for a discussion on importing data into the
database. 

To load a layer from PostGIS, perform the following steps:

\begin{itemize}
\item If the \dialog{Add PostGIS Table(s)} dialog is not already open, click on the
\toolbtntwo{mActionAddLayer}{Add a PostGIS Layer} toolbar button.
\item Choose the connection from the drop-down list and click \button{Connect}.
\item Find the layer you wish to add in the list of available layers.
\item Select it by clicking on it. You can select multiple layers by holding
down the \keystroke{shift} key while clicking. See Section \ref{sec:query_builder} for
information on using the PostgreSQL Query Builder to further define the layer.
\item Click on the \button{Add} button to add the layer to the map.
\end{itemize}

\begin{Tip}\caption{\textsc{PostGIS Layers}}
\qgistip{Normally a PostGIS layer is defined by an entry in the
geometry\_columns table. From version \OLD % should be 0.9.0 
on, QGIS can load layers that do not have
an entry in the geometry\_columns table. This includes both tables and views.
Defining a spatial view provides a powerful means to visualize your data. Refer
to your PostgreSQL manual for information on creating views.}
\end{Tip}

\subsubsection{Some details about PostgreSQL
layers}\label{sec:postgis_details}
\index{PostgreSQL!layer details}

This section contains some details on how QGIS accesses PostgreSQL
layers. Most of the time QGIS should simply provide you with a list of
database tables that can be loaded, and load them on request. However,
if you have trouble loading a PostgreSQL table into QGIS, the information
below may help you understand any QGIS messages and give you direction on
changing the PostgreSQL table or view definition to allow QGIS to load it.

QGIS requires that PostgreSQL layers contain a column that can be
used as a unique key for the layer. For tables this usually means
that the table needs a primary key, or a column with a unique
constraint on it. In QGIS, this column needs to be of
type int4 (an integer of size 4 bytes). Alternatively the ctid column can be used as primary key. 
If a table lacks these items,
the oid column will be used instead. Performance will be improved if the
column is indexed (note that primary keys are automatically indexed in
PostgreSQL). 

If the PostgreSQL layer is a view, the same requirement exists, but
views don't have primary keys or columns with unique constraints on
them. In this case QGIS will try to find a column in the view that is
derived from a suitable table column. It does this by parsing the view
definition SQL. However there are several aspects of SQL that QGIS ignores
- these include the use of table aliases and columns that are generated by
SQL functions.

If a suitable column cannot be found, QGIS will not load the layer. If this
occurs, the solution is to alter the view so that it does include a suitable
column (a type of int4 and either a primary key or with a unique constraint,
preferably indexed).

When dealing with views, QGIS parses the view definition and

\subsubsection{Importing Data into PostgreSQL}\label{sec:loading_postgis_data}
\index{PostGIS!SPIT!importing data}

\minisec{shp2pgsql}
Data can be imported into PostgreSQL using a number of methods. PostGIS
includes a utility called \filename{shp2pgsql} that can be used to import shapefiles into
a PostGIS enabled database. For example, to import a shapefile named
\filename{lakes.shp}
into a PostgreSQL database named \usertext{gis\_data}, use the following command:

\begin{verbatim} 
  shp2pgsql -s 2964 lakes.shp lakes_new | psql gis_data
\end{verbatim}

This creates a new layer named \usertext{lakes\_new} in the
\usertext{gis\_data} database. The
new layer will have a spatial reference identifier (SRID) of 2964. See Section 
\ref{label_projections} for more information on spatial reference systems and
projections.
\begin{Tip}
\caption{\textsc{Exporting datasets from PostGIS}\index{PostGIS!Exporting}}
\qgistip{Like the import-tool \filename{shp2pgsql} there is also a tool to export
PostGIS-datasets as shapefiles: \filename{pgsql2shp}. This is shipped within your
PostGIS distribution.} 
\end{Tip}

\minisec{SPIT Plugin}
\includegraphics[width=0.7cm]{spiticon} QGIS comes with a
plugin named 
SPIT (Shapefile to PostGIS Import Tool)\index{PostGIS!SPIT}.
SPIT can be used to load multiple shapefiles at one time and includes support
for schemas. To use SPIT, open the Plugin Manager from the \mainmenuopt{Plugins}
menu, check the box next to the \checkbox{SPIT plugin} and click \button{OK}. The SPIT
icon will be added to the plugin toolbar\index{PostGIS!SPIT!loading}. 

To import a shapefile, click on the \toolbtntwo{spiticon}{SPIT} tool in the 
toolbar to open the 
\dialog{SPIT - Shapefile to PostGIS Import Tool} dialog. Select the PostGIS database 
you want to connect to and click on \button{Connect}. Now you can add one or more 
files to the queue by clicking on the \button{Add} button. To process the files, 
click on the \button{OK} button. The progress of the import as well as any 
errors/warnings will be displayed as each shapefile is processed.

\begin{Tip}\caption{\textsc{Importing Shapefiles Containing
PostgreSQL Reserved Words}}\index{PostGIS!SPIT!reserved words}
\qgistip{If a shapefile is added to the queue containing fields that are
reserved words in the PostgreSQL database a dialog will popup showing the
status
of each field. You can edit the field names\index{PostGIS!SPIT!editing field names}
prior to import and change any that are reserved words (or change any other
field names as desired). Attempting to
import a shapefile with reserved words as field names will likely fail.}
\end{Tip} 

\minisec{ogr2ogr}
Beside \filename{shp2pgsql} and \filename{SPIT} there is another tool for feeding
geodata in PostGIS: \filename{ogr2ogr}. This is part of your GDAL installation.
To import a shapefile into PostGIS, do the following:
\begin{verbatim}
  ogr2ogr -f "PostgreSQL" PG:"dbname=postgis host=myhost.de user=postgres \
  password=topsecret" alaska.shp
\end{verbatim}

This will import the shapefile \filename{alaska.shp} into the PostGIS-database
\usertext{postgis}
using the user \usertext{postgres} with the password \usertext{topsecret} on host
\server{myhost.de}.

Note that OGR must be built with PostgreSQL to support PostGIS.
You can see this by typing
\begin{verbatim}
ogrinfo --formats | grep -i post
\end{verbatim}

If you like to use PostgreSQL's \filename{COPY}-command instead of the default
\filename{INSERT INTO} method you can export the following
environment-variable (at least available on \nix and \osx):
\begin{verbatim}
  export PG_USE_COPY=YES
\end{verbatim}

\filename{ogr2ogr} does not create spatial indexes like \filename{shp2pgsl}
does. You need to create them manually using the normal SQL-command
\filename{CREATE INDEX} afterwards as an extra step (as described in the next
section \ref{label_improve}).

\subsubsection{Improving Performance} \label{label_improve}

Retrieving features from a PostgreSQL database can be time consuming,
especially over a network. You can improve the drawing performance of
PostgreSQL layers by ensuring that a \index{PostGIS!spatial index} spatial
index
exists on each layer in the database. PostGIS supports creation of a
\index{PostGIS!spatial index!GiST} GiST
(Generalized Search Tree) index to speed up spatial searches of the data.

The syntax for creating a GiST\footnote{GiST index information is taken from the PostGIS
documentation available at \url{http://postgis.refractions.net}}
index is:

\begin{verbatim}
    CREATE INDEX [indexname] ON [tablename] 
      USING GIST ( [geometryfield] GIST_GEOMETRY_OPS );
\end{verbatim}

Note that for large tables, creating the index can take a long time. Once the
index is created, you should perform a \usertext{VACUUM ANALYZE}. See the
PostGIS documentation \cite{PostGISweb} for more information.

The following is an example of creating a GiST index:
\begin{verbatim}
gsherman@madison:~/current$ psql gis_data
Welcome to psql 8.3.0, the PostgreSQL interactive terminal.

Type:  \copyright for distribution terms
        \h for help with SQL commands
        \? for help with psql commands
        \g or terminate with semicolon to execute query
        \q to quit

gis_data=# CREATE INDEX sidx_alaska_lakes ON alaska_lakes
gis_data-# USING GIST (the_geom GIST_GEOMETRY_OPS);
CREATE INDEX
gis_data=# VACUUM ANALYZE alaska_lakes;
VACUUM
gis_data=# \q
gsherman@madison:~/current$
\end{verbatim}

\subsection{SpatiaLite Layers} 
\index{SpatiaLite layers!properties dialog}
\index{vector layers!SpatlaLIte|see{SpatiaLite}}
\index{SpatiaLite!layers}
\label{label_spatialite} 

\includegraphics[width=0.7cm]{mActionAddSpatiaLiteLayer}
The first time you load data from a Spatialite database, begin by clicking on the 
\toolbtntwo{mActionAddSpatiaLiteLayer}{Add SpatiaLite Layer} toolbar button or by selecting the 
\dropmenuopttwo{mActionAddSpatiaLiteLayer}{Add SpatiaLite Layer...} 
option from the \mainmenuopt{Layer} menu or by typing \keystroke{L}. 
This will bring up a window, which will allow you to either connect to a Spatialite database already known to QGIS, which 
you can choose from the dropdown menu or to define a new connection to a new database. To define a new connection, 
click on \button{New} and use the file browser to point to your SpatiaLite database, 
which is a file with a \filename{.sqlite } extension.

\subsection{The Vector Properties Dialog}\label{sec:vectorprops}
\index{vector layers!properties dialog}

The \dialog{Layer Properties} dialog for a vector layer 
provides information about the layer, symbology
settings and labeling options. If your vector layer has been loaded from a
PostgreSQL / PostGIS datastore, you can also alter the underlying SQL for the
layer - either by hand editing the SQL on the \tab{General} tab or by
invoking the \dialog{Query Builder} dialog on the \tab{General} tab. 
To access the
\dialog{Layer Properties} dialog, double-click on a layer in the legend or right-click on the
layer and select \dropmenuopt{Properties} from the popup menu.

\begin{figure}[H]
   \begin{center}
   \caption{Vector Layer Properties Dialog \nixcaption}\label{fig:vector_symbology}\smallskip
   \includegraphics[clip=true, width=12cm]{vectorLayerSymbology} 
\end{center}  
\end{figure}

\subsubsection{General Tab}\label{vectorgeneraltab}
The \tab{General} tab is essentially like that of the raster dialog. It allows you
to change the display name, set scale dependent rendering options, create a spatial 
index of the vector file (only for OGR supported formats and PostGIS) and view or
change the projection of the specific vetor layer.

The \button{Query Builder} button allows you to create a subset of the features 
in the layer - but this button currently only is available when you open the 
attribute table and select the \button{...} button next to Advanced search.

\subsubsection{Symbology Tab}\label{sec:symbology}
\index{vector layers!symbology}

QGIS supports a number of symbology renderers to control how
vector features are displayed. Currently the following renderers
are available:

\begin{description} 
    \item[Single symbol] - a single style is applied to every
    object in the layer.\index{vector layers!renderers!single symbol}
    \item[Graduated symbol] - objects within the layer are
    displayed with different symbols classified by the values of a
    particular field.\index{vector layers!renderers!graduated symbol}
    \item[Continuous color] - objects within the layer are
    displayed with a spread of colours classified by the numerical
    values within a specified field.\index{vector layers!renderers!continuous
color}
    \item[Unique value] - objects are classified by the unique
    values within a specified field with each value having a
    different symbol.\index{vector layers!renderers!unique value}
\end{description}

To change the symbology for a layer, simply double click on its legend 
entry and the vector \dialog{Layer Properties} dialog will be 
shown.\index{symbology!changing}

\begin{figure}[h]
\centering
\caption{Symbolizing-options \nixcaption}
   \subfigure[Single symbol] {\label{subfig:single_symbol}\includegraphics[clip=true, width=0.4\textwidth]{vectorClassifySingle}}\goodgap
   \subfigure[Graduated symbol] {\label{subfig:graduated_symbol}\includegraphics[clip=true, width=0.4\textwidth]{vectorClassifyGraduated}}\\
   \subfigure[Continous color] {\label{subfig:cont_color}\includegraphics[clip=true, width=0.4\textwidth]{vectorClassifyContinous}}\goodgap
   \subfigure[Unique value] {\label{subfig:unique_val}\includegraphics[clip=true, width=0.4\textwidth]{vectorClassifyUnique}}
\end{figure}

% FIXME: outdated
% Since \usertext{version v0.9} there is a function to use image files stored on 
% your computer as fill pattern for vector layers.

\minisec{Style Options} \label{sec:style_options} \index{vector layers!styles}
Within this dialog you can style your vector layer. Depending on the selected
rendering option you have the possibility to also classify your mapfeatures.

At least the following styling options apply for nearly all renderers:
\begin{description}
 \item[Outline style] - pen-style for your outline of your feature. you can
 also set this to 'no pen'.
 \item[Outline color] - color of the ouline of your feature
 \item[Outline width] - width of your features
 \item[Fill color] - fill-color of your features.
 \item[Fill style] - Style for filling. Beside the given brushes you can
 select \selectstring{Fill style}{? texture} and click the \browsebutton
 button for selecting your own fill-style. Currently the fileformats
 \filename{*.jpeg, *.xpm, and *.png} are supported.
\end{description}

Once you have styled your layer you also could save your layer-style to a
separate file (with \filename{*.qml}-ending).
To do this, use the button \button{Save Style \ldots}. No need to say that
\button{Load Style \ldots} loads your saved layer-style-file.

If you wish to always use a particular style whenever the layer is loaded, 
use the \button{Save As Default} button to make your style the default. Also, 
if you make changes to the style that you are not happy with, use the \button{Restore 
Default Styel} button to revert to your default style.

\minisec{Vector transparency} \label{sec:vect_transparency} \index{vector layers!transparency}
QGIS \CURRENT allows to set a transparency for every vector layer. This can be done with
the slider \slider{Transparency}{0}{20mm} inside the \tab{symbology} tab (see fig. \ref{fig:vector_symbology}).
This is very useful for overlaying several vector layers.

\subsubsection{Metadata Tab}

The \tab{Metadata} tab contains information about the layer, including specifics
about the type and location, number of features, feature type, and the editing
capabilities. The \guiheading{Layer Spatial Reference System} section, providing 
projection information, and the \guiheading{Attribute field info} section,
listing fields and their data types, are displayed 
on this tab. This is a quick way to get information about the layer.

\subsubsection{Labels Tab}

The \tab{Labels} tab allows you to enable labeling features and control a number of
options related to fonts, placement, style, alignment and buffering.

We will illustrate this by labelling the lakes shapefile of the
\filename{qgis\_example\_dataset}:

\begin{enumerate}
\item Load the Shapefile \filename{alaska.shp} and GML file \filename{lakes.gml} in QGIS.
\item Zoom in a bit to your favorite area with some lake.
\item Make the \filename{lakes} layer active.
\item Open the \dialog{Layer Properties} dialog.
\item Click on the \tab{Labels} tab.
\item Check the \checkbox{Display labels} checkbox to enable labeling.
\item Choose the field to label with. 
  We'll use \selectstring{Field containing label}{NAMES}.
\item Enter a default for lakes that have no name. The default label will be
  used each time QGIS encounters a lake with no value in the \guilabel{NAMES} field.
\item If have labels extending over several lines, check \checkbox{Multiline labels?}. 
QGIS will check for a true line return in your label field and insert the line breaks accordingly.
A true line return is a \textbf{single} character \textbackslash n, 
(not two separate characters, like a backlash \textbackslash ~followed by the character n).
\item Click \button{Apply}.
\end{enumerate} 

Now we have labels. How do they look? They are probably too big and poorly
placed in relation to the marker symbol for the lakes.

Select the \tab{Font} entry and use the \button{Font} and \button{Color}
buttons to set the font and color. You can also change the angle and the
placement of the text-label.

To change the position of the text relative to the feature:

\begin{enumerate} 
\item Click on the \tab{Font} entry.
\item Change the placement by selecting one of the radio buttons
in the \classname{Placement} group. To fix our labels, choose the
\radiobuttonon{Right} radio button.
\item the \classname{Font size units} allows you to select between
\radiobuttonon{Points} or \radiobuttonon{Map units}.
\item Click \button{Apply} to see your changes without closing the dialog.
\end{enumerate} 

Things are looking better, but the labels are still too close to the marker. To
fix this we can use the options on the \tab{Position} entry. Here we can add
offsets for the X and Y directions. Adding an X offset of 5 will move our
labels off the marker and make them more readable. Of course if your marker
symbol or font is larger, more of an offset will be required.

The last adjustment we'll make is to \tab{buffer} the labels. This just means
putting a backdrop around them to make them stand out better. To buffer the
lakes labels:

\begin{enumerate}
\item Click the \tab{Buffer} tab.
\item Click the \checkbox{Buffer Labels?} checkbox to enable buffering.
\item Choose a size for the buffer using the spin box.
\item Choose a color by clicking on \button{Color} and choosing your
  favorite from the color selector. You can also set some transparency for the
  buffer if you prefer.
\item Click \button{Apply} to see if you like the changes.
\end{enumerate} 

If you aren't happy with the results, tweak the settings and then test again
by clicking \button{Apply}.

A buffer of 1 points seems to give a good result.
Notice you can also specify the buffer size in map units if that works out
better for you.

The remaining entries inside the \tab{Label} tab allow you control the appearance of the
labels using attributes stored in the layer. The entries beginning with \tab{Data defined} allow you to
set all the parameters for the labels using fields in the layer.

Not that the \tab{Label} tab provides a \classname{preview-box} where your
selected label is shown.

\subsubsection{Actions Tab}\index{actions}\label{label_actions}

QGIS provides the ability to perform an action based on the attributes of a
feature. This can be used to perform any number of actions, for example,
running a program with arguments built from the attributes of a feature or
passing parameters to a web reporting tool.

Actions are useful when you frequently want to run an external application or
view a web page based on one or more values in your vector layer. An example
is performing a search based on an attribute value. This concept is used in 
the following discussion.

\minisec{Defining Actions}\index{actions!defining}

Attribute actions are defined from the vector \dialog{Layer Properties} dialog. To
define an action, open the vector \dialog{Layer Properties} dialog and click on the
\tab{Actions} tab. Provide a descriptive name for the action. The action
itself must contain the name of the application that will be executed when the
action is invoked. You can add one or more attribute field values as arguments
to the application. When the action is invoked any set of characters that
start with a \% followed by the name of a field will be replaced by the value of
that field. The special characters \%\% \index{\%\%}will be replaced by the value
of the field that was selected from the identify results or attribute table (see
Using Actions below).  Double quote marks can be used to group text into a
single argument to the program, script or command. Double quotes will be
ignored if preceded by a backslash.

If you have field names that are substrings of other field names (e.g., \usertext{col1}
and \usertext{col10}) you should
indicate so, by surrounding the field name (and the \% character) with square
brackets (e.g., \usertext{[\%col10]}). This will prevent the \usertext{\%col10} field
name being mistaken for the \usertext{\%col1} field name with a \usertext{0}
on the end. The brackets will be removed by QGIS when it substitutes in the
value of the field. If you want the substituted field to be surrounded by square
brackets, use a second set like this: \usertext{[[\%col10]]}.

The \dialog{Identify Results} dialog box includes a {\em (Derived)} item that
contains information relevant to the layer type. The
values in this item can be accessed in a similar way to the other fields
by using preceeding the derived field name by \usertext{(Derived).}. For
example, a point layer has an \usertext{X} and \usertext{Y} field and the
value of these can be used in the action with \usertext{\%(Derived).X} and
\usertext{\%(Derived).Y}. The derived attributes are only available from the
\dialog{Identify Results} dialog box, not the \dialog{Attribute Table} dialog box.

Two example actions are shown below:\index{actions!examples}

\begin{itemize}
  \item \usertext{konqueror http://www.google.com/search?q=\%nam}
  \item \usertext{konqueror http://www.google.com/search?q=\%\%}
\end{itemize}

In the first example, the web browser konqueror is invoked and passed a URL to
open. The URL performs a Google search on the value of the \usertext{nam} field
from our vector layer. Note that the application or script called by the
action must be in the path or you must provided the full path. To be sure, we could
rewrite the first example as: \usertext{/opt/kde3/bin/konqueror
http://www.google.com/search?q=\%nam}. This will ensure that the konqueror
application will be executed when the action is invoked.

The second example uses the \%\% notation which does not rely on a particular
field for its value. When the action is invoked, the \%\% will be replaced by
the value of the selected field in the identify results or attribute table.

\minisec{Using Actions}\index{actions!using}\label{label_usingactions}
Actions can be invoked from either the \dialog{Identify Results} dialog or an
 \dialog{Attribute Table} dialog. 
(Recall that these dialogs can be opened by clicking
\toolbtntwo{mActionOpenTable}{Identify Features}
or
\toolbtntwo{mActionOpenTable}{Open Table}.)
To invoke an action, 
right click on the
record and choose the action from the popup menu. Actions are listed in the popup
menu by the name you assigned when defining the actions. Click on the action you
wish to invoke.

If you are invoking an action that uses the \%\% notation, right-click on the
field value in the \dialog{Identify Results} dialog or the
\dialog{Attribute Table} dialog that you wish to pass to the application or script.

Here is another example that pulls data out of a vector layer and inserts them
into a file using bash and the \usertext{echo} command (so it will only work
\nix or perhaps \osx). The layer in question has fields for a species name
\usertext{taxon\_name}, latitude \usertext{lat} and longitude
\usertext{long}. I would like to be able to
make a spatial selection of a localities and export these field values to a
text file for the selected record (shown in yellow in the QGIS map area). Here is
the action to achieve this:

\begin{verbatim}
  bash -c "echo \"%taxon_name %lat %long\" >> /tmp/species_localities.txt"
\end{verbatim} 

After selecting a few localities and running the action on each one, opening
the output file will show something like this:

\begin{verbatim}
  Acacia mearnsii -34.0800000000 150.0800000000
  Acacia mearnsii -34.9000000000 150.1200000000
  Acacia mearnsii -35.2200000000 149.9300000000
  Acacia mearnsii -32.2700000000 150.4100000000
\end{verbatim} 

As an exercise we create an action that does a Google search on the 
\filename{lakes} layer. First we need to determine the URL needed to perform a search on a
keyword. This is easily done by just going to Google and doing a simple
search, then grabbing the URL from the address bar in your browser. From this
little effort we see that the format is: \url{http://google.com/search?q=qgis},
where \usertext{qgis} is the search term. Armed with this information, we can
proceed:

\begin{enumerate}
\item Make sure the \filename{lakes} layer is loaded.
\item Open the \dialog{Layer Properties} dialog by double-clicking on the layer in the
  legend or right-click and choose \dropmenuopt{Properties} from the popup menu.
\item Click on the \tab{Actions} tab.
\item Enter a name for the action, for example \usertext{Google Search}.
\item For the action, we need to provide the name of the external program to
  run. In this case, we can use Firefox. If the program is not in
  your path, you need to provide the full path.
\item Following the name of the external application, add the URL used for
  doing a Google search, up to but not included the search term:
  \url{http://google.com/search?q=}
\item The text in the \guilabel{Action} field should now look like this:\\
  \usertext{firefox \url{http://google.com/search?q=}}
\item Click on the drop-down box containing the field names for the
  \usertext{lakes} layer. It's located just to the left of the
  \button{Insert Field} button.
\item From the drop-down box, select \selectstring{}{NAMES} and click \button{Insert Field}.
\item Your action text now looks like this:\\ \usertext{firefox
  \url{http://google.com/search?q=\%NAMES}}
\item Fo finalize the action click the \button{Insert action} button.
\end{enumerate}
 
This completes the action and it is ready to use. The final text of the action
should look like this:

\begin{center}
\usertext{firefox \url{http://google.com/search?q=\%NAMES}}
\end{center}

We can now use the action. Close the \dialog{Layer Properties} dialog and zoom in to an area
of interest. Make sure the \filename{lakes} layer is active and identify a
lake. In the result box you'll now see that our action is visible:

\begin{figure}[H]
   \begin{center}
   \caption{Select feature and choose action \nixcaption}\label{fig:identify_action}\smallskip
   \includegraphics[clip=true, width=8cm]{action_identifyaction} 
\end{center}  
\end{figure}

When we click on the action, it brings up Firefox and navigates to the URL
\url{http://www.google.com/search?q=Tustumena}. It is also possible to add further 
attribute fields to the action. Therefore you can add a ``+'' to the end of the action 
text, select another field and click on \button{Insert Field}. In this example there 
is just no other field available that would make sense to search for.

You can define multiple actions for a layer and each will show up in the
\dialog{Identify Results} dialog. You can also invoke actions from the attribute table
by selecting a row and right-clicking, then choosing the action from the popup
menu.

You can think of all kinds of uses for actions. For example, if you have a point layer
containing locations of images or photos along with a file name, you could
create an action to launch a viewer to display the image. You could also use
actions to launch web-based reports for an attribute field or combination of
fields, specifying them in the same way we did in our Google search example.

\subsubsection{Attributes Tab}\index{attributes}\label{label_attributes}
Within the \tab{Attributes} tab the attributes of the selected dataset can be
manipulated. The buttons \button{New Column} and \button{Delete Column} can be
used, when the dataset is in editing mode. At the moment only columns from 
PostGIS layers can be edited, because this feature is not yet supported by 
the OGR library. 

The \button{Toggle editing mode} button toggles this mode.

\minisec{edit widget}

Within the \tab{Attributes} tab you also find an \texttt{edit widget} and a 
\texttt{value} column. These two columns can be used to define values or a range 
of values that are allowed to be added to the specific attribute table columns. 
They are used to produce different edit widgets in the attribute dialog. These 
widgets are:

\begin{itemize}
\item line edit: an edit field which allows to enter simple text (or restrict to 
numbers for numeric attributes).
\item unique value: a list of unique attribute values of all pre-existing features
is produced and presented in a combo box for selection.
\item  unique value (editable): a combination of `line edit' and `unique value'.
The edit field completes entered values to the unique value, but also allows
to enter new values.
\item value map: a combobox to select from a set of values specified in the
\texttt{value} column the \tab{Attributes} tab.  The possible values are 
delimited by a semicolon (e.g. \verb|high;medium;low|).  It is also possible
to prepend a label to each value, which is delimited with an equal sign (e.g.
\verb|high=1;medium=2;low=3|). The label is shown in the combobox instead of
the value.
\item classification: if a unique value renderer is selected for the layer, the
values used for the classes are presented for selection in a combobox.
\item range (editable): A edit field that allows to restrict numeric values to a
given range.  That range is specified by entering minium and maximum value
delimited by a semicolon (e.g. \verb|0;360|) in the \texttt{value} column of
the \tab{Attributes} tab.
\item range (slider): A slider widget is presented that allows selection of a value
in a given range and precision.  The range is specifed by minimum, maximum
value and a step width (e.g. \verb|0;360;10|) in the \texttt{value} column of
the \tab{Attributes} tab.
\item file name: the line edit widget is accompanied by a push button. When pressed
it allows to select a filename using the standard file dialog.
\end{itemize}

\subsubsection{Diagram Tab}\label{sec:diagram}
\index{vector layers!diagram}

The \tab{Diagram} tab allows you to add a grahic overlay to a vector layer.
To activate this feature, open the Plugin Manager and select the Diagram Overlay' 
plugin. After this, there is a new tab in the vector \dialog{Layer
Properties} dialog where the settings for diagrams may be entered (see
figure~\ref{fig:diagramtab}).

\begin{figure}[ht]
   \begin{center}
   \caption{Vector properties dialog with diagram tab \nixcaption}\label{fig:diagramtab}\smallskip
   \includegraphics[clip=true, width=13cm]{diagram_tab}
\end{center}
\end{figure}

The current implementation of diagrams provides support for pie- and barcharts
and for linear scaling of the diagram size according to a classification
attribute. We will demonstrate an example and overlay the alaska boundary
layer a barchart diagramm showing some temperature data from a climate vector
layer. Both vector layers are part of the QGIS sample dataset (see
Section~\ref{label_sampledata}.

\begin{enumerate}
\item First click on the \toolbtntwo{mActionAddOgrLayer}{Load Vector} icon,
browse to the QGIS sample dataset folder and load the two vector shape layers
\filename{alaska.shp} and \filename{climate.shp}.
\item Double click the \filename{climate} layer in the map legend to open the
\dialog{Layer Properties} dialog.
\item Click on the \tab{Diagram Overlay} and select \button{Bar chart} as
Diagram type.
\item In the diagram we want to display the values of the three columns
\filename{T\_F\_JAN, T\_F\_JAN} and \filename{T\_F\_MEAN}. First select
\filename{T\_F\_JAN} as Attributes and click \button{Add attribute}, then
\filename{T\_F\_JUL} and finally \filename{T\_F\_MEAN}.  
\item For linear scaling of the diagram size we define \filename{T\_F\_JUL}
as classification attribute.
\item Now click on \button{find maximum value}, choose a size value and unit
and click \button{Apply} to display the diagram in the QGIS main window.
\item You can now adapt the chart size, or change the attribute colors double
clicking on the color values in the attribute field.
Figure~\ref{fig:climatediagram} gives an impression.
\item Finally click \button{Ok}. 
\end{enumerate}

\begin{figure}[ht]
   \begin{center}
   \caption{Diagram from temperature data overlayed on a map \nixcaption}\label{fig:climatediagram}\smallskip
   \includegraphics[clip=true, width=13cm]{climate_diagram}
\end{center}
\end{figure}

\subsection{Editing}\index{editing}

QGIS supports basic capabilities for editing vector geometries.  Before reading any
further you should note that at this stage editing support is still preliminary.
Before performing any edits, always make a backup of the dataset you are about
to edit. 

\textbf{Note} - the procedure for editing GRASS layers is different - see
Section \ref{grass_digitising} for details.

\subsubsection{Setting the Snapping Tolerance and Search Radius}

Before we can edit vertices, it is very important to set the snapping
tolerance and search radius to a value that allows us an optimal editing of
the vector layer geometries. 

\minisec{Snapping tolerance}

Snapping tolerance is the distance QGIS uses to \usertext{search} for the
closest vertex and/or segment you are trying to
connect when you set a new vertex or move an existing vertex. If you aren't
within the snap tolerance, QGIS will leave the vertex where you release the
mouse button, instead of snapping it to an existing vertex and/or segment. 

\begin{enumerate}
\item A general, project wide snapping tolerance can be defined choosing
\mainmenuopt{Settings} > \dropmenuopttwo{mActionOptions}{Options}. 
(On Mac: go to  \mainmenuopt{QGIS} > Preferences, on Linux: \mainmenuopt{Edit} > \dropmenuopttwo{mActionOptions}{Options}.)
In the \tab{Digitizing} tab you can select between to vertex, to segment or
to vertex and segment as default snap mode. You can also define a default
snapping tolerance and a search radius for vertex edits. The tolerance an be set either in map units or in pixels. 
In our digitizing project (working with the
Alaska dataset), the units are in feet. Your results may vary, but something
on the order of 300ft should be fine at a scale of 1:10 000 should be a
reasonable setting.
\item A layer based snapping tolerance can be defined by choosing
\mainmenuopt{Settings} (or \mainmenuopt{File}) > \dropmenuopttwo{mActionOptions}{Project
Properties\dots}. In the \tab{General} tab, section \classname{Digitize} you
can click on \button{Snapping options\dots} to enable and adjust snapping
mode and tolerance on a layer basis (see Figure~\ref{fig:snappingoptions}).
\end{enumerate}

\begin{figure}[H]
   \begin{center}
   \caption{Edit snapping options on a layer basis \nixcaption}\label{fig:snappingoptions}\smallskip
   \includegraphics[clip=true, width=14cm]{editProjectSnapping} 
\end{center}  
\end{figure}

\minisec{Search radius}

Search radius is the distance QGIS uses to \usertext{search} for the closest
vertex you are trying to move when you click on the
map. If you aren't within the search radius, QGIS won't find and select
any vertex for editing and it will pop up an annoying warning to that effect.
Snap tolerance and search radius are set in map units or pixels, so you may find you
need to experiment to get them set right. If you specify too big of a
tolerance, QGIS may snap to the wrong vertex, especially if you are dealing
with a large number of vertices in close proximity. Set search radius too
small and it won't find anything to move.

The search radius for vertex edits in layer units can be defined in the
\tab{Digitizing} tab under \mainmenuopt{Settings} >
\dropmenuopttwo{mActionOptions}{Options}. The same place where you define the
general, project wide snapping tolerance.

\subsubsection{Topological editing}

Besides layer based snapping options the \tab{General} tab in menu 
\mainmenuopt{Settings} -> \dropmenuopttwo{mActionOptions}{Project Properties\dots} 
also provides some topological functionalities. 
In the Digitizing option group you can \checkbox{Enable topological editing} and/or activate 
\checkbox{Avoid intersections of new polygons}.

\minisec{Enable topological editing}

The option \checkbox{Enable topological editing} is for editing and maintaining 
common boundaries in polygon mosaics. QGIS "detects" a shared boundary in 
a polygon mosaic and you only have to move the vertex once and QGIS will take 
care about updating the other boundary.

\minisec{Avoid intersections of new polygons}

The second topological option called \checkbox{Avoid intersections of new polygons} 
avoids overlaps in polygon mosaics. It is for quicker digitizing of adjacent polygons. 
If you already have one polygon, it is possible with this option to digitise the second 
one such that both intersect and qgis then cuts the second polygon to the common boundary. 
The advantage is that users don't have to digitize all vertices of the common boundary.

\subsubsection{Editing an Existing Layer}
\index{vector layers!editing}
\index{editing!an existing layer}
\label{sec:edit_existing_layer}

By default, QGIS loads layers read-only: This is a safeguard
to avoid accidentally editing a layer if there is a slip of the mouse.
However, you can choose to edit any layer as long as the data provider supports it,
and the underlying data source is writable (i.e. its files are not read-only).

Layer editing is most versatile when used on PostgreSQL/PostGIS data sources. 

\begin{Tip}[ht]\caption{\textsc{Data Integrity}}
\qgistip{It is always a good idea to back up your data source before you start 
editing. While the authors of QGIS have made every effort to preserve the 
integrity of your data, we offer no warranty in this regard.
}
\end{Tip}

\begin{Tip}[ht]\caption{\textsc{Manipulating Attribute data}}
\qgistip{Currently only PostGIS layers are supported for adding or dropping attribute
columns within this dialog. In future versions of QGIS, other datasources 
will be supported, because this feature was recently implemented in GDAL/OGR > 1.6.0
}
\end{Tip}



\begin{Tip}[ht]\caption{\textsc{Save Regularly}}
\qgistip{Remember to toggle \toolbtntwo{mActionToggleEditing}{Toggle editing} off regularly.  
This allows you to save your recent changes,
and also confirms that your data source can accept all
your changes.
}
\end{Tip}

\begin{Tip}[ht]\caption{\textsc{Concurrent Edits}}
\qgistip{This version of QGIS does not track if somebody else is editing a feature at the same time
as you.  The last person to save their edits wins.
}
\end{Tip}

\begin{Tip}[ht]\caption{\textsc{Zoom in Before Editing}}
\qgistip{Before editing a layer, you should
zoom in to your area of interest. This 
avoids waiting while all the vertex markers are rendered across the entire layer.
}
\end{Tip}

\begin{Tip}[ht]\caption{\textsc{Vertex Markers}}
\qgistip{
The current version of QGIS supports two kinds of vertex-markers -
a semi-transparent circle or a cross. To change the marker style, choose
\dropmenuopttwo{mActionOptions}{Options} from the
\mainmenuopt{Settings} menu and click on the \tab{Digitizing} tab and select
the appropriate entry.
}
\end{Tip}

All editing sessions start by choosing the \dropmenuopttwo{mActionToggleEditing}{Toggle editing} option.
This can be found in the context menu after right clicking on the legend
entry for that layer.\index{Allow Editing}
Alternately, you can use the \index{Toggle Editing}
\toolbtntwo{mActionToggleEditing}{Toggle editing} button from the toolbar to start 
or stop the editing mode.\index{editing!icons} Once the layer is in edit mode, 
markers will appear at the vertices, and additional tool buttons on the editing 
toolbar will become available.

\minisec{Zooming and panning with the mouse wheel}

While digitizing you can press the mouse wheel to pan inside of the main
window and you can roll the mouse wheel to zoom in and out on the map. For
zooming place the mouse cursor inside the map area and roll it forward (away from you) 
to zoom in and backwards (towards you) to zoom out. The mouse cursor position will 
be the center of the zoomed area of interest. You can customize the behavior 
of the mouse wheel zoom using the \tab{Map tools} tab under the
\mainmenuopt{Settings} >\dropmenuopt{Options} menu.  

\minisec{Panning with the arrow keys}

Panning the Map during digitizing is possible with the arrow keys. Place
the mouse cursor inside the map area and click on the right arrow key to
pan east, left arrow key to pan west, up arrow key to pan north and down arrow 
key to pan south.

You can also use the spacebar to temporarily cause mouse movements to pan 
then map. The PgUp and PgDown keys on your keyboard will cause the map 
display to zoom in or out without interrupting your digitising session.

You can perform the following editing functions:

\begin{itemize}
\item Add Features: \toolbtntwo{mActionCapturePoint}{Capture Point},
  \toolbtntwo{mActionCaptureLine}{Capture Line} and
  \toolbtntwo{mActionCapturePolygon}{Capture Polygon}
\item \toolbtntwo{mActionAddRing}{Add Ring}
\item \toolbtntwo{mActionAddIsland}{Add Island}
\item \toolbtntwo{mActionSplitFeatures}{Split Features}
\item \toolbtntwo{mActionMoveFeature}{Move Features}
\item \toolbtntwo{mActionMoveVertex}{Move Vertex}
\item \toolbtntwo{mActionAddVertex}{Add Vertex}
\item \toolbtntwo{mActionDeleteVertex}{Delete Vertex}
\item \toolbtntwo{mActionDeleteSelected}{Delete Selected}
\item \toolbtntwo{mActionEditCut}{Cut Features}
\item \toolbtntwo{mActionEditCopy}{Copy Features}
\item \toolbtntwo{mActionEditPaste}{Paste Features}
\end{itemize}

\minisec{Adding Features}
\index{vector layers!adding!feature}

Before you start adding features, use the \toolbtntwo{mActionPan}{pan}
and \toolbtntwo{mActionZoomIn}{zoom-in}/\toolbtntwo{mActionZoomOut}{zoom-out} 
tools to first navigate to the area of interest.

Then you can use the \toolbtntwo{mActionCapturePoint}{Capture point},
\toolbtntwo{mActionCaptureLine}{Capture line} or
\toolbtntwo{mActionCapturePolygon}{Capture polygon} icons on the toolbar to put the QGIS cursor
into digitizing mode.

For each feature, you first digitize the geometry, then enter its attributes.

To digitize the geometry, left-click on the map area to create the
first point of your new feature.

For lines and polygons, keep on left-clicking for each additional
point you wish to capture.  When you have finished adding points,
right-click anywhere on the map area to confirm you have finished entering
the geometry of that feature.

The attribute window will appear, allowing you to enter the information for the new feature.
Figure \ref{fig:vector_digitising} shows setting attributes for a fictitious
new river in Alaska.

\begin{figure}[ht]
   \begin{center}
   \caption{Enter Attribute Values Dialog after digitizing a new vector
   feature \nixcaption}\label{fig:vector_digitising}\smallskip
   \includegraphics[clip=true, width=8cm]{editDigitizing}
\end{center}  
\end{figure}

\begin{Tip}[ht]\caption{\textsc{Attribute Value Types}}
\qgistip{
At least for shapefile editing the attribue types are validated during the
entry. Because of this, it is not possible to enter a number into the text-column in
the dialog \dialog{Enter Attribute Values} or vica versa. If you need to do so,
you should edit the attributes in a second step within the \dialog{Attribute
table} dialog.
}
\end{Tip}

\minisec{Move Feature}
\index{vector layers!move!feature}

You can move features using the \toolbtntwo{mActionMoveFeature}{Move Feature} icon
on the toolbar.

\minisec{Split Feature}
\index{vector layers!split!feature}

You can split features using the \toolbtntwo{mActionSplitFeatures}{Split Features} icon
on the toolbar.

\minisec{Editing Vertices of a Feature}
\index{vector layers!editing!vertex}

For both PostgreSQL/PostGIS and shapefile-based layers, the vertices of features can be edited. 

Vertices can be directly edited, that is, you don't
have to choose which feature to edit before you can change
its geometry.
In some cases, several features may share the same vertex
and so the following rules apply when the mouse is pressed
down near map features:

\begin{itemize}
\item \textbf{Lines}    - The nearest line to the mouse position
                          is used as the target feature.
                          Then (for moving and deleting a vertex)
                          the nearest vertex
                          on that line is the editing target.

\item \textbf{Polygons} - If the mouse is inside a polygon, then it is
                          the target feature; otherwise the nearest polygon
                          is used.
                          Then (for moving and deleting a vertex)
                          the nearest vertex
                          on that polygon is the editing target.
\end{itemize}

You will need to set the property
\mainmenuopt{Settings}>\dropmenuopttwo{mActionOptions}{Options}>\tab{Digitizing}>\selectnumber{Search Radius}{10}
to a number greater than zero.  Otherwise QGIS will not be able to tell which feature is being edited.


\minisec{Adding Vertices of a Feature}
\index{vector layers!adding!vertex}

You can add new vertices to a feature by using the
\toolbtntwo{mActionAddVertex}{Add Vertex} icon
on the toolbar.

Note, it doesn't make sense to add more vertices to a Point feature!

In this version of QGIS, vertices can only be added to an \textit{existing} line
segment of a line feature.  If you want to extend a line beyond its end,
you will need to move the terminating vertex first, then add a new vertex where
the terminus used to be.

\minisec{Moving Vertices of a Feature}
\index{vector layers!moving!vertex}

You can move vertices using the \toolbtntwo{mActionMoveVertex}{Move Vertex} icon
on the toolbar.

\minisec{Deleting Vertices of a Feature}
\index{vector layers!deleting!vertex}

You can delete vertices by using the \toolbtntwo{mActionDeleteVertex}{Delete Vertex} icon
on the toolbar.

Note, it doesn't make sense to delete the vertex of a Point feature!
Delete the whole feature instead.

Similarly, a one-vertex line or a two-vertex polygon is also
fairly useless and will lead to unpredictable results elsewhere
in QGIS, so don't do that.

\textbf{Warning:} A vertex is identified for deletion as
soon as you click the mouse near an eligible
feature.  To undo, you will need to toggle
Editing off and then discard your changes.
(Of course this will mean that other unsaved changes will be lost, too.)

\minisec{Add Ring}
\index{vector layers!add!ring}

You can create ring polygons using the \toolbtntwo{mActionAddRing}{Add Ring}
icon in the toolbar. This means inside an existing area it is
possible to digitize further polygons, that will occur as a 'whole', so only 
the area in between the boundaries of the outer and inner polygons remain as 
a ring polygon. 

\minisec{Add Island}
\index{vector layers!add!island}

You can \toolbtntwo{mActionAddIsland}{add island} polygons to a selected multipolygon. 
The new island polygon has to be digitized outside the selected multipolygon. 

\minisec{Cutting, Copying and Pasting Features}
\index{vector layers!cut!feature}
\index{vector layers!copy!feature}
\index{vector layers!paste!feature}
\index{editing!cutting features}
\index{editing!copying features}
\index{editing!pasting features}

Selected features can be cut, copied and pasted between layers in the
same QGIS project, as long as destination layers are set to 
\toolbtntwo{mActionToggleEditing}{Toggle editing} beforehand.

Features can also be pasted to external applications as text:  That is,
the features are represented in CSV format with the geometry data appearing 
in the OGC Well-Known Text (WKT) format.


However in this version of QGIS, text features from outside QGIS cannot 
be pasted to a layer within QGIS. When would the copy and paste function 
come in handy? Well, it turns out that you can edit more than one layer 
at a time and copy/paste features between layers. Why would we want to do 
this?  Say we need to do some work on a new layer but only need one or 
two lakes, not the 5,000 on our \filename{big\_lakes} layer. We can create 
a new layer and use copy/paste to plop the needed lakes into it. 

As an example we are copying some lakes to a new layer:

\begin{enumerate}
\item Load the layer you want to copy from (source layer)
\item Load or create the layer you want to copy to (target layer) 
\item Start editing for target layer
\item Make the source layer active by clicking on it in the legend 
\item Use the \toolbtntwo{mActionSelect}{Select} tool to select the feature(s) on the source layer
\item Click on the \toolbtntwo{mActionEditCopy}{Copy Features} tool
\item Make the destination layer active by clicking on it in the legend 
\item Click on the \toolbtntwo{mActionEditPaste}{Paste Features} tool 
\item Stop editing and save the changes
\end{enumerate}

What happens if the source and target layers have
different schemas (field names and types are not the same)? QGIS populates
what matches and ignores the rest. If you don't care about the attributes
being copied to the target layer, it doesn't matter how you design the
fields and data types. If you want to make sure everything - feature and its
attributes - gets copied, make sure the schemas match.

\begin{Tip}[ht]\caption{\textsc{Congruency of Pasted Features}}
\qgistip{If your source and destination layers use the
same projection, then the pasted features will have
geometry identical to the source layer.
However if the destination layer is a different projection
then QGIS cannot guarantee the geometry is identical.
This is simply because there are small rounding-off errors
involved when converting between projections.
}
\end{Tip}

\minisec{Deleting Selected Features}
\index{vector layers!deleting!feature}

If we want to delete an entire polygon, we can do that by first selecting 
the polygon using the regular \toolbtntwo{mActionSelect}{Select Features} tool. You can select 
multiple features for deletion. Once you have the selection set, use the 
\toolbtntwo{mActionDeleteSelected}{Delete Selected} tool to delete the features. There is no undo function, 
but remember your layer isn't really changed until you stop editing and choose 
to save your changes. So if you make a mistake, you can always cancel the save.

The \toolbtntwo{mActionEditCut}{Cut Features} tool on the digitizing toolbar can
also be used to delete features. This effectively deletes the feature but
also places it on a ``spatial clipboard". So we cut the feature to delete. 
We could then use the \toolbtntwo{mActionEditPaste}{paste tool} to put it back, giving us a one-level undo 
capability. Cut, copy, and paste work on the currently selected features, 
meaning we can operate on more than one at a time.

\begin{Tip}[ht]\caption{\textsc{Feature Deletion Support}}
\qgistip{When editing ESRI shapefiles, the deletion
of features only works if QGIS is linked to a GDAL version 1.3.2 or greater. 
The OS X and Windows versions of QGIS available from the download site are built 
using GDAL 1.3.2 or higher.
}
\end{Tip}

\minisec{Snap Mode}
\index{editing!snap}
QGIS allows digitized vertices to be snapped to other vertices of the same layer. To 
set the snapping tolerance, go to
\mainmenuopt{Settings}>\dropmenuopttwo{mActionOptions}{Options}->\tab{Digitizing}.
(On Mac: go to  \mainmenuopt{QGIS} > Preferences, on Linux: \mainmenuopt{Edit} > \dropmenuopttwo{mActionOptions}{Options}.)
Note that the snapping tolerance is in map units or pixels.

\minisec{Saving Edited Layers}
\index{editing!saving changes}

When a layer is in editing mode, any changes remain in the memory of QGIS.
Therefore they are not committed/saved immediately to the data source or disk.
When you turn editing mode off (or quit QGIS for that matter), 
you are then asked if you want to save your
changes or discard them.

If the changes cannot be saved (e.g. disk full, or the attributes have
values that are out of range), the QGIS in-memory state is preserved.  This
allows you to adjust your edits and try again.

\subsubsection{Creating a New Layer}\label{sec:create shape}\index{editing!creating a new layer}

To create a new layer for editing, choose \toolbtntwo{mActionNewVectorLayer}{New Vector Layer} from the
\mainmenuopt{Layer} menu. 
The \dialog{New Vector Layer} dialog will be displayed as
shown in Figure \ref{fig:newvectorlayer}. Choose the type of layer (point,
line or polygon).

\begin{figure}[ht]
   \begin{center}
   \caption{Creating a New Vector Dialog \nixcaption}\label{fig:newvectorlayer}\smallskip
   \includegraphics[clip=true, width=10cm]{editNewVector}
\end{center} 
\end{figure}

Note that QGIS does not yet support creation of 2.5D
features (i.e. features with X,Y,Z coordinates) or measure features. At this
time, only shapefiles can be created. In a future version of QGIS, creation of
any OGR or PostgreSQL layer type will be supported. 

Creation of GRASS-layers is supported within the GRASS-plugin. Please refer to section
\ref{sec:creating_new_grass_vectors} for more information on creating GRASS vector 
layers.

To complete the creation of the new layer, add the desired attributes by
clicking on the \button{Add} button and specifying a name and type for the
attribute. Only \selectstring{Type}{real}, \selectstring{Type}{integer}, and \selectstring{Type}{string} attributes are supported. Once you
are happy with the attributes, click \button{OK} and provide a name for the shapefile.
QGIS will automatically add a \filename{.shp} extension to the name you specify.  Once
the layer has been created, it will be added to the map and you can edit it in
the same way as described in Section \ref{sec:edit_existing_layer} above. 

\subsubsection{Working with the Attribute Table}\label{sec:attribute table}\index{editing!working with the attribute table}

To open the attribute table for a vector layer, make the layer active by clicking on it in the Map legend area. 
Then use \mainmenuopt{Layer} Layer from the main menu and and choose \dropmenuopttwo{mActionOpenTable}{Open Attribute Table} 
from the menu. It is also possible to rightlick on the layer and choose \dropmenuopttwo{mActionOpenTable}{Open Attribute Table} 
from the dropdown menu. This will open a new window which displays the attributes for every feature in the layer 
(figure \ref{fig:attributetable}).

\begin{figure}[ht]
   \begin{center}
   \caption{Attribute Table for Alaska layer \nixcaption}\label{fig:attributetable}\smallskip
   \includegraphics[clip=true, width=12cm]{vectorAttributeTable}
\end{center} 
\end{figure}

Each column can be sorted by clicking on its header. A small arrow indicates the sort 
order (downward pointing means descending values from the top row down, upward pointing means 
ascending values from the top rown down). 
For a simple selection by attributes on only one column the \button{Look for} field 
can be used. Select the field (column) from which the search should be performed from 
the dropdown menu and hit the \button{Search} button. For more complex searches use the
Advanced search \button{...}, which will lauch the Search Query Builder described in 
Section \ref{sec:select_by_query}. 

To show selected records only, use the checkbox \checkbox{Show selected records only}.
Using the buttons at the bottom left of the window, selected fields can be removed, 
moved to the top of the table, or the selection can be inverted. Selected features can 
also be copied to the clipboard, which can also be done with \keystroke{Ctrl-C}. You can also zoom 
into the selected features on the map. Toggle editing allows to edit single values of attributes. 

\subsection{Query Builder}\label{sec:query_builder}
\index{Query Builder}

The Query Builder allows you to define a subset of a table and display
it as a layer in QGIS. It can currently only be used with PostGIS layers. 
For example, if you have a \filename{towns} layer with a
\usertext{population} field you could select only larger towns by entering
\usertext{population > 100000} in the SQL box of the query builder. Figure
\ref{fig:query_builder} shows an example of the query builder populated with
data from a PostGIS layer with attributes stored in PostgreSQL. 

\begin{figure}[ht]
  \begin{center}
    \caption{Query Builder \nixcaption}\label{fig:query_builder}\smallskip
    \includegraphics[clip=true, width=11.5cm]{queryBuilder}
  \end{center}  
\end{figure}

The query builder\index{Query Builder} lists the layer's database
fields in the list box on the left. You can get a sample of the data
contained in the highlighted field by clicking on the \button{Sample} button\index{Query
Builder!generating sample list}. This retrieves the first 25 distinct values
for the field from the database. To get a list of all possible values for a
field, click on the \button{All} button\index{Query Builder!getting all
values}. To add a selected field or value to the query, double-click on
it\index{Query Builder!adding fields}. You can use the various buttons to
construct the query or you can just type it into the SQL box.

To test a query, click on the \button{Test} button\index{Query Builder!testing
queries}. This will return a count of the number of records that will be
included in the layer. When satisfied with the query, click \button{OK}. The
SQL for the where clause will be shown in the SQL column of the layer list.

\begin{Tip}\caption{\textsc{Changing the Layer Definition}}\index{Query
Builder!changing layer definitions}
\qgistip{You can change the layer definition after it is loaded by altering
the SQL query used to define the layer. To do this, open the 
vector \dialog{Layer Properties} dialog by double-clicking on the layer in the legend and click on the
\button{Query Builder} button on the \tab{General} tab. See Section
\ref{sec:vectorprops} for more information.}
\end{Tip}

\subsection{Select by query}\label{sec:select_by_query}
\index{PostgreSQL!query builder}
\index{PostGIS!query builder}
\index{query builder!PostgreSQL}
\index{query builder!PostGIS}

With QGIS it is possible also to select features using a similar query builder 
interface to that used in \ref{sec:query_builder}. In the above section 
the purpose of the query builder is to only show features meeting the 
filter criteria as a 'virtual layer' / subset. The purpose of the select by 
query function is to highlight all features that meet a particular criteria. 
Select by query can be used with all vector data providers.

To do a `select by query' on a loaded layer, click on the 
button \toolbtntwo{mActionOpenTable}{Open Table} to open the attribute table of the layer. Then 
click the \button{Advanced...} button at the bottom. This starts the Query Builder 
that allows to define a subset of a table and display it as described in Section 
\ref{sec:query_builder}.


\index{vector layers|)}
