[QGIS Commit] r9374 - docs/trunk/english_us/user_guide
svn_qgis at osgeo.org
svn_qgis at osgeo.org
Mon Sep 22 11:47:41 EDT 2008
Author: dassau
Date: 2008-09-22 11:47:41 -0400 (Mon, 22 Sep 2008)
New Revision: 9374
Added:
docs/trunk/english_us/user_guide/core_plugins.tex
docs/trunk/english_us/user_guide/external_plugins.tex
docs/trunk/english_us/user_guide/plugins.tex
docs/trunk/english_us/user_guide/plugins_mapserver_export.tex
docs/trunk/english_us/user_guide/plugins_writing_in_cpp.tex
docs/trunk/english_us/user_guide/plugins_writing_in_python.tex
Removed:
docs/trunk/english_us/user_guide/mapserver_export.tex
docs/trunk/english_us/user_guide/plugins.tex
docs/trunk/english_us/user_guide/plugins_python.tex
Modified:
docs/trunk/english_us/user_guide/creating_applications.tex
docs/trunk/english_us/user_guide/user_guide.tex
Log:
restructured plugin chapters
Copied: docs/trunk/english_us/user_guide/core_plugins.tex (from rev 9373, docs/trunk/english_us/user_guide/plugins.tex)
===================================================================
--- docs/trunk/english_us/user_guide/core_plugins.tex (rev 0)
+++ docs/trunk/english_us/user_guide/core_plugins.tex 2008-09-22 15:47:41 UTC (rev 9374)
@@ -0,0 +1,64 @@
+\section{Using QGIS Core Plugins}\label{sec:core_plugins}\index{plugins!core}
+
+QGIS currently contains 11 core plugins that can be loaded using the Plugin Manager.
+Table \ref{tab:core_plugins} lists each of the core plugins along with a description of their purpose and the toolbar-icon.
+Note the GRASS plugin is not included below because it installs its own toolbar (see section \ref{sec:grass} for a discussion of available features in the GRASS plugin).
+
+% minipage is needed to appear the footnote under the table
+% SH
+\begin{minipage}{\textwidth}
+\begin{table}[H]
+\centering
+\caption{QGIS Core Plugins}\label{tab:core_plugins}\medskip
+\small
+ \begin{tabular}{|l|l|p{4in}|}
+\hline \textbf{Icon} & \textbf{Plugin} & \textbf{Description} \\
+\hline
+% WHICH ICON TO CHOOSE HERE?
+\includegraphics[width=0.7cm]{delimited_text}
+ & Delimited Text \index{plugins!delimited text}& Load a delimited text file containing x,y coordinates as a point layer \\
+\hline
+\includegraphics[width=0.7cm]{copyright_label}
+ & Copyright Label \index{plugins!copyright}& Display a copyright label on the map canvas\\
+\hline
+\includegraphics[width=0.7cm]{gps_importer}
+ & GPS Tools \index{plugins!gps}& Load and display GPS data \\
+\hline
+\includegraphics[width=0.7cm]{georeferencer}
+ & Georeferencer \index{plugin!georeferencer} & Georeferencing rasterlayers \\
+\hline
+\includegraphics[width=0.7cm]{grid_maker}
+ & Graticule Creator \index{plugins!graticule}& Create a latitude/longitude grid and save as a shapefile\\
+\hline
+\includegraphics[width=0.7cm]{north_arrow}
+& North Arrow \index{plugins!north arrow}& Add a north arrow to the map canvas\\
+\hline
+\includegraphics[width=0.7cm]{icon_buffer}
+ & PostgreSQL Geoprocessing \index{plugins!geoprocessing}& Buffer a PostGIS layer \\
+\hline
+\includegraphics[width=0.7cm]{quick_print}
+ & Quick Print \index{plugins!quickprint}& Quickly print a map \\
+\hline
+\includegraphics[width=0.7cm]{spiticon}
+ & SPIT \index{plugins!spit}& Shapefile to PostGIS Import Tool - import shapefiles into PostgreSQL\\
+\hline
+\includegraphics[width=0.7cm]{scale_bar}
+ & Scalebar \index{plugins!scalebar}& Add a scalebar to the map canvas\\
+\hline
+\includegraphics[width=0.7cm]{mIconAddWfsLayer}
+ & WFS & Load and display WFS layer \\
+\hline
+\end{tabular}
+\end{table}
+\end{minipage}
+
+\normalsize
+
+
+\begin{Tip}\caption{\textsc{Plugins Settings Saved to Project}}\index{plugins
+settings}
+\qgistip{When you save a .qgs project, any changes you have made to NorthArrow, ScaleBar and Copyright plugins will be saved in the project and restored next time you load the project.
+}
+\end{Tip}
+
+
Property changes on: docs/trunk/english_us/user_guide/core_plugins.tex
___________________________________________________________________
Name: svn:mergeinfo
+
Modified: docs/trunk/english_us/user_guide/creating_applications.tex
===================================================================
--- docs/trunk/english_us/user_guide/creating_applications.tex 2008-09-22 13:58:05 UTC (rev 9373)
+++ docs/trunk/english_us/user_guide/creating_applications.tex 2008-09-22 15:47:41 UTC (rev 9374)
@@ -1,4 +1,4 @@
-\section{Creating Applications}
+\section{Creating PyQGIS Applications}
% when the revision of a section has been finalized,
% comment out the following line:
Added: docs/trunk/english_us/user_guide/external_plugins.tex
===================================================================
--- docs/trunk/english_us/user_guide/external_plugins.tex (rev 0)
+++ docs/trunk/english_us/user_guide/external_plugins.tex 2008-09-22 15:47:41 UTC (rev 9374)
@@ -0,0 +1,13 @@
+\section{Using external QGIS Plugins}\label{sec:external_plugins}\index{plugins}
+
+% when the revision of a section has been finalized,
+% comment out the following line:
+\updatedisclaimer
+
+An external QGIS plugin is stored in an external svn repository and
+maintained by the individual author. It can be added to QGIS with the Plugin
+installer. QGIS core plugins are maintained by the QGIS Development Team
+and part of every QGIS distribution. You find more information about QGIS
+core plugins in Section \ref{sec:core_plugins}.
+
+\newpage
Deleted: docs/trunk/english_us/user_guide/mapserver_export.tex
===================================================================
--- docs/trunk/english_us/user_guide/mapserver_export.tex 2008-09-22 13:58:05 UTC (rev 9373)
+++ docs/trunk/english_us/user_guide/mapserver_export.tex 2008-09-22 15:47:41 UTC (rev 9374)
@@ -1,142 +0,0 @@
-\section{Making MapServer Map Files}\label{sec:mapserver_export}
-
-% when the revision of a section has been finalized,
-% comment out the following line:
-\updatedisclaimer
-
-QGIS can be used to create map files for MapServer. You use QGIS to
-``compose'' your map by adding and arranging layers, symbolizing them, and
-customizing the colors.
-
-In order to use the MapServer exporter, you must have Python on your
-system and QGIS must have been compiled with support for it.
-
-\subsection{Creating the Project File}
-
-To create a MapServer map file:
-
-\begin{enumerate}
-\item Add your layers to QGIS
-\item Symbolize your layers, setting the renderer and colors
-\item Arrange the layers in the order you want them to appear in MapServer
-\item Save your work to a QGIS project file
-\end{enumerate}
-
-This gets us to the point where we are ready to create the map file.
-
-\begin{Tip}\caption{\textsc{MapServer Export Requires a QGIS Project File}}
-\qgistip{This has been a source of confusion for a number of people. The
-MapServer export tool operates on a saved QGIS project file,
-\textbf{not} the current contents of the map canvas and legend. When
-using the tool, you need to specify a QGIS project file as input.
-}
-\end{Tip}
-
-\subsection{Creating the Map File}
-
-The exporter tool (\filename{msexport}) is installed in your QGIS binary directory and can be used independently of QGIS.
-
-From QGIS you can start the exporter by choosing \mainmenuopt{File} > \dropmenuopt{Export to MapServer Map...}.
-
-Here is a summary of the input fields:
-
-\begin{description}
-\item [Map file] \mbox{}\\
-Enter the name for the map file to be created. You can use the button at the right to browse for the directory where you want the map file created.
-
-\item [Qgis project file] \mbox{}\\
-Enter the full path to the QGIS project file (.qgs) you want to export. You can use the button at the right to browse for the QGIS project file.
-\item [Map Name] \mbox{}\\
-A name for the map. This name is prefixed to all images generated by the mapserver.
-\item [Map Width] \mbox{}\\
-Width of the output image in pixels.
-
-\item [Map Height] \mbox{}\\
-Height of the output image in pixels.
-\item [Map Units] \mbox{}\\
-Units of measure used for output
-\item [Image type] \mbox{}\\
-Format for the output image generated by MapServer
-\item [Web Template] \mbox{}\\
-Full path to the MapServer template file to be used with the map file
-\item [Web Header] \mbox{}\\
-Full path to the MapServer header file to be used with the map file
-\item [Web Footer] \mbox{}\\
-Full path to the MapServer footer file to be used with the map file
-\end{description}
-
-Only the Map file and QGIS project file inputs are required to create a
-map file, however you may end up with a non-functional map file, depending
-on your intended use. Although QGIS is good at creating a map file from
-your project file, it may require some tweaking to get the results you
-want - but it's still way better than writing a map file from scratch.
-
-\minisec{Creating a Map File}
-
-Let's create a map file using the shape files \filename{alaska}, \filename{lakes}
-and \filename{rivers} layers from the qgis\_sample\_data:
-
-\begin{enumerate}
- \item Load the \filename{alaska}, \filename{rivers} and \filename{lakes}
- layers into QGIS
- \item Change the colors and symbolize the data as you like
- \item Save the project using \mainmenuopt{File} >
- \dropmenuopttwo{mActionFileSave}{Save Project}.
- \item Open the exporter by clicking mainmenuopt{File} > \dropmenuopt{Export
- to MapServer Map...}.
- \item Enter a name for your new map file
- \item Browse and find the project file you just saved
- \item Enter a name for the map
- \item Enter 600 for the width and 400 for the height
- \item Our layers are in decimal degrees so we don't need to change the
- units
- \item Choose ``png'' for the image type
- \item Click \button{OK} to generate the map file
-\end{enumerate}
-
-
-%\begin{figure}[ht]
-%\begin{center}
-% \caption{Export to MapServer map module in QGIS}\label{fig:mapserver_export}\smallskip
-% \includegraphics[clip=true, width=0.8\textwidth]{mapserver_export}
-%\end{center}
-%\end{figure}
-
-You'll notice there is no feedback on the success of your efforts. This
-is an enhancement scheduled for the next version.
-
-You can view the map file in an text editor or visualizer. If you
-take a look, you'll notice that the export tool adds the metadata needed
-to enable our map file for WMS.
-
-\subsection{Testing the Map File}
-
-Let's test our work by using the \filename{shp2img} command to create an image
-from the map file. The \filename{shp2img} utility is part of MapServer,
-but is also distributed with FWTools. To create an image from our map:
-
-\begin{itemize}
-\item Open a terminal window
-\item If you didn't save your map file in your home directory, change to
- the directory where you saved it
-\item Run \filename{shp2img}
-\item View the created image
-\end{itemize}
-
-Assuming our map file was named \filename{mapserver\_test.map}, the
-\filename{shp2img} command is:
-
-\begin{verbatim}
-shp2img -m mapserver_test.map -o mapserver_test.png
-\end{verbatim}
-
-This creates a PNG for us to view, containing all the layers that were on
-when we saved the QGIS project. In addition, the extent of the PNG will be the same as
-when we saved the project.
-
-If you plan to use the map file to serve WMS requests, you probably don't
-have to tweak anything. If you plan to use it with a mapping template or a
-custom interface, you may have a bit of manual work to do. To see how easy
-it is to go from QGIS to serving maps on the web, take a look at
-Christopher Schmidt's 5 minute flash video.
-\footnote{\url{http://openlayers.org/presentations/mappingyourdata/}}
Deleted: docs/trunk/english_us/user_guide/plugins.tex
===================================================================
--- docs/trunk/english_us/user_guide/plugins.tex 2008-09-22 13:58:05 UTC (rev 9373)
+++ docs/trunk/english_us/user_guide/plugins.tex 2008-09-22 15:47:41 UTC (rev 9374)
@@ -1,164 +0,0 @@
-\section{Using Plugins}\index{plugins}
-
-% when the revision of a section has been finalized,
-% comment out the following line:
-\updatedisclaimer
-
-%% FIXME: here we need to include new python plugin section and updates
-
-\subsection{An Introduction to Using Plugins}\label{label_introplugin}
-
-QGIS has been designed with a plugin architecture.
-This allows new features/functions to be added to the application.
-Many of the features in QGIS are actually implemented as plugins.
-
-There are two types of plugins in QGIS: core and user-contributed.
-\index{plugins!types} A core plugin is maintained by the QGIS development team and is part of every QGIS distribution.
-A user-contributed plugin is an external plugin that is maintained by the individual author.
-The QGIS SVN website (\url{http://svn.qgis.org}) serves some user contributed plugins.
-
-\subsubsection{Finding and Installing a Plugin}
-When you install QGIS, all of the core plugins are included (see chapter \ref{sec:core_plugins}). \index{plugins!installing}
-% Additional user-contributed
-% plugins may be available on the QGIS Community site. To see what
-% user-contributed plugins are available, see the plugins page on the Community
-% site (\url{http://community.qgis.org/plugins}).\index{plugins!user
-% contributed}
-
-Typically user-contributed plugins are distributed in source form and require compiling.
-For instructions on building and installing a user-contributed plugin, see the documentation included with the plugin.
-
-\subsubsection{Managing Plugins}\label{sec:managing_plugins}
-\index{plugins!managing} Managing plugins consists of loading or unloading them from QGIS.
-Loaded plugins are "remembered" when you exit the application and restored the next time you run QGIS.
-
-To manage plugins, open \mainmenuopt{Plugins} > \dropmenuopttwo{mActionShowPluginManager}{Plugin Manager...}
-\index{plugins!manager}The Plugin Manager displays all the available plugins and their status (loaded or unloaded).
-Figure \ref{fig:pluginmanager} shows the Plugin Manager dialog.
-
-%\begin{figure}[ht]
-% \begin{center}
-% \caption{Plugin Manager}\label{fig:pluginmanager}\smallskip
-% \includegraphics[clip=true, width=14cm]{pluginmanager2}
-%\end{center}
-%\end{figure}
-
-Typically all QGIS plugins are installed in the same location.
-This location is shown in the Plugin Directory text field.
-You can tell QGIS to load plugins from another location by specifying a different directory.
-
-\begin{Tip}\caption{\textsc{Crashing Plugins}}\index{crashes}
-\qgistip{If you find that QGIS crashes on startup, a plugin may be at fault.
-You can stop all plugins from loading by editing your stored settings file (see \ref{subsec:gui_options} for location).
-Locate the plugins settings and change all the plugin values to false to prevent them from loading.
-\nix {For example, to prevent the Delimited text plugin from loading, the entry in \$HOME/.config/QuantumGIS/qgis.conf on Linux
-should look like this:\usertext{Add Delimited Text Layer=false}.}
-\normalfont
-Do this for each plugin in the [Plugins] section.
-You can then start QGIS and add the plugins one at a time from the Plugin Manger to determine which is causing the problem.
-}
-\end{Tip}
-
-\subsubsection{Data Providers}\index{data providers}
-
-Data Providers are "special" plugins that provides access to a data store.
-By default, QGIS supports PostGIS layers and disk-based data stores supported by the GDAL/OGR library (Appendix \ref{appdx_ogr}).
-A Data Provider plugin extends the ability of QGIS to use other data sources.
-
-Data Provider plugins are registered automatically by QGIS at startup.
-They are not managed by the Plugin Manager but are used behind the scenes when a corresponding data type is added as a layer in QGIS.
-
-\subsubsection{Core Plugins}\label{sec:core_plugins}\index{plugins!core}
-
-QGIS currently contains 11 core plugins that can be loaded using the Plugin Manager.
-Table \ref{tab:core_plugins} lists each of the core plugins along with a description of their purpose and the toolbar-icon.
-Note the GRASS plugin is not included below because it installs its own toolbar (see section \ref{sec:grass} for a discussion of available features in the GRASS plugin).
-
-% minipage is needed to appear the footnote under the table
-% SH
-\begin{minipage}{\textwidth}
-\begin{table}[H]
-\centering
-\caption{QGIS Core Plugins}\label{tab:core_plugins}\medskip
-\small
- \begin{tabular}{|l|l|p{4in}|}
-\hline \textbf{Icon} & \textbf{Plugin} & \textbf{Description} \\
-\hline
-% WHICH ICON TO CHOOSE HERE?
-\includegraphics[width=0.7cm]{delimited_text}
- & Delimited Text \index{plugins!delimited text}& Load a delimited text file containing x,y coordinates as a point layer \\
-\hline
-\includegraphics[width=0.7cm]{copyright_label}
- & Copyright Label \index{plugins!copyright}& Display a copyright label on the map canvas\\
-\hline
-\includegraphics[width=0.7cm]{gps_importer}
- & GPS Tools \index{plugins!gps}& Load and display GPS data \\
-\hline
-\includegraphics[width=0.7cm]{georeferencer}
- & Georeferencer \index{plugin!georeferencer} & Georeferencing rasterlayers \\
-\hline
-\includegraphics[width=0.7cm]{grid_maker}
- & Graticule Creator \index{plugins!graticule}& Create a latitude/longitude grid and save as a shapefile\\
-\hline
-\includegraphics[width=0.7cm]{north_arrow}
-& North Arrow \index{plugins!north arrow}& Add a north arrow to the map canvas\\
-\hline
-\includegraphics[width=0.7cm]{icon_buffer}
- & PostgreSQL Geoprocessing \index{plugins!geoprocessing}& Buffer a PostGIS layer \\
-\hline
-\includegraphics[width=0.7cm]{quick_print}
- & Quick Print \index{plugins!quickprint}& Quickly print a map \\
-\hline
-\includegraphics[width=0.7cm]{spiticon}
- & SPIT \index{plugins!spit}& Shapefile to PostGIS Import Tool - import shapefiles into PostgreSQL\\
-\hline
-\includegraphics[width=0.7cm]{scale_bar}
- & Scalebar \index{plugins!scalebar}& Add a scalebar to the map canvas\\
-\hline
-\includegraphics[width=0.7cm]{mIconAddWfsLayer}
- & WFS & Load and display WFS layer \\
-\hline
-\end{tabular}
-\end{table}
-\end{minipage}
-
-\normalsize
-
-
-\begin{Tip}\caption{\textsc{Plugins Settings Saved to Project}}\index{plugins
-settings}
-\qgistip{When you save a .qgs project, any changes you have made to NorthArrow, ScaleBar and Copyright plugins will be saved in the project and restored next time you load the project.
-}
-\end{Tip}
-
-%
-% External Plugins
-%
-\subsubsection{External Plugins}\label{sec:external_plugins}\index{plugins!external}
-
-QGIS also comes with some externally developed plugins.
-They are not shipped with the default distribution.
-However, they can be compiled and used within QGIS.
-
-Currently the external plugins are only available directly from SVN.
-To check out all available external plugins do the following:
-\begin{verbatim}
-svn co https://svn.osgeo.org/qgis/trunk/external_plugins external_qgis_plugins
-\end{verbatim}
-
-This will create a folder \usertext{external\_qgis\_plugins} in your current folder.
-Each subdirectory has its own compile and install instructions.
-Read them carefully in order to build the plugin.
-
-%
-% Plugin template
-%
-\subsubsection{Plugin templates}\label{sec:plugin_template}\index{plugins!template}
-
-If you like to develop your own QGIS-plugin the main sources include a nice script which guides you through the process of creating your own template-directory-structure within the QGIS-source-tree.
-The script lives in \usertext{QGIS/src/plugins/plugin\_builder.pl}.
-
-The only thing to do is coding your functions into the plugin (and of course contribute your plugin to the QGIS-development-team).
-
-Beside that the QGIS-wiki (\url{http://wiki.qgis.org}) and the QGIS-blog (\url{http://blog.qgis.org}) provide useful articles about writing your own plugin as well.
-Check the websites for details!
Added: docs/trunk/english_us/user_guide/plugins.tex
===================================================================
--- docs/trunk/english_us/user_guide/plugins.tex (rev 0)
+++ docs/trunk/english_us/user_guide/plugins.tex 2008-09-22 15:47:41 UTC (rev 9374)
@@ -0,0 +1,64 @@
+\section{QGIS Plugins}\index{plugins}
+
+% when the revision of a section has been finalized,
+% comment out the following line:
+\updatedisclaimer
+
+QGIS has been designed with a plugin architecture. This allows new
+features/functions to be added to the application. Many of the features in
+QGIS are actually implemented as core or external plugins.\index{plugins!types}
+
+A QGIS core plugin is maintained by the QGIS Development Team
+and is part of every QGIS distribution (see Section \ref{sec:core_plugins}).
+
+An external plugin is stored in an external svn repository and maintained
+by the individual author. It can be added to QGIS with the Plugin installer.
+You find more information about external plugins in Section
+\ref{sec:external_plugins}.
+
+\subsection{Finding and Installing a Plugin}
+When you install QGIS, all of the core plugins are included (see chapter \ref{sec:core_plugins}). \index{plugins!installing}
+
+Typically user-contributed plugins are distributed in source form and require compiling.
+For instructions on building and installing a user-contributed plugin, see the documentation included with the plugin.
+
+\subsection{Managing Plugins}\label{sec:managing_plugins}
+\index{plugins!managing} Managing plugins consists of loading or unloading them from QGIS.
+Loaded plugins are "remembered" when you exit the application and restored the next time you run QGIS.
+
+To manage plugins, open \mainmenuopt{Plugins} > \dropmenuopttwo{mActionShowPluginManager}{Plugin Manager...}
+\index{plugins!manager}The Plugin Manager displays all the available plugins and their status (loaded or unloaded).
+Figure \ref{fig:pluginmanager} shows the Plugin Manager dialog.
+
+%\begin{figure}[ht]
+% \begin{center}
+% \caption{Plugin Manager}\label{fig:pluginmanager}\smallskip
+% \includegraphics[clip=true, width=14cm]{pluginmanager2}
+%\end{center}
+%\end{figure}
+
+Typically all QGIS plugins are installed in the same location.
+This location is shown in the Plugin Directory text field.
+You can tell QGIS to load plugins from another location by specifying a different directory.
+
+\begin{Tip}\caption{\textsc{Crashing Plugins}}\index{crashes}
+\qgistip{If you find that QGIS crashes on startup, a plugin may be at fault.
+You can stop all plugins from loading by editing your stored settings file (see \ref{subsec:gui_options} for location).
+Locate the plugins settings and change all the plugin values to false to prevent them from loading.
+\nix {For example, to prevent the Delimited text plugin from loading, the entry in \$HOME/.config/QuantumGIS/qgis.conf on Linux
+should look like this:\usertext{Add Delimited Text Layer=false}.}
+\normalfont
+Do this for each plugin in the [Plugins] section.
+You can then start QGIS and add the plugins one at a time from the Plugin Manger to determine which is causing the problem.
+}
+\end{Tip}
+
+\subsection{Data Providers}\index{data providers}
+
+Data Providers are "special" plugins that provides access to a data store.
+By default, QGIS supports PostGIS layers and disk-based data stores supported by the GDAL/OGR library (Appendix \ref{appdx_ogr}).
+A Data Provider plugin extends the ability of QGIS to use other data sources.
+
+Data Provider plugins are registered automatically by QGIS at startup.
+They are not managed by the Plugin Manager but are used behind the scenes when a corresponding data type is added as a layer in QGIS.
+
Property changes on: docs/trunk/english_us/user_guide/plugins.tex
___________________________________________________________________
Name: svn:mergeinfo
+
Copied: docs/trunk/english_us/user_guide/plugins_mapserver_export.tex (from rev 9373, docs/trunk/english_us/user_guide/mapserver_export.tex)
===================================================================
--- docs/trunk/english_us/user_guide/plugins_mapserver_export.tex (rev 0)
+++ docs/trunk/english_us/user_guide/plugins_mapserver_export.tex 2008-09-22 15:47:41 UTC (rev 9374)
@@ -0,0 +1,140 @@
+\subsection{Making MapServer Map Files}\label{sec:mapserver_export}
+
+% when the revision of a section has been finalized,
+% comment out the following line:
+\updatedisclaimer
+
+QGIS can be used to create map files for MapServer. You use QGIS to
+``compose'' your map by adding and arranging layers, symbolizing them, and
+customizing the colors. In order to use the MapServer exporter, you must have Python on your
+system and QGIS must have been compiled with support for it.
+
+\subsubsection{Creating the Project File}
+
+To create a MapServer map file:
+
+\begin{enumerate}
+\item Add your layers to QGIS
+\item Symbolize your layers, setting the renderer and colors
+\item Arrange the layers in the order you want them to appear in MapServer
+\item Save your work to a QGIS project file
+\end{enumerate}
+
+This gets us to the point where we are ready to create the map file.
+
+\begin{Tip}\caption{\textsc{MapServer Export Requires a QGIS Project File}}
+\qgistip{This has been a source of confusion for a number of people. The
+MapServer export tool operates on a saved QGIS project file,
+\textbf{not} the current contents of the map canvas and legend. When
+using the tool, you need to specify a QGIS project file as input.
+}
+\end{Tip}
+
+\subsubsection{Creating the Map File}
+
+The exporter tool (\filename{msexport}) is installed in your QGIS binary directory and can be used independently of QGIS.
+
+From QGIS you can start the exporter by choosing \mainmenuopt{File} > \dropmenuopt{Export to MapServer Map...}.
+
+Here is a summary of the input fields:
+
+\begin{description}
+\item [Map file] \mbox{}\\
+Enter the name for the map file to be created. You can use the button at the right to browse for the directory where you want the map file created.
+
+\item [Qgis project file] \mbox{}\\
+Enter the full path to the QGIS project file (.qgs) you want to export. You can use the button at the right to browse for the QGIS project file.
+\item [Map Name] \mbox{}\\
+A name for the map. This name is prefixed to all images generated by the mapserver.
+\item [Map Width] \mbox{}\\
+Width of the output image in pixels.
+
+\item [Map Height] \mbox{}\\
+Height of the output image in pixels.
+\item [Map Units] \mbox{}\\
+Units of measure used for output
+\item [Image type] \mbox{}\\
+Format for the output image generated by MapServer
+\item [Web Template] \mbox{}\\
+Full path to the MapServer template file to be used with the map file
+\item [Web Header] \mbox{}\\
+Full path to the MapServer header file to be used with the map file
+\item [Web Footer] \mbox{}\\
+Full path to the MapServer footer file to be used with the map file
+\end{description}
+
+Only the Map file and QGIS project file inputs are required to create a
+map file, however you may end up with a non-functional map file, depending
+on your intended use. Although QGIS is good at creating a map file from
+your project file, it may require some tweaking to get the results you
+want - but it's still way better than writing a map file from scratch.
+
+\minisec{Creating a Map File}
+
+Let's create a map file using the shape files \filename{alaska}, \filename{lakes}
+and \filename{rivers} layers from the qgis\_sample\_data:
+
+\begin{enumerate}
+ \item Load the \filename{alaska}, \filename{rivers} and \filename{lakes}
+ layers into QGIS
+ \item Change the colors and symbolize the data as you like
+ \item Save the project using \mainmenuopt{File} >
+ \dropmenuopttwo{mActionFileSave}{Save Project}.
+ \item Open the exporter by clicking mainmenuopt{File} > \dropmenuopt{Export
+ to MapServer Map...}.
+ \item Enter a name for your new map file
+ \item Browse and find the project file you just saved
+ \item Enter a name for the map
+ \item Enter 600 for the width and 400 for the height
+ \item Our layers are in decimal degrees so we don't need to change the
+ units
+ \item Choose ``png'' for the image type
+ \item Click \button{OK} to generate the map file
+\end{enumerate}
+
+
+%\begin{figure}[ht]
+%\begin{center}
+% \caption{Export to MapServer map module in QGIS}\label{fig:mapserver_export}\smallskip
+% \includegraphics[clip=true, width=0.8\textwidth]{mapserver_export}
+%\end{center}
+%\end{figure}
+
+You'll notice there is no feedback on the success of your efforts. This
+is an enhancement scheduled for the next version.
+
+You can view the map file in an text editor or visualizer. If you
+take a look, you'll notice that the export tool adds the metadata needed
+to enable our map file for WMS.
+
+\subsubsection{Testing the Map File}
+
+Let's test our work by using the \filename{shp2img} command to create an image
+from the map file. The \filename{shp2img} utility is part of MapServer,
+but is also distributed with FWTools. To create an image from our map:
+
+\begin{itemize}
+\item Open a terminal window
+\item If you didn't save your map file in your home directory, change to
+ the directory where you saved it
+\item Run \filename{shp2img}
+\item View the created image
+\end{itemize}
+
+Assuming our map file was named \filename{mapserver\_test.map}, the
+\filename{shp2img} command is:
+
+\begin{verbatim}
+shp2img -m mapserver_test.map -o mapserver_test.png
+\end{verbatim}
+
+This creates a PNG for us to view, containing all the layers that were on
+when we saved the QGIS project. In addition, the extent of the PNG will be the same as
+when we saved the project.
+
+If you plan to use the map file to serve WMS requests, you probably don't
+have to tweak anything. If you plan to use it with a mapping template or a
+custom interface, you may have a bit of manual work to do. To see how easy
+it is to go from QGIS to serving maps on the web, take a look at
+Christopher Schmidt's 5 minute flash video.
+\footnote{\url{http://openlayers.org/presentations/mappingyourdata/}}
Property changes on: docs/trunk/english_us/user_guide/plugins_mapserver_export.tex
___________________________________________________________________
Name: svn:mergeinfo
+
Deleted: docs/trunk/english_us/user_guide/plugins_python.tex
===================================================================
--- docs/trunk/english_us/user_guide/plugins_python.tex 2008-09-22 13:58:05 UTC (rev 9373)
+++ docs/trunk/english_us/user_guide/plugins_python.tex 2008-09-22 15:47:41 UTC (rev 9374)
@@ -1,330 +0,0 @@
-\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}.
-
-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 \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 \filename{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.
-
-\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 \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 \filename{qgis} in our home directory.
-Let's create the directory for the plugin.
-
-\begin{verbatim}
-mkdir ~/qgis/share/qgis/python/plugins/new_layer
-\end{verbatim}
-
-To get started, we need to create the following files in the \filename{new\_layer} directory (we'll need some additional files in a bit):
-
-\begin{verbatim}
-__init__.py
-resources.py
-resources.qrc
-newlayer.py
-\end{verbatim}
-
-\subsubsection{Making the Plugin Recognizable}
-
-Initializing the plugin is done in the \filename{\_\_init\_\_.py} script.
-For our \filename{NewLayer} plugin the script contains:
-
-\begin{verbatim}
-1 # load NewLayer class from file newlayer.py
-2 from newlayer import NewLayer
-3 def name():
-4 return "New PostGIS layer"
-5 def description():
-6 return "Creates a new empty Postgis layer"
-7 def version():
-8 return "Version 0.1"
-9 def classFactory(iface):
-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 \method{classFactory} method that must return a reference to the plugin itself (line 10), after receiving the \object{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 \filename{resources.qrc}.
-This is just a simple XML file that defines the icon resource:
-
-\begin{verbatim}
- <RCC>
- <qresource prefix="/plugins/newlayer">
- <file>icon.png</file>
- </qresource>
-</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 \filename{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:
-
-\begin{verbatim}
- pyrcc4 -o resources.py resources.qrc
-\end{verbatim}
-
-The \filename{-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.
-
-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 \classname{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.
-
-\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 \filename{newlayer.py}.
-
-\begin{verbatim}
-1 # Import the PyQt and QGIS libraries
-2 from PyQt4.QtCore import *
-3 from PyQt4.QtGui import *
-4 from qgis.core import *
-5 import psycopg
-6 # Initialize Qt resources from file resources.py
-7 import resources
-8
-9 # Our main class for the plugin
-10 class NewLayer:
-11
-12 def __init__(self, iface):
-13 # Save reference to the QGIS interface
-14 self.iface = iface
-15
-16 def initGui(self):
-17 # Create action that will start plugin configuration
-18 self.action = QAction(QIcon(":/plugins/newlayer/icon.png"),\
-19 "New PosGIS Layer", self.iface.getMainWindow())
-20 QObject.connect(self.action, SIGNAL("activated()"), self.run)
-21
-22 # Add toolbar button and menu item
-23 self.iface.addToolBarIcon(self.action)
-24 self.iface.addPluginMenu("&New PostGIS Layer...", self.action)
-25
-26 def unload(self):
-27 # Remove the plugin menu item and icon
-28 self.iface.removePluginMenu("&New PostGIS Layer...",self.action)
-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 \filename{resources.py} file we created with the icon definition.
-
-In line 10 we declare the class \classname{NewLayer}.
-In the \method{\_\_init\_\_} method (lines 12 through 14) our class is initialized and passed the \object{iface} object from QGIS via the \method{classFactory} method in line 10 of \filename{\_\_init\_\_.py}.
-We store \object{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 \classname{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 \filename{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 \object{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 \mainmenuopt{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 \method{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.
-It's all contained in the \method{run} method.
-
-\begin{verbatim}
-30 def run(self):
-31 # Get the user input, starting with the table name
-32 table_name = QInputDialog.getText(None, "Table Name?", \
-33 "Name for new PostGIS layer")
-34 if table_name[0].length() > 0:
-35 # Get the field names and types
-36 fields = QInputDialog.getText(None, "Field Names", \
-37 "Fields (separate with a comma)")
-38 parts = fields[0].split(',')
-39 # Create the SQL statement
-40 sql = "create table " + table_name[0] + " (id int4 primary key, "
-41 for fld in parts:
-42 sql += fld + " varchar(10), "
-43 sql = sql[0:-2]
-44 sql += ")"
-45 # Connect to the database
-46 # First get the DSN
-47 dsn = QInputDialog.getText(None, "Database DSN", \
-48 "Enter the DSN for connecting to the database (dbname=db user=user)")
-49 if dsn[0].length() > 0:
-50 con = psycopg.connect(str(dsn[0]))
-51 curs = con.cursor()
-52 curs.execute(str(sql))
-53 con.commit()
-54 # add the geometry column
-55 curs.execute("select AddGeometryColumn('" + str(table_name[0]) + \
-56 "', 'the_geom', 4326, 'POLYGON', 2)")
-57 con.commit()
-58 # create the GIST index
-59 curs.execute("create index sidx_" + str(table_name[0]) + " on " + \
-60 str(table_name[0]) + " USING GIST(the_geom GIST_GEOMETRY_OPS)")
-61 con.commit()
-\end{verbatim}
-
-The first thing we need to do is use the \classname{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}
-% \caption{Enter new PostGIS table name}\label{fig:gettablename}\smallskip
-% \includegraphics[scale=0.8]{gettablename}
-%\end{center}
-%\end{figure}
-
-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.
-
-%\begin{figure}[ht]
-%\begin{center}
-% \caption{Enter field names for new PostGIS table}\label{fig:getfieldname}\smallskip
-% \includegraphics[scale=0.8]{getfieldname}
-%\end{center}
-%\end{figure}
-
-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).
-
-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:
-
-\begin{center}
- \textsl{dbname=gis\_data user=gsherman}
-\end{center}
-
-To get the DSN, we prompt the user with a \classname{QInputDialog} in line 47.
-
-%\begin{figure}[ht]
-%\begin{center}
-% \caption{Enter DSN for connection to PostGIS database}\label{fig:getdsn}\smallskip
-% \includegraphics[scale=0.8]{getdsn}
-%\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 touse it needs a couple more things.
-
-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);
-\end{verbatim}
-
-\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:
-
-\begin{itemize}
-\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}
- \item If you don't enter any fields, the plugin fails
- \item There is no error checking on any of the database operations
- \end{itemize}
-\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.
-
-\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.
-
-To do this, we just add the following code after line 61:
-
-\begin{verbatim}
-# show the user what happened
-QMessageBox.information(None, "Results", "Table " + str(table_name[0]) + \
-" has been created. Check your database to confirm.")
-\end{verbatim}
-
-When the table is created, the user sees this:
-
-%\begin{figure}[ht]
-%\begin{center}
-% \caption{Message Box with Plugin results}\label{fig:plugin_results}\smallskip
-% \includegraphics[scale=0.8]{plugin_results}
-%\end{center}
-%\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 \classname{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:
-
-\begin{center}
- \url{http://blog.qgis.org}
-\end{center}
\ No newline at end of file
Added: docs/trunk/english_us/user_guide/plugins_writing_in_cpp.tex
===================================================================
--- docs/trunk/english_us/user_guide/plugins_writing_in_cpp.tex (rev 0)
+++ docs/trunk/english_us/user_guide/plugins_writing_in_cpp.tex 2008-09-22 15:47:41 UTC (rev 9374)
@@ -0,0 +1,12 @@
+\subsection{Writing a QGIS Plugin in C++}
+
+% when the revision of a section has been finalized,
+% comment out the following line:
+\updatedisclaimer
+
+Writing plugins in C++.
+
+\newpage
+
+
+
Copied: docs/trunk/english_us/user_guide/plugins_writing_in_python.tex (from rev 9373, docs/trunk/english_us/user_guide/plugins_python.tex)
===================================================================
--- docs/trunk/english_us/user_guide/plugins_writing_in_python.tex (rev 0)
+++ docs/trunk/english_us/user_guide/plugins_writing_in_python.tex 2008-09-22 15:47:41 UTC (rev 9374)
@@ -0,0 +1,330 @@
+\subsection{Writing a QGIS Plugin in Python}
+
+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:
+
+\begin{itemize}
+\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 \filename{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.
+
+\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 \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 \filename{qgis} in our home directory.
+Let's create the directory for the plugin.
+
+\begin{verbatim}
+mkdir ~/qgis/share/qgis/python/plugins/new_layer
+\end{verbatim}
+
+To get started, we need to create the following files in the \filename{new\_layer} directory (we'll need some additional files in a bit):
+
+\begin{verbatim}
+__init__.py
+resources.py
+resources.qrc
+newlayer.py
+\end{verbatim}
+
+\subsubsection{Making the Plugin Recognizable}
+
+Initializing the plugin is done in the \filename{\_\_init\_\_.py} script.
+For our \filename{NewLayer} plugin the script contains:
+
+\begin{verbatim}
+1 # load NewLayer class from file newlayer.py
+2 from newlayer import NewLayer
+3 def name():
+4 return "New PostGIS layer"
+5 def description():
+6 return "Creates a new empty Postgis layer"
+7 def version():
+8 return "Version 0.1"
+9 def classFactory(iface):
+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 \method{classFactory} method that must return a reference to the plugin itself (line 10), after receiving the \object{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 \filename{resources.qrc}.
+This is just a simple XML file that defines the icon resource:
+
+\begin{verbatim}
+ <RCC>
+ <qresource prefix="/plugins/newlayer">
+ <file>icon.png</file>
+ </qresource>
+</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 \filename{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:
+
+\begin{verbatim}
+ pyrcc4 -o resources.py resources.qrc
+\end{verbatim}
+
+The \filename{-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.
+
+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 \classname{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.
+
+\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 \filename{newlayer.py}.
+
+\begin{verbatim}
+1 # Import the PyQt and QGIS libraries
+2 from PyQt4.QtCore import *
+3 from PyQt4.QtGui import *
+4 from qgis.core import *
+5 import psycopg
+6 # Initialize Qt resources from file resources.py
+7 import resources
+8
+9 # Our main class for the plugin
+10 class NewLayer:
+11
+12 def __init__(self, iface):
+13 # Save reference to the QGIS interface
+14 self.iface = iface
+15
+16 def initGui(self):
+17 # Create action that will start plugin configuration
+18 self.action = QAction(QIcon(":/plugins/newlayer/icon.png"),\
+19 "New PosGIS Layer", self.iface.getMainWindow())
+20 QObject.connect(self.action, SIGNAL("activated()"), self.run)
+21
+22 # Add toolbar button and menu item
+23 self.iface.addToolBarIcon(self.action)
+24 self.iface.addPluginMenu("&New PostGIS Layer...", self.action)
+25
+26 def unload(self):
+27 # Remove the plugin menu item and icon
+28 self.iface.removePluginMenu("&New PostGIS Layer...",self.action)
+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 \filename{resources.py} file we created with the icon definition.
+
+In line 10 we declare the class \classname{NewLayer}.
+In the \method{\_\_init\_\_} method (lines 12 through 14) our class is initialized and passed the \object{iface} object from QGIS via the \method{classFactory} method in line 10 of \filename{\_\_init\_\_.py}.
+We store \object{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 \classname{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 \filename{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 \object{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 \mainmenuopt{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 \method{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.
+It's all contained in the \method{run} method.
+
+\begin{verbatim}
+30 def run(self):
+31 # Get the user input, starting with the table name
+32 table_name = QInputDialog.getText(None, "Table Name?", \
+33 "Name for new PostGIS layer")
+34 if table_name[0].length() > 0:
+35 # Get the field names and types
+36 fields = QInputDialog.getText(None, "Field Names", \
+37 "Fields (separate with a comma)")
+38 parts = fields[0].split(',')
+39 # Create the SQL statement
+40 sql = "create table " + table_name[0] + " (id int4 primary key, "
+41 for fld in parts:
+42 sql += fld + " varchar(10), "
+43 sql = sql[0:-2]
+44 sql += ")"
+45 # Connect to the database
+46 # First get the DSN
+47 dsn = QInputDialog.getText(None, "Database DSN", \
+48 "Enter the DSN for connecting to the database (dbname=db user=user)")
+49 if dsn[0].length() > 0:
+50 con = psycopg.connect(str(dsn[0]))
+51 curs = con.cursor()
+52 curs.execute(str(sql))
+53 con.commit()
+54 # add the geometry column
+55 curs.execute("select AddGeometryColumn('" + str(table_name[0]) + \
+56 "', 'the_geom', 4326, 'POLYGON', 2)")
+57 con.commit()
+58 # create the GIST index
+59 curs.execute("create index sidx_" + str(table_name[0]) + " on " + \
+60 str(table_name[0]) + " USING GIST(the_geom GIST_GEOMETRY_OPS)")
+61 con.commit()
+\end{verbatim}
+
+The first thing we need to do is use the \classname{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}
+% \caption{Enter new PostGIS table name}\label{fig:gettablename}\smallskip
+% \includegraphics[scale=0.8]{gettablename}
+%\end{center}
+%\end{figure}
+
+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.
+
+%\begin{figure}[ht]
+%\begin{center}
+% \caption{Enter field names for new PostGIS table}\label{fig:getfieldname}\smallskip
+% \includegraphics[scale=0.8]{getfieldname}
+%\end{center}
+%\end{figure}
+
+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).
+
+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:
+
+\begin{center}
+ \textsl{dbname=gis\_data user=gsherman}
+\end{center}
+
+To get the DSN, we prompt the user with a \classname{QInputDialog} in line 47.
+
+%\begin{figure}[ht]
+%\begin{center}
+% \caption{Enter DSN for connection to PostGIS database}\label{fig:getdsn}\smallskip
+% \includegraphics[scale=0.8]{getdsn}
+%\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 touse it needs a couple more things.
+
+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);
+\end{verbatim}
+
+\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:
+
+\begin{itemize}
+\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}
+ \item If you don't enter any fields, the plugin fails
+ \item There is no error checking on any of the database operations
+ \end{itemize}
+\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.
+
+\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.
+
+To do this, we just add the following code after line 61:
+
+\begin{verbatim}
+# show the user what happened
+QMessageBox.information(None, "Results", "Table " + str(table_name[0]) + \
+" has been created. Check your database to confirm.")
+\end{verbatim}
+
+When the table is created, the user sees this:
+
+%\begin{figure}[ht]
+%\begin{center}
+% \caption{Message Box with Plugin results}\label{fig:plugin_results}\smallskip
+% \includegraphics[scale=0.8]{plugin_results}
+%\end{center}
+%\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 \classname{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:
+
+\begin{center}
+ \url{http://blog.qgis.org}
+\end{center}
\ No newline at end of file
Property changes on: docs/trunk/english_us/user_guide/plugins_writing_in_python.tex
___________________________________________________________________
Name: svn:mergeinfo
+
Modified: docs/trunk/english_us/user_guide/user_guide.tex
===================================================================
--- docs/trunk/english_us/user_guide/user_guide.tex 2008-09-22 13:58:05 UTC (rev 9373)
+++ docs/trunk/english_us/user_guide/user_guide.tex 2008-09-22 15:47:41 UTC (rev 9374)
@@ -19,18 +19,21 @@
\include{working_with_ogc}
\include{working_with_projections}
\include{grass_integration}
-\include{mapserver_export}
\include{map_composer}
%first the general intro to plugins
%then each individual plugin can have a section
%in the plugins chapter
\include{plugins}
+\include{plugins_writing_in_cpp}
+\include{plugins_writing_in_python}
+\include{core_plugins}
\include{plugins_decorations}
\include{plugins_delimited_text}
\include{plugins_gps}
\include{plugins_graticule_creator}
\include{plugins_georeferencer}
-\include{plugins_python}
+\include{external_plugins}
+\include{plugins_mapserver_export}
%end of plugin docs
\include{creating_applications}
\include{help_and_support}
More information about the QGIS-commit
mailing list