[QGIS Commit] r8983 - docs/trunk/english_us/user_guide
svn_qgis at osgeo.org
svn_qgis at osgeo.org
Sat Aug 2 13:30:55 EDT 2008
Author: macho
Date: 2008-08-02 13:30:55 -0400 (Sat, 02 Aug 2008)
New Revision: 8983
Modified:
docs/trunk/english_us/user_guide/plugins_decorations.tex
docs/trunk/english_us/user_guide/plugins_delimited_text.tex
docs/trunk/english_us/user_guide/plugins_georeferencer.tex
docs/trunk/english_us/user_guide/plugins_gps.tex
docs/trunk/english_us/user_guide/plugins_graticule_creator.tex
docs/trunk/english_us/user_guide/plugins_python.tex
Log:
updating to conventions.tex for chapter 11 using plugins finished.. someone can overlook it please?
Modified: docs/trunk/english_us/user_guide/plugins_decorations.tex
===================================================================
--- docs/trunk/english_us/user_guide/plugins_decorations.tex 2008-08-02 12:09:23 UTC (rev 8982)
+++ docs/trunk/english_us/user_guide/plugins_decorations.tex 2008-08-02 17:30:55 UTC (rev 8983)
@@ -28,7 +28,7 @@
shown in the example
\item Choose the placement of the label from the \selectstring{Placement}{Bottom Right} drop-down box
\item Make sure the \checkbox{Enable Copyright Label} checkbox is checked
-\item Click \textsl{OK}
+\item Click \button{OK}
\end{enumerate}
In the example above, the first line is in bold, the second (created using
@@ -73,7 +73,7 @@
\item Make sure the \checkbox{Enable scale bar} checkbox is checked
\item Optionally choose to automatically snap to a round number when the
canvas is resized \checkbox{Automatically snap to round number on resize}
-\item Click \textsl{OK}
+\item Click \button{OK}
\end{enumerate}
%\begin{figure}[ht]
Modified: docs/trunk/english_us/user_guide/plugins_delimited_text.tex
===================================================================
--- docs/trunk/english_us/user_guide/plugins_delimited_text.tex 2008-08-02 12:09:23 UTC (rev 8982)
+++ docs/trunk/english_us/user_guide/plugins_delimited_text.tex 2008-08-02 17:30:55 UTC (rev 8983)
@@ -45,7 +45,7 @@
\index{plugins!manager}
The Plugin Manager displays a list of available plugins.
Those that are already loaded have a check mark to the left of their name.
-Click on the checkbox to the left of the \checkbox{Add Delimited Text Layer} plugin and click Ok to load it as described in Section \ref{sec:managing_plugins}.
+Click on the checkbox to the left of the \checkbox{Add Delimited Text Layer} plugin and click \button{OK} to load it as described in Section \ref{sec:managing_plugins}.
A new toolbar icon is now present:
@@ -86,8 +86,7 @@
To properly parse the file, change the delimiter to tab using \mbox{$\backslash$}t (this is a regular expression for the tab character).
After changing the delimiter, click \button{Parse}.
-The drop down boxes now contain the fields properly parsed as shown in Figure
-\ref{fig:delim_text_file_selected2}.
+The drop down boxes now contain the fields properly parsed as shown in Figure \ref{fig:delim_text_file_selected2}.
%\begin{figure}[ht]
% \begin{center}
@@ -98,4 +97,5 @@
%\end{figure}
Choose the X and Y fields from the drop down boxes and enter a Layer name as shown in Figure \ref{fig:delim_text_file_selected3}.
-To add the layer to the map, click {\em Add Layer}. The delimited text file now behaves as any other map layer in QGIS.
\ No newline at end of file
+To add the layer to the map, click \button{Add Layer}.
+The delimited text file now behaves as any other map layer in QGIS.
\ No newline at end of file
Modified: docs/trunk/english_us/user_guide/plugins_georeferencer.tex
===================================================================
--- docs/trunk/english_us/user_guide/plugins_georeferencer.tex 2008-08-02 12:09:23 UTC (rev 8982)
+++ docs/trunk/english_us/user_guide/plugins_georeferencer.tex 2008-08-02 17:30:55 UTC (rev 8983)
@@ -1,14 +1,12 @@
\subsection{Using the Georeferencer Plugin}
-The georeferencer plugin allows to generate world files for rasters. Therefore
-you select points on the raster, add their coordinates, and the plugin will
-compute the world file parameters. The more coordinates you provide the better
-the result will be.
+The \toolbtntwo{georeferencer}{Georeferencer} allows to generate world files for rasters.
+Therefore you select points on the raster, add their coordinates, and the plugin will compute the world file parameters.
+The more coordinates you provide the better the result will be.
-As an example we will generate a world file for a topo sheet of South Dakota
-from SDGS. It can later be visualized together with in the data of the GRASS
-spearfish60 location. You can download the topo sheet here: \\
-\url{http://grass.osgeo.org/sampledata/spearfish\_toposheet.tar.gz}
+As an example we will generate a world file for a topo sheet of South Dakota from SDGS.
+It can later be visualized together with in the data of the GRASS spearfish60 location.
+You can download the topo sheet here: \url{http://grass.osgeo.org/sampledata/spearfish\_toposheet.tar.gz}
As a first step we download the file and untar it.
@@ -18,8 +16,7 @@
cd spearfish_toposheet
\end{verbatim}
-The next step is to start QGIS, load the georeferencer plugin and select
-the file spearfish\_topo24.tif.
+The next step is to start QGIS, load the georeferencer plugin and select the file spearfish\_topo24.tif.
%\begin{figure}[ht]
%\begin{center}
@@ -28,8 +25,7 @@
%\end{center}
%\end{figure}
-Now click on the button \textsl{Arrange plugin window} to open the image
-in the georeferencer and to arrange it with the reference map in the qgis map canvas on your dekstop.
+Now click on the button \button{Arrange plugin window} to open the image in the georeferencer and to arrange it with the reference map in the qgis map canvas on your desktop.
%\begin{figure}[ht]
%\begin{center}
@@ -38,17 +34,13 @@
%\end{center}
%\end{figure}
-With the button \textsl{Add Point} you can start to add points on the
-raster image and enter their coordinates, and the plugin will compute the
-world file parameters (see Figure \ref{fig:choose_points}). The more coordinates you provide the better the
-result will be. For the procedure you have two options:
+With the button \button{Add Point} you can start to add points on the raster image and enter their coordinates, and the plugin will compute the world file parameters (see Figure \ref{fig:choose_points}).
+The more coordinates you provide the better the result will be.
+For the procedure you have two options:
\begin{enumerate}
-\item You click on a point in the raster map and enter the X and Y
-coordinates manually
-\item You click on a point in the raster map and choose the button
-\textsl{from map canvas} to add the X and Y coordinates with the help
-of a georeferenced map already loaded in QGIS.
+\item You click on a point in the raster map and enter the X and Y coordinates manually
+\item You click on a point in the raster map and choose the button \button{from map canvas} to add the X and Y coordinates with the help of a georeferenced map already loaded in QGIS.
\end{enumerate}
%\begin{figure}[ht]
@@ -58,35 +50,25 @@
%\end{center}
%\end{figure}
-For this example we use the second option and enter the coordinates for the
-selected points with the help of the \textsl{roads} map provided with the
-\textsl{spearfish60} location from: \\
-\url{http://grass.osgeo.org/sampledata/spearfish\_grass60data-0.3.tar.gz}
+For this example we use the second option and enter the coordinates for the selected points with the help of the \textsl{roads} map provided with the \textsl{spearfish60} location from: \url{http://grass.osgeo.org/sampledata/spearfish\_grass60data-0.3.tar.gz}
-If you don't know how to integrate the spearfish60 location with the GRASS plugin,
-information are provided in Section \ref{sec:grass}.
+If you don't know how to integrate the spearfish60 location with the GRASS plugin, information are provided in Section \ref{sec:grass}.
-As you can see in Figure \ref{fig:choose_points}, the georeferencer provides buttons
-to zoom, pan, add and delete points in the image.
+As you can see in Figure \ref{fig:choose_points}, the georeferencer provides buttons to zoom, pan, add and delete points in the image.
-After you added enough points to the image you need to select the transformation
-type for the georeferencing process and save the resulting world file together with
-the Tiff. In our example we choose linear transformation although a Helmert
-transformation might be sufficient as well.
+After you added enough points to the image you need to select the transformation type for the georeferencing process and save the resulting world file together with the Tiff.
+In our example we choose linear transformation although a Helmert transformation might be sufficient as well.
+
\begin{Tip}\caption{\textsc{Choosing the transformation type}}
-\qgistip{The linear (affine) transformation is a 1st order transformation and is used
-for scaling, translation and rotation of geometrically correct images. With the
-Helmert transformation you simply add coordinate information to the image like
-geocooding. If your image is contorted you will need to use software that provides
-2nd or 3rd order polynomial transformation, e.g. GRASS GIS.
-}
+\qgistip{The linear (affine) transformation is a 1st order transformation and is used for scaling, translation and rotation of geometrically correct images.
+With the Helmert transformation you simply add coordinate information to the image like geocooding.
+If your image is contorted you will need to use software that provides 2nd or 3rd order polynomial transformation, e.g. GRASS GIS.}
\end{Tip}
-The points we added to the map will be stored in a \textsl{spearfish\_topo24.tif.points} file together
-with the raster image. This allows us to reopen the georeferencer plugin and to add new points or delete
-existing ones to optimize the result. The \textsl{spearfish\_topo24.tif.points} file of this
-example shows the points:
+The points we added to the map will be stored in a \textsl{spearfish\_topo24.tif.points} file together with the raster image.
+This allows us to reopen the georeferencer plugin and to add new points or delete existing ones to optimize the result.
+The \textsl{spearfish\_topo24.tif.points} file of this example shows the points:
\begin{verbatim}
mapX mapY pixelX pixelY
@@ -97,21 +79,13 @@
602649.526155399973504 4919088.353569299913943 602618 4.91907e+06
\end{verbatim}
-We used 5 coordinate points to georeference the raster image. To get correct results
-it is important to disperse the points regulary in the image. Finally we check the result and load
-the new georeferenced map \textsl{spearfish\_topo24.tif} and overlay it with the map \textsl{roads}
-of the spearfish60 location.
+We used 5 coordinate points to georeference the raster image.
+To get correct results it is important to disperse the points regulary in the image.
+Finally we check the result and load the new georeferenced map \textsl{spearfish\_topo24.tif} and overlay it with the map \textsl{roads} of the spearfish60 location.
%\begin{figure}[ht]
%\begin{center}
% \caption{Georeferenced map with overlayed roads from spearfish60 location}\label{fig:result_map}\smallskip
% \includegraphics[clip=true,width=0.8\textwidth]{result_map}
%\end{center}
-%\end{figure}
-
-
-
-
-
-
-
+%\end{figure}
\ No newline at end of file
Modified: docs/trunk/english_us/user_guide/plugins_gps.tex
===================================================================
--- docs/trunk/english_us/user_guide/plugins_gps.tex 2008-08-02 12:09:23 UTC (rev 8982)
+++ docs/trunk/english_us/user_guide/plugins_gps.tex 2008-08-02 17:30:55 UTC (rev 8983)
@@ -14,48 +14,40 @@
There are dozens of different file formats for storing GPS data.
The format that QGIS uses is called GPX (GPS eXchange format), which is a standard interchange format that can contain any number of waypoints, routes and tracks in the same file.
-To load a GPX file you need to use the plugin.
-When this plugin is loaded a button with a small handheld GPS device will show up in the toolbar (the device looks a bit like a mobile phone).
-Clicking on this button will open the \emph{GPS Tools} dialog (see figure \ref{figure GPX loader}).
+To load a GPX file you first need to load the plugin.
+\mainmenuopt{Plugins} > \dropmenuopttwo{mActionShowPluginManager}{Plugin Manager...} > \checkbox{GPS Tools}
+When this plugin is loaded a button with a small handheld GPS device will show up in the toolbar.
+Clicking on this button \toolbtntwo{gps_importer}{GPS Tools} will open the GPS Tools dialog (see figure \ref{gpxloader}).
+
%\begin{figure}[ht]
% \begin{center}
-%\caption{\label{figure GPX loader}The \emph{GPS Tools} dialog window}
+%\caption{\label{gpxloader}The \emph{GPS Tools} dialog window}
%\includegraphics[clip=true, width=12cm]{loadgpx}
%\end{center}
%\end{figure}
-Use the browse button {[}Browse...{]} to select the GPX file, then use the
-checkboxes to select the feature types you want to load from that
-GPX file. Each feature type will be loaded in a separate layer when
-you click OK.
+Use the browse button \browsebutton to select the GPX file, then use the checkboxes to select the feature types you want to load from that GPX file.
+Each feature type will be loaded in a separate layer when you click \button{OK}.
\subsubsection{GPSBabel}
-Since QGIS uses GPX files you need a way to convert other GPS file
-formats to GPX. This can be done for many formats using the free program
-GPSBabel, which is available at \url{http://www.gpsbabel.org}. This
-program can also transfer GPS data between your computer and a GPS
-device. QGIS uses GPSBabel to do these things, so it is recommended
-that you install it. However, if you just want to load GPS data from
-GPX files you will not need it. Version 1.2.3 of GPSBabel is known
-to work with QGIS, but you should be able to use later versions without
+Since QGIS uses GPX files you need a way to convert other GPS file formats to GPX.
+This can be done for many formats using the free program GPSBabel, which is available at \url{http://www.gpsbabel.org}.
+This program can also transfer GPS data between your computer and a GPS device.
+QGIS uses GPSBabel to do these things, so it is recommended that you install it.
+However, if you just want to load GPS data from GPX files you will not need it.
+Version 1.2.3 of GPSBabel is known to work with QGIS, but you should be able to use later versions without
any problems.
\subsubsection{Importing GPS data}
-To import GPS data from a file that is not a GPX file, you use the
-tool \emph{Import other file} in the \emph{GPS Tools} dialog. Here
-you select the file that you want to import, which feature type you
-want to import from it, where you want to store the converted GPX
-file and what the name of the new layer should be.
+To import GPS data from a file that is not a GPX file, you use the tool \tab{Import other file} in the GPS Tools dialog.
+Here you select the file that you want to import, which feature type you want to import from it, where you want to store the converted GPX file and what the name of the new layer should be.
-When you select the file to import you must also select the format
-of that file by using the menu in the file selection dialog (see figure
-\ref{figure importdialog}). All formats do not support all three
-feature types, so for many formats you will only be able to choose
-between one or two types.
+When you select the file to import you must also select the format of that file by using the menu in the file selection dialog (see figure \ref{figure importdialog}).
+All formats do not support all three feature types, so for many formats you will only be able to choose between one or two types.
%\begin{figure}[ht]
% \begin{center}
@@ -67,12 +59,9 @@
\subsubsection{Downloading GPS data from a device}
-QGIS can use GPSBabel to download data from a GPS device directly
-into vector layers. For this you use the tool \emph{Download from
-GPS} (see Figure \ref{figure_download}), where you select your type
-of GPS device, the port that it is connected to, the feature type
-that you want to download, the GPX file where the data should be stored,
-and the name of the new layer.
+QGIS can use GPSBabel to download data from a GPS device directly into vector layers.
+For this you use the tool \tab{Download from GPS} (see Figure \ref{figure_download}), where you select your type
+of GPS device, the port that it is connected to, the feature type that you want to download, the GPX file where the data should be stored, and the name of the new layer.
%\begin{figure}[ht]
% \begin{center}
@@ -82,73 +71,45 @@
%\end{figure}
-The device type you select in the GPS device menu determines how GPSBabel
-tries to communicate with the device. If none of the types
-works with your GPS device you can create a new type (see section
-\ref{sec:Defining-new-device}).
+The device type you select in the GPS device menu determines how GPSBabel tries to communicate with the device.
+If none of the types works with your GPS device you can create a new type (see section \ref{sec:Defining-new-device}).
-The port is a file name or some other name that your operating system
-uses as a reference to the physical port in your computer that the
-GPS device is connected to. On Linux this is something like /dev/ttyS0
-or /dev/ttyS1 and on Windows it's COM1 or COM2.
+The port is a file name or some other name that your operating system uses as a reference to the physical port in your computer that the GPS device is connected to.
+\nix On Linux this is something like /dev/ttyS0 or /dev/ttyS1 and on \win Windows it's COM1 or COM2.
-When you click OK the data will be downloaded from the device and
-appear as a layer in QGIS.
+When you click \button{OK} the data will be downloaded from the device and appear as a layer in QGIS.
\subsubsection{Uploading GPS data to a device}
-You can also upload data directly from a vector layer in QGIS to a
-GPS device, using the tool \emph{Upload to GPS}. The layer must be
-a GPX layer. To do this you simply select the layer that you want
-to upload, the type of your GPS device and the port that it's connected
-to. Just as with the download tool you can specify new device types
-if your device isn't in the list.
+You can also upload data directly from a vector layer in QGIS to a GPS device, using the tool \tab{Upload to GPS}.
+The layer must be a GPX layer.
+To do this you simply select the layer that you want to upload, the type of your GPS device and the port that it's connected to.
+Just as with the download tool you can specify new device types if your device isn't in the list.
-This tool is very useful together with the vector editing capabilities
-of QGIS. You can load a map, create some waypoints and routes and
-then upload them and use them in your GPS device.
+This tool is very useful together with the vector editing capabilities of QGIS.
+You can load a map, create some waypoints and routes and then upload them and use them in your GPS device.
\subsubsection{\label{sec:Defining-new-device}Defining new device types}
-There are lots of different types of GPS devices. The QGIS developers
-can't test all of them, so if you have one that does not work with
-any of the device types listed in the download and upload tools you
-can define your own device type for it. You do this by using the \emph{GPS
-device editor}, which you start by clicking the \emph{Edit devices}
-button in the download or the upload window.
+There are lots of different types of GPS devices.
+The QGIS developers can't test all of them, so if you have one that does not work with any of the device types listed in the \tab{Download from GPS} and \tab{Upload to GPS} tools you can define your own device type for it.
+You do this by using the GPS device editor, which you start by clicking the \button{Edit devices} button in the download or the upload window.
-To define a new device you simply click the \emph{New device} button,
-enter a name, a download command and an upload command for your device,
-and click the \emph{Update device} button. The name will be listed in the
-device menus in the upload and download windows, and can be any string.
+To define a new device you simply click the \button{New device} button, enter a name, a download command and an upload command for your device, and click the \button{Update device} button.
+The name will be listed in the device menus in the upload and download windows, and can be any string.
+The download command is the command that is used to download data from the device to a GPX file.
+This will probably be a GPSBabel command, but you can use any other command line program that can create a GPX file.
+QGIS will replace the keywords \emph{\%type}, \emph{\%in}, and \emph{\%out} when it runs the command.
-The download command is the command that is used to download data
-from the device to a GPX file. This will probably be a GPSBabel command,
-but you can use any other command line program that can create a GPX
-file. QGIS will replace the keywords \emph{\%type}, \emph{\%in}, and
-\emph{\%out} when it runs the command.
+\emph{\%type} will be replaced by {}``-w'' if you are downloading waypoints, {}``-r'' if you are downloading routes and {}``-t'' if you are downloading tracks.
+These are command line options that tell GPSBabel which feature type to download.
-\emph{\%type} will be replaced by {}``-w'' if you are downloading
-waypoints, {}``-r'' if you are downloading routes and {}``-t''
-if you are downloading tracks. These are command line options that
-tell GPSBabel which feature type to download.
+\emph{\%in} will be replaced by the port name that you choose in the download window and \emph{\%out} will be replaced by the name you choose for the GPX file that the downloaded data should be stored in.
+So if you create a device type with the download command {}``gpsbabel \%type -i garmin -o gpx \%in \%out'' (this is actually the download command for the predefined device type {}``Garmin serial'') and then use it to download waypoints from port {}``/dev/ttyS0'' to the file {}``output.gpx'', QGIS will replace the keywords and run the command {}``gpsbabel -w -i garmin -o gpx /dev/ttyS0 output.gpx''.
-\emph{\%in} will be replaced by the port name that you choose in the
-download window and \emph{\%out} will be replaced by the name you
-choose for the GPX file that the downloaded data should be stored
-in. So if you create a device type with the download command {}``gpsbabel
-\%type -i garmin -o gpx \%in \%out'' (this is actually the download
-command for the predefined device type {}``Garmin serial'') and
-then use it to download waypoints from port {}``/dev/ttyS0'' to
-the file {}``output.gpx'', QGIS will replace the keywords and run
-the command {}``gpsbabel -w -i garmin -o gpx /dev/ttyS0 output.gpx''.
+The upload command is the command that is used to upload data to the device.
+The same keywords are used, but \emph{\%in} is now replaced by the name of the GPX file for the layer that is being uploaded, and \emph{\%out} is replaced by the port name.
-The upload command is the command that is used to upload data to the
-device. The same keywords are used, but \emph{\%in} is now replaced
-by the name of the GPX file for the layer that is being uploaded,
-and \emph{\%out} is replaced by the port name. You can learn more
-about GPSBabel and it's available command line options at
-\url{http://www.gpsbabel.org}
+You can learn more about GPSBabel and it's available command line options at \url{http://www.gpsbabel.org}
-Once you have created a new device type it will appear in the device
-lists for the download and upload tools.
+Once you have created a new device type it will appear in the device lists for the download and upload tools.
\ No newline at end of file
Modified: docs/trunk/english_us/user_guide/plugins_graticule_creator.tex
===================================================================
--- docs/trunk/english_us/user_guide/plugins_graticule_creator.tex 2008-08-02 12:09:23 UTC (rev 8982)
+++ docs/trunk/english_us/user_guide/plugins_graticule_creator.tex 2008-08-02 17:30:55 UTC (rev 8983)
@@ -1,9 +1,8 @@
\subsection{Using the Graticule Creator Plugin}
-The graticule creator allows to create a ``grid'' of points, line or
-polygons to cover our area of interest. All units must be entered in
-decimal degrees. The output is a shapefile which can be projected on the
-fly to match your other data.
+The graticule creator allows to create a ``grid'' of points, line or polygons to cover our area of interest.
+All units must be entered in decimal degrees.
+The output is a shapefile which can be projected on the fly to match your other data.
%\begin{figure}[ht]
%\begin{center}
@@ -16,16 +15,12 @@
\begin{enumerate}
\item Make sure the plugin is loaded.
-\item Click on the \textsl{Graticule Creator} tool on the plugins toolbar.
-\item Choose the type of graticule you wish to create: point, line or
- polygon.
-\item Enter the latitude and longitude for the lower left and upper right
- corners of the graticule.
-\item Enter the interval to be used in constructing the grid. You can
- enter different values for the X and Y directions (longitude, latitude)
+\item Click on the \toolbtntwo{grid_maker}{Graticule Creator} tool on the plugins toolbar.
+\item Choose the type of graticule you wish to create: point, line or polygon.
+\item Enter the latitude and longitude for the lower left and upper right corners of the graticule.
+\item Enter the interval to be used in constructing the grid. You can enter different values for the X and Y directions (longitude, latitude)
\item Choose the name and location of the shapefile to be created.
-\item Click \textsl{OK} to create the graticule and add it to the map
- canvas.
+\item Click \button{OK} to create the graticule and add it to the map canvas.
\end{enumerate}
Modified: docs/trunk/english_us/user_guide/plugins_python.tex
===================================================================
--- docs/trunk/english_us/user_guide/plugins_python.tex 2008-08-02 12:09:23 UTC (rev 8982)
+++ docs/trunk/english_us/user_guide/plugins_python.tex 2008-08-02 17:30:55 UTC (rev 8983)
@@ -1,46 +1,39 @@
\subsection{Using the Python Plugin}
-Writing plugins in Python is much simpler than using C++. To create a PyQGIS
-plugin, you need QGIS 0.9, Python, PyQt, and the Qt developer tools
-\cite{sherman07}.
+Writing plugins in Python is much simpler than using C++.
+To create a PyQGIS plugin, you need QGIS 0.9, Python, PyQt, and the Qt developer tools \cite{sherman07}.
-When QGIS starts up it scans certain directories looking for both C++ and
-Python plugins. For a file (shared library, DLL, or python script) to be
-recognized as a plugin it has to have a specific signature. For Python scripts
-it's pretty simple. QGIS looks in the following locations under the
-installation directory:
+When QGIS starts up it scans certain directories looking for both C++ and Python plugins.
+For a file (shared library, DLL, or python script) to be recognized as a plugin it has to have a specific signature.
+For Python scripts it's pretty simple.
+QGIS looks in the following locations under the installation directory:
+
\begin{itemize}
-\item \textbf{Linux and other Unix}: ./share/qgis/python/plugins
-\item \textbf{Mac OS X}: ./Contents/MacOS/share/qgis/python/plugins
-\item \textbf{Windows}: .\textbackslash share\textbackslash QGIS\textbackslash
-python\textbackslash plugins
+\item \nix{Linux and other Unix}: ./share/qgis/python/plugins
+\item \osx{Mac OS X}: ./Contents/MacOS/share/qgis/python/plugins
+\item \win{Windows}: .\textbackslash share\textbackslash QGIS\textbackslash python\textbackslash plugins
\end{itemize}
-Each Python plugin is contained in its own directory. When QGIS starts up it will
-scan each subdirectory in \textsl{share/qgis/python/plugins} and initialize
-any plugins it finds. Once that's done, the plugin will show up in the plugin
-manager.
+Each Python plugin is contained in its own directory.
+When QGIS starts up it will scan each subdirectory in \textsl{share/qgis/python/plugins} and initialize any plugins it finds.
+Once that's done, the plugin will show up in the \dropmenuopttwo{mActionShowPluginManager}{Plugin Manager...}
-Let's create a plugin to fill a gap in the QGIS interface. This plugin will
-allow us to create a new PostGIS layer for us to digitize. It will be a
-simple plugin and pretty rough, but it illustrates how to get started
-writing your own PyQGIS plugins.
+Let's create a plugin to fill a gap in the QGIS interface.
+This plugin will allow us to create a new PostGIS layer for us to digitize.
+It will be a simple plugin and pretty rough, but it illustrates how to get started writing your own PyQGIS plugins.
\subsubsection{Setting up the Structure}
-The first thing we need to do is set up the structure for our plugin. In
-this example we'll be developing our plugin on Linux but the method is
-the same, just adapt some of the file system commands as appropriate for
-your platform. QGIS is installed in a directory named
-\textsl{qgis\_09} in our home directory. Let's create the directory for
-the plugin.
+The first thing we need to do is set up the structure for our plugin.
+In this example we'll be developing our plugin on \nix{Linux} but the method is the same, just adapt some of the file system commands as appropriate for your platform.
+QGIS is installed in a directory named \textsl{qgis} in our home directory.
+Let's create the directory for the plugin.
\begin{verbatim}
-mkdir ~/qgis_09/share/qgis/python/plugins/new_layer
+mkdir ~/qgis/share/qgis/python/plugins/new_layer
\end{verbatim}
-To get started, we need to create the following files in the \textsl{new\_layer} directory
- (we'll need some additional files in a bit):
+To get started, we need to create the following files in the \textsl{new\_layer} directory (we'll need some additional files in a bit):
\begin{verbatim}
__init__.py
@@ -51,8 +44,8 @@
\subsubsection{Making the Plugin Recognizable}
-Initializing the plugin is done in the \textsl{\_\_init\_\_.py} script. For our
-\textsl{NewLayer} plugin the script contains:
+Initializing the plugin is done in the \textsl{\_\_init\_\_.py} script.
+For our \textsl{NewLayer} plugin the script contains:
\begin{verbatim}
1 # load NewLayer class from file newlayer.py
@@ -67,19 +60,15 @@
10 return NewLayer(iface)
\end{verbatim}
-The mandatory things a plugin must return are a name, description, and
-version, all of which are implemented in our script above. Each method
-simply returns a string with the appropriate information. The other
-requirement is the \textsl{classFactory} method that must
-return a reference to the plugin itself (line 10), after
-receiving the \textbf{iface} object as an argument. With this simple code,
-QGIS will recognize our script as a plugin.
+The mandatory things a plugin must return are a name, description, and version, all of which are implemented in our script above.
+Each method simply returns a string with the appropriate information.
+The other requirement is the \textsl{classFactory} method that must return a reference to the plugin itself (line 10), after receiving the \textbf{iface} object as an argument.
+With this simple code, QGIS will recognize our script as a plugin.
\subsubsection{Resources}
-In order to have a nice icon for our plugin, we need a resources file
-which we'll name \textsl{resources.qrc}. This is just a simple XML
-file that defines the icon resource:
+In order to have a nice icon for our plugin, we need a resources file which we'll name \textsl{resources.qrc}.
+This is just a simple XML file that defines the icon resource:
\begin{verbatim}
<RCC>
@@ -89,49 +78,39 @@
</RCC>
\end{verbatim}
-The resource file uses a prefix to prevent naming clashes with other
-plugins - using the name of the plugin is usually sufficient.
-The \textsl{icon.png} file is is just a PNG image that will be used
-in the toolbar when the plugin is activated. You can use any image,
-as long as it's 22x22 pixels (so it fits on the toolbar).
+The resource file uses a prefix to prevent naming clashes with other plugins - using the name of the plugin is usually sufficient.
+The \textsl{icon.png} file is is just a PNG image that will be used in the toolbar when the plugin is activated.
+You can use any image, as long as it's 22x22 pixels (so it fits on the toolbar).
-To turn the resource file into something the plugin can use, it must be
-compiled using the PyQt resource compiler:
+To turn the resource file into something the plugin can use, it must be compiled using the PyQt resource compiler:
\begin{verbatim}
pyrcc4 -o resources.py resources.qrc
\end{verbatim}
-The \textsl{-o} switch is used to specify the output file. Now that we
-have resources, we need a way to collect the information needed for creating
-a new layer.
+The \textsl{-o} switch is used to specify the output file.
+Now that we have resources, we need a way to collect the information needed for creating a new layer.
\subsubsection{Creating the GUI}
-Normally we would use the same tool that C++ developers use to create a
-GUI: Qt Designer. This is a visual design tool that allows you to create
-dialog and main windows by dragging and dropping widgets and defining
-their properties.
+Normally we would use the same tool that C++ developers use to create a GUI: Qt Designer.
+This is a visual design tool that allows you to create dialog and main windows by dragging and dropping widgets and defining their properties.
-To design our NewLayer plugin we could get quite fancy and include widgets
-for field types and other options. However, since our time is limited, we'll
-use another means to collect the information we need to create the table.
-This will illustrate the concepts and then you can venture further using the
-tutorials on the QGIS blog.
+To design our NewLayer plugin we could get quite fancy and include widgets for field types and other options.
+However, since our time is limited, we'll use another means to collect the information we need to create the table.
+This will illustrate the concepts and then you can venture further using the tutorials on the QGIS blog.
-To collect the user input, we'll use the \textsl{QInputDialog} class from
-the Qt library. This prompts the user for a single line of input. While it
-will make our plugin a little crude, it serves to illustrate the concepts.
+To collect the user input, we'll use the \textsl{QInputDialog} class from the Qt library.
+This prompts the user for a single line of input.
+While it will make our plugin a little crude, it serves to illustrate the concepts.
-All we need to write now is the Python code to collect the input and create
-the table.
+All we need to write now is the Python code to collect the input and create the table.
\subsubsection{Creating the Plugin}
-Now that we have the preliminaries out of the way, we can get down to writing
-the code that does the actual work. Let's start by looking at the things we
-need to import and the initialization of the plugin in \textsl{newlayer.py}.
-
+Now that we have the preliminaries out of the way, we can get down to writing the code that does the actual work.
+Let's start by looking at the things we need to import and the initialization of the plugin in \textsl{newlayer.py}.
+
\begin{verbatim}
1 # Import the PyQt and QGIS libraries
2 from PyQt4.QtCore import *
@@ -164,41 +143,30 @@
29 self.iface.removeToolBarIcon(self.action)
\end{verbatim}
-In lines 2 through 7 we import the libraries needed for the plugin.
-This includes the PyQt libraries, the QGIS core library, and the Python
-PostgreSQL library psycopg. Every Python script that uses the QGIS
-libraries and PyQt needs to import the QtCore and QtGui libraries, as
-well as the QGIS core library.
-This gives us access to the PyQt wrappers for our Qt objects (like our
-input dialog) and the QGIS core libraries. We also need to import the
-\textsl{resources.py} file we created with the icon definition.
+In lines 2 through 7 we import the libraries needed for the plugin.
+This includes the PyQt libraries, the QGIS core library, and the Python PostgreSQL library psycopg.
+Every Python script that uses the QGIS libraries and PyQt needs to import the QtCore and QtGui libraries, as well as the QGIS core library.
+This gives us access to the PyQt wrappers for our Qt objects (like our input dialog) and the QGIS core libraries.
+We also need to import the \textsl{resources.py} file we created with the icon definition.
-In line 10 we declare the class \textbf{NewLayer}. In the \textsl{\_\_init\_\_}
-method (lines 12 through 14) our class is initialized and passed the
-\textbf{iface} object from QGIS via the \textsl{classFactory} method
-in line 10 of \_\_init\_\_.py. We store \textbf{iface} as a
-member variable so we can use it later.
+In line 10 we declare the class \textbf{NewLayer}.
+In the \textsl{\_\_init\_\_} method (lines 12 through 14) our class is initialized and passed the \textbf{iface} object from QGIS via the \textsl{classFactory} method in line 10 of \_\_init\_\_.py.
+We store \textbf{iface} as a member variable so we can use it later.
+In lines 16 through 24 we initialize the GUI elements for the plugin.
+In Qt, a \textbf{QAction} is used to create a user interface action that can be used to create both a menu and toolbar item.
+In our plugin, we use it for both.
+In line 18 we create the action using our icon resource (note the prefix we specified in \textsl{resources.qrc}).
+We also provide some text that will appear when it is used in a menu or during a mouseover, and lastly we need to specify the ``parent''.
+In a plugin, the parent is the main window of QGIS.
+The \textbf{iface} object that we stored during initialization allows us to get the reference to the main window in line 19.
-In lines 16 through 24 we initialize the GUI
-elements for the plugin. In Qt, a \textbf{QAction} is used to create a
-user interface action that can be used to create both a menu and toolbar
-item. In our plugin, we use it for both. In line 18 we create the
-action using our icon resource (note the prefix we specified in
-\textsl{resources.qrc}). We also provide some text that will appear when
-it is used in a menu or during a mouseover, and lastly we need to specify
-the ``parent''. In a plugin, the parent is the main window of QGIS. The
-\textbf{iface} object that we stored during initialization allows us to
-get the reference to the main window in line 19.
+Once the action is created, we can add it to both the toolbar and the \textsl{Plugins} menu (lines 23 and 24).
+That takes care of initializing the GUI for the plugin.
+The other thing we need to do is clean up after ourself when the plugin is unloaded.
+The \textsl{unload} method takes care of this by removing the menu item and the tool from the toolbar (lines 28 and 29).
-Once the action is created, we can add it to both the toolbar and the
-\textsl{Plugins} menu (lines 23 and 24).
-That takes care of initializing the GUI for the plugin. The other thing we
-need to do is clean up after ourself when the plugin is unloaded. The
-\textsl{unload} method takes care of this by removing
-the menu item and the tool from the toolbar (lines 28 and 29).
-
-This takes care of the initialization stuff and getting our plugin to load
-and unload nicely. Now let's look at the code that does the actual work.
+This takes care of the initialization stuff and getting our plugin to load and unload nicely.
+Now let's look at the code that does the actual work.
It's all contained in the \textsl{run} method.
\begin{verbatim}
@@ -236,8 +204,8 @@
61 con.commit()
\end{verbatim}
-The first thing we need to do is use the \textbf{QInputDialog} to get the
-name of the table to create. This is done in line 32 where we prompt for it.
+The first thing we need to do is use the \textbf{QInputDialog} to get the name of the table to create.
+This is done in line 32 where we prompt for it.
%\begin{figure}[ht]
%\begin{center}
@@ -246,14 +214,13 @@
%\end{center}
%\end{figure}
-In line 34 we check to see if the user actually entered anything before
-proceeding.
+In line 34 we check to see if the user actually entered anything before proceeding.
-Next we need to get the field names. For this example we are keeping it very
-simple. Every field will be a varchar(10), meaning we can store up to 10
-characters in it. If we really want to make this plugin useful, we would need
-to provide a way for the user to specify the type. In line 36 we
-prompt the user to enter a comma delimited list of field names.
+Next we need to get the field names.
+For this example we are keeping it very simple.
+Every field will be a varchar(10), meaning we can store up to 10 characters in it.
+If we really want to make this plugin useful, we would need to provide a way for the user to specify the type.
+In line 36 we prompt the user to enter a comma delimited list of field names.
%\begin{figure}[ht]
%\begin{center}
@@ -262,25 +229,21 @@
%\end{center}
%\end{figure}
-We then split this list into its components for use in constructing the SQL
-statement (line 38).
+We then split this list into its components for use in constructing the SQL statement (line 38).
-Line 40 contains the first part of the SQL statement. Note we are
-creating the table with an integer id field that will be the primary key. We
-then iterate through the field list, appending the appropriate code to the
-SQL statement (line 41).
+Line 40 contains the first part of the SQL statement.
+Note we are creating the table with an integer id field that will be the primary key.
+We then iterate through the field list, appending the appropriate code to the SQL statement (line 41).
-Once we have all the fields added to the SQL statement, we chop off the
-trailing characters we don't want (line 43) and then add
-the closing parenthesis to complete the statement (line 44).
+Once we have all the fields added to the SQL statement, we chop off the trailing characters we don't want (line43) and then add the closing parenthesis to complete the statement (line 44).
-Now we are ready to connect to the database and create the table. To access
-the database, we are using psycopg (\url{http://www.initd.org}). In order
-to connect we need to specify the data source name (DSN) with the name of
-the database, the user, and a password if necessary. If we are running both
-QGIS and PostgreSQL on the same machine we usually don't need to specify a
-password. In this case, the DSN will look something like this:
+Now we are ready to connect to the database and create the table.
+To access the database, we are using psycopg (\url{http://www.initd.org}).
+In order to connect we need to specify the data source name (DSN) with the name of the database, the user, and a password if necessary.
+If we are running both QGIS and PostgreSQL on the same machine we usually don't need to specify a password.
+In this case, the DSN will look something like this:
+
\begin{center}
\textsl{dbname=gis\_data user=gsherman}
\end{center}
@@ -294,25 +257,20 @@
%\end{center}
%\end{figure}
-If the user enters a DSN then we can proceed with the connection to the
-database in line 50. We get a cursor from the connection in
-line 51 and then execute the SQL statement to create the
-table and commit the change in lines 52 through 53.
-This creates the table, but for it to be a valid layer and ready for us to
-use it needs a couple more things.
+If the user enters a DSN then we can proceed with the connection to the database in line 50.
+We get a cursor from the connection in line 51 and then execute the SQL statement to create the table and commit the change in lines 52 through 53.
-First it needs a geometry column. We purposely didn't include one
-when we created the table so we could use the \textsl{AddGeometryColumn}
-function to create it. This function adds a geometry column to the table
-and then puts an entry in the \textsl{geometry\_columns} table for us. In
-line 55 we specify the table name, the name we want for the
-geometry column, the SRID, feature type, and the dimension of the feature.
+This creates the table, but for it to be a valid layer and ready for us touse it needs a couple more things.
-The last thing to do is create a spatial index on the table so we get
-optimum performance when doing spatial searches and displaying the data
-in QGIS. In line 59 we have cobbled together the SQL to create the
-index. The actual statement looks like this:
+First it needs a geometry column.
+We purposely didn't include one when we created the table so we could use the \textsl{AddGeometryColumn} function to create it. This function adds a geometry column to the table and then puts an entry in the \textsl{geometry\_columns} table for us.
+In line 55 we specify the table name, the name we want for the geometry column, the SRID, feature type, and the dimension of the feature.
+The last thing to do is create a spatial index on the table so we get optimum performance when doing spatial searches and displaying the data in QGIS.
+In line 59 we have cobbled together the SQL to create the index.
+
+The actual statement looks like this:
+
\begin{verbatim}
create index sidx_park_land on park_land
USING GIST(the_geom GIST_GEOMETRY_OPS);
@@ -320,12 +278,11 @@
\subsubsection{Issues and Problems}
-Our plugin is now complete. Now lets look at some of the things that are
-wrong with it or where we could improve it:
+Our plugin is now complete.
+Now lets look at some of the things that are wrong with it or where we could improve it:
\begin{itemize}
-\item We could use an improved GUI, one that lets the user enter all the
- needed information on one dialog
+\item We could use an improved GUI, one that lets the user enter all the needed information on one dialog
\item The user can't specify field types
\item There is limited error checking in the dialog
\begin{itemize}
@@ -335,14 +292,12 @@
\item There is no feedback from the plugin once it completes
\end{itemize}
-With all the issues, it still serves as a primordial plugin that illustrates
-the process and helps get you started with your own plugin development.
+With all the issues, it still serves as a primordial plugin that illustrates the process and helps get you started with your own plugin development.
\subsubsection{Adding Feedback}
-Let's fix one of the small problems by adding some feedback at the end of
-the process. We'll just add a message box to tell the user that everything
-is done and to check the database to make sure the table was created.
+Let's fix one of the small problems by adding some feedback at the end of the process.
+We'll just add a message box to tell the user that everything is done and to check the database to make sure the table was created.
To do this, we just add the following code after line 61:
@@ -362,18 +317,14 @@
%\end{figure}
\subsubsection{Summary}
-Writing a QGIS plugin in Python is pretty easy. Some plugins won't require a
-GUI at all. For example, you might write a plugin that returns the map
-coordinates for the point you click on the map. Such a plugin wouldn't
-require any user input and could use a standard Qt \textbf{QMessageBox}
-to display the result.
+Writing a QGIS plugin in Python is pretty easy.
+Some plugins won't require a GUI at all.
+For example, you might write a plugin that returns the map coordinates for the point you click on the map.
+Such a plugin wouldn't require any user input and could use a standard Qt \textbf{QMessageBox} to display the result.
-You can also write plugins for QGIS in C++, but that's another story. You can
-find tutorials on writing QGIS plugins in both C++ and Python on the QGIS
-blog at:
+You can also write plugins for QGIS in C++, but that's another story.
+You can find tutorials on writing QGIS plugins in both C++ and Python on the QGIS blog at:
\begin{center}
\url{http://blog.qgis.org}
-\end{center}
-
-% vim:tw=76:autoindent
+\end{center}
\ No newline at end of file
More information about the QGIS-commit
mailing list