[QGIS Commit] r9904 - docs/trunk/english_us/user_guide
svn_qgis at osgeo.org
svn_qgis at osgeo.org
Sun Dec 28 05:59:17 EST 2008
Author: dassau
Date: 2008-12-28 05:59:17 -0500 (Sun, 28 Dec 2008)
New Revision: 9904
Modified:
docs/trunk/english_us/user_guide/core_plugins.tex
docs/trunk/english_us/user_guide/external_plugins.tex
docs/trunk/english_us/user_guide/features_at_a_glance.tex
docs/trunk/english_us/user_guide/plugins.tex
docs/trunk/english_us/user_guide/plugins_writing_in_python.tex
Log:
applied patch from Borys
reviewed plugins.tex and core_plugins.tex
Modified: docs/trunk/english_us/user_guide/core_plugins.tex
===================================================================
--- docs/trunk/english_us/user_guide/core_plugins.tex 2008-12-28 03:40:47 UTC (rev 9903)
+++ docs/trunk/english_us/user_guide/core_plugins.tex 2008-12-28 10:59:17 UTC (rev 9904)
@@ -4,7 +4,7 @@
% when the revision of a section has been finalized,
% comment out the following line:
-\updatedisclaimer
+%\updatedisclaimer
QGIS currently contains 16 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
Modified: docs/trunk/english_us/user_guide/external_plugins.tex
===================================================================
--- docs/trunk/english_us/user_guide/external_plugins.tex 2008-12-28 03:40:47 UTC (rev 9903)
+++ docs/trunk/english_us/user_guide/external_plugins.tex 2008-12-28 10:59:17 UTC (rev 9904)
@@ -7,9 +7,10 @@
\updatedisclaimer
External QGIS plugins are all written in python. They are stored in
-an official, moderated svn repository and maintained by the individual
+an official, moderated repository and maintained by the individual
author. Table \ref{tab:external_plugins} shows a list of plugins
currently available. All these plugins are descibed in this manual.
+Also updates of core plugins may be available in this repository as external overlays.
\begin{table}[H]
\centering
@@ -34,13 +35,19 @@
A detailed install description for external python plugins can be found in
Section \ref{sec:load_external_plugin}.
-\minisec{Unofficial Python Plugin repository}
+\minisec{User-Contributed Python Plugin Repository and author repositories}
-Apart from the moderated external plugins there exist another unofficial
-Python Plugin repository. It contains of plugins that are not yet stable
-enough...
+Apart from the moderated external plugins there exists another unofficial
+Python Plugin repository. It contains plugins that are not yet mature
+enough to include them to the Official repository, however some of them
+can be quite useful. Furthermore a few of our contributors maintain
+their own repositories.
-ADD MORE INFO HERE
+To add the unofficial repository and the author repositories open the
+Plugin Installer (\mainmenuopt{Plugins} > \dropmenuopttwo{plugin_installer}{Fetch Python Plugins...}),
+go to the \tab{Repositories} tab and click the \button{Add 3rd party repositories}
+button. If you don't want one or more of the added repositories, disable it with the
+\button{Edit...} button or completely remove with the \button{Delete} button.
\begin{Tip} \caption{\textsc{Add more external Plugins}}
\qgistip{Apart from the official QGIS plugin repository you can add
Modified: docs/trunk/english_us/user_guide/features_at_a_glance.tex
===================================================================
--- docs/trunk/english_us/user_guide/features_at_a_glance.tex 2008-12-28 03:40:47 UTC (rev 9903)
+++ docs/trunk/english_us/user_guide/features_at_a_glance.tex 2008-12-28 10:59:17 UTC (rev 9904)
@@ -566,7 +566,7 @@
zoom in and out. A progress bar in the status bar shows progress of rendering
as each layer is drawn to the map view. In some cases, such as the gathering
of statistics in raster layers, the progress bar will be used to show the
-status of lengthy operations. Also, if external python plugins are available,
+status of lengthy operations. Also, if a new plugin or a plugin update is available,
you will see a message in the status bar. On the right side of the status bar is a small
checkbox which can be used to temporarily prevent layers being rendered to the
map view (see Section \ref{subsec:redraw_events} below). At the far right of
Modified: docs/trunk/english_us/user_guide/plugins.tex
===================================================================
--- docs/trunk/english_us/user_guide/plugins.tex 2008-12-28 03:40:47 UTC (rev 9903)
+++ docs/trunk/english_us/user_guide/plugins.tex 2008-12-28 10:59:17 UTC (rev 9904)
@@ -4,7 +4,7 @@
% when the revision of a section has been finalized,
% comment out the following line:
-\updatedisclaimer
+%\updatedisclaimer
QGIS has been designed with a plugin architecture.
This allows new features/functions to be easily added to the application.
@@ -12,26 +12,28 @@
\begin{itemize}
\item \textbf{Core Plugins} are maintained by the QGIS Development Team and are automatically part of every QGIS distribution.
+They are written in one of two languages: C++ or Python.
More information about core plugins are provided in Section \ref{sec:core_plugins}.
\item \textbf{External Plugins} are currently all written in Python.
-They are stored in external svn repositories and maintained by the individual author.
-They can be added to QGIS using the core plugin called \filename{Fetch Python Plugins...}.
+They are stored in external repositories and maintained by the individual author.
+They can be added to QGIS using the core plugin called \filename{Plugin Installer}.
More information about external plugins are provided in Section \ref{sec:external_plugins}.
\end{itemize}
\subsection{Managing Plugins}\label{sec:managing_plugins}
\index{plugins!managing}
-Managing plugins in general means loading or unloading them using the \filename{Plugin Manager} and the \filename{Plugin installer} plugin.
+Managing plugins in general means loading or unloading them using the \filename{Plugin Manager} plugin.
+External plugins need to be first installed using the \filename{Plugin Installer} plugin.
\subsubsection{Loading a QGIS Core Plugin}\label{sec:load_core_plugin}
-Loading a QGIS Core Plugin is provided in the main menu \mainmenuopt{Plugins} > \dropmenuopttwo{plugin_installer}{Manage Plugins...}.\index{plugins!manager}
+Loading a QGIS Core Plugin is provided in the main menu \mainmenuopt{Plugins} > \dropmenuopttwo{mActionShowPluginManager}{Manage Plugins...}.\index{plugins!manager}
\begin{figure}[ht]
\begin{center}
\caption{Plugin Manager \nixcaption}\label{fig:pluginmanager}\smallskip
- \includegraphics[clip=true, width=9cm]{pluginmanager}
+ \includegraphics[clip=true, width=14cm]{pluginmanager}
\end{center}
\end{figure}
@@ -40,10 +42,6 @@
Figure \ref{fig:pluginmanager} shows the Plugin Manager dialog.
Loaded plugins are "remembered" when you exit the application and restored the next time you run QGIS.
-Typically all QGIS core plugins are installed in the same location on your computer.
-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).
@@ -60,19 +58,48 @@
Then you can load external QGIS python plugin in two steps:
\begin{enumerate}
-\item Download an external plugin from a repository using the \filename{Plugin Installer}.
+\item Download an external plugin from a repository using the \filename{Plugin Installer} (Section \ref{sec:python_plugin_installer}).
The new external plugin will be integrated into the list of available plugins in the \filename{Plugin Manager}.
\item Load the plugin using the \filename{Plugin Manager}.
\end{enumerate}
+\subsubsection{Using the QGIS Python Plugin Installer}\index{plugins!installing}\label{sec:python_plugin_installer}
+\index{plugins!Python Plugin Installer}\index{plugins!upgrading}
+
\begin{figure}[ht]
\begin{center}
\caption{Installing external python plugins \nixcaption}
\label{fig:plugininstaller}\smallskip
- \includegraphics[clip=true, width=9cm]{plugininstaller}
+ \includegraphics[clip=true, width=14cm]{plugininstaller}
\end{center}
\end{figure}
+In order to download and install an external Python plugin, click the menu \mainmenuopt{Plugins} > \dropmenuopttwo{plugin_installer}{Fetch Python Plugins...}.
+The \filename{Plugin Installer} window will appear (figure \ref{fig:plugininstaller}) with the tab \tab{Plugins}, containing the list of all Python plugins available in remote repositories as well as installed ones. Each plugin can be either:
+\begin{itemize}
+\item \textbf{not installed} - it means the plugin is available in the repository, but is not installed yet. In order to install, select it from the list and click the \button{Install plugin} button.
+\item \textbf{new} - the same as before but the plugin is seen for the first time.
+\item \textbf{installed} - the plugin is installed. If it's also available in any repository the \button{Reinstall plugin} button is enabled. But if the available version is older than the installed one, the \button{Downgrade plugin} button appears instead.
+\item \textbf{upgradeable} - the plugin is installed, but there is an updated version available. The \button{Upgrade plugin} button is enabled.
+\item \textbf{invalid} - the plugin is installed, but is unworkable. The reason is explained in the plugin description.
+\end{itemize}
+
+\minisec{Plugins tab}
+
+To install a plugin, select it from the list and click the \button{Install plugin} button. The plugin is installed in its own directory, e.g. for \nix under \filename{\$HOME/.qgis/python/plugins} and is only visible for the user who has installed it. See a list of other OS specific subdirectory used for plugins in Section~\ref{subsec:pyfoursteps}. If the installation is successful, a confirmation message will appear. Then you need go to the \mainmenuopt{Plugins} > \dropmenuopttwo{mActionShowPluginManager}{Manage Plugins...} and load the installed plugin.
+
+If the installation fails, the reason is displayed. The most often troubles are related to connection errors and missing Python modules. In the former case you'll probably need to wait some minutes or hours, in the latter one you need to install the missing modules in your operating system prior to using the plugin. \nix{For Linux, most required modules should be available in a package manager}. \win{For install instructions in Windows visit the module home page}. If you use a proxy, you may need to configure it under the menu \mainmenuopt{Settings} > \dropmenuopttwo{mActionOptions}{Options} on the \tab{Proxy} tab.
+
+The \button{Uninstall plugin} button is enabled only if the selected plugin is installed and it's not a core plugin. Note that if you have installed an update of a core plugin, you can still uninstall this update with the \button{Uninstall plugin} and revert to the version shipped within Quantum GIS install package. This one cannot be uninstalled.
+
+\minisec{Repositories tab}
+
+The second tab \tab{Repositories} contains a list of plugin repositories available for the Plugin Installer. By default, only the QGIS Official Repository is used. You can add some user-contributed repositories, including the central QGIS Contributed Repository and a few author repositories by clicking the \button{Add 3rd party repositories} button. Those repositories contain a huge number of more or less useful plugins but please note that they aren't maintained by the QGIS Development Team and we can't take any responsibility for them. You can also manage the repository list manually, that is add, remove and edit the entries. Temporary disabling a particular repository is possible clicking the \button{Edit...} button.
+
+The \checkbox{Check for updates on startup} checkbox makes QGIS looking for plugin updates and news. If it's enabled, all repositories listed and enabled on the \tab{Repositories} tab are checked whenever the program is starting. If a new plugin or an update for one of installed plugins is available, a clickable notification appears in the Status Bar. If the checkbox is disabled, looking for updates and news is performed only when Plugin Installer is being launched from the menu.
+
+In case of some internet connection problems a \textit{Looking for new plugins...} indicator in the Status Bar may stay visible during whole QGIS session and cause a program crash when exiting. In this case please disable the checkbox.
+
\subsection{Data Providers}\index{data providers}
Data Providers are "special" plugins that provides access to a data store.
@@ -80,4 +107,4 @@
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.
+They are not managed by the Plugin Manager but used behind the scenes when a data type is added as a layer in QGIS.
Modified: docs/trunk/english_us/user_guide/plugins_writing_in_python.tex
===================================================================
--- docs/trunk/english_us/user_guide/plugins_writing_in_python.tex 2008-12-28 03:40:47 UTC (rev 9903)
+++ docs/trunk/english_us/user_guide/plugins_writing_in_python.tex 2008-12-28 10:59:17 UTC (rev 9904)
@@ -49,7 +49,7 @@
Windows, the PyQt installer already contains Qt, PyQt and the PyQt
development tools.
-\subsection{Programming a simple PyQGIS Plugin in four steps}
+\subsection{Programming a simple PyQGIS Plugin in four steps}\label{subsec:pyfoursteps}
The example plugin is intentionally kept simple. It adds a button to the menu
bar of QGIS. If the button is clicked, a file dialog appears where the user
@@ -57,10 +57,8 @@
For each python plugin, a dedicated folder that contains the plugin files
needs to be created. By default, QGIS looks for plugins in
-\$QGIS\_DIR/share/qgis/python/plugins (in our workshop
-/usr/share/qgis/python/plugins). On Linux, there is also the possibility to
-have plugins in \$HOME/.qgis/python/plugins such that it is only visible for
-one user.
+two locations: \$QGIS\_DIR/share/qgis/python/plugins and \$HOME/.qgis/python/plugins.
+Note that plugins installed in the latter location are only visible for one user.
\minisec{Step 1: Make the plugin manager recognise the plugin}
@@ -68,25 +66,31 @@
will scan each OS specific subdirectory and initialize any plugins it finds.
\begin{itemize}
-\item \nix{Linux and other unices}: ./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
+\item \nix{Linux and other unices}:\\
+./share/qgis/python/plugins \\
+/home/\$USERNAME/.qgis/python/plugins
+\item \osx{Mac OS X}:\\
+./Contents/MacOS/share/qgis/python/plugins \\
+/Users/\$USERNAME/.qgis/python/plugins
+\item \win{Windows}:\\
+C:\textbackslash Program Files\textbackslash QGIS\textbackslash python\textbackslash plugins \\
+C:\textbackslash Documents and Settings\textbackslash\$USERNAME\textbackslash .qgis\textbackslash python\textbackslash plugins
+
\end{itemize}
Once that's done, the plugin will show up in the
\dropmenuopttwo{mActionShowPluginManager}{Plugin Manager...}
-\begin{Tip}\caption{\textsc{QGIS Python Plugin folder in \$HOME/.qgis}}
-\qgistip{For Linux and other unices, there is also the possibility to have
-your python plugins in \$HOME/.qgis/python/plugins. In that case, they are
-only visible for one user.
+\begin{Tip}\caption{\textsc{Two QGIS Python Plugin folders}}
+\qgistip{There are two directories containing the python plugins. \$QGIS\_DIR/share/qgis/python/plugins
+is designed mainly for the core plugins while \$HOME/.qgis/python/plugins for easy installation of the external plugins. Plugins in the home location are only visible for one user but also mask the core plugins with the same name, what can be used to provide main plugin updates
}
\end{Tip}
To provide the neccessary information for QGIS, the plugin needs to implement
-the methods \method{name()}, \method{description()} and \method{version()}
-which return descriptive strings. A plugin also needs a method
+the methods \method{name()}, \method{description()}, \method{version()},
+\method{qgisMinimumVersion()} and \method{authorName()} which return descriptive strings.
+The \method{qgisMinimumVersion()} should return a simple form, for example ``1.0``. A plugin also needs a method
\method{classFactory(QgisInterface)} which is called by the plugin manager to create
an instance of the plugin. The argument of type QGisInterface is used by the
plugin to access functions of the QGIS instance. We are going to work with
@@ -96,7 +100,7 @@
important. The Python interpreter throws an error if it is not correct.
For our plugin we create the plugin folder 'foss4g\_plugin' in
-\filename{./qgis/python/plugins}. Then we add two new textfiles into this
+\filename{\$HOME/.qgis/python/plugins}. Then we add two new textfiles into this
folder, \filename{foss4gplugin.py} and \filename{\_\_init\_\_.py}.
The file \filename{foss4gplugin.py} contains the plugin class:
@@ -124,7 +128,8 @@
\end{verbatim}
The file \filename{\_\_init\_\_.py} contains the methods \method{name()},
-\method{description()} and \method{version()} and \method{classFactory}. As
+\method{description()}, \method{version()}, \method{qgisMinimumVersion()}
+and \method{authorName()} and \method{classFactory}. As
we are creating a new instance of the plugin class, we need to import the
code of this class:
@@ -136,7 +141,11 @@
def description():
return "A simple example plugin to load shapefiles"
def version():
- return "Version 0.1"
+ return "0.1"
+def qgisMinimumVersion():
+ return "1.0"
+def authorName():
+ return "John Developer"
def classFactory(iface):
return FOSS4GPlugin(iface)
\end{verbatim}
@@ -157,7 +166,7 @@
this little workshop can be downloaded from
\url{http://karlinapp.ethz.ch/python\_foss4g}. Move these 2 files into the
directory of the example plugin
-\filename{./qgis/python/plugins/foss4g\_plugin} and enter: <path\_to\_QGIS\_folder>/pyrcc4 -o
+\filename{\$HOME/.qgis/python/plugins/foss4g\_plugin} and enter there: pyrcc4 -o
resources.py resources.qrc.
\minisec{Step 3: Add a button and a menu}
@@ -209,6 +218,24 @@
vlayer = self.iface.addVectorLayer(fileName, "myLayer", "ogr")
\end{verbatim}
+
+\subsection{Committing the plugin to repository}
+
+If you have written a plugin you consider to be useful and you want to share with
+other users you're welcome to upload it to the QGIS User-Contributed Repository.
+\begin{itemize}
+\item Prepare a plugin directory containing only necessary files (ensure that there
+is no compiled .pyc files, Subversion .svn directories etc).
+\item Make a zip archive of it, including the directory. Be sure the zip file
+name is exactly the same as the directory inside (except the .zip extension of course).
+In other case the Plugin Installer won't be able to relate the available plugin with its
+locally installed instance.
+\item Upload it to the repository: \url{http://pyqgis.org/admin/contributed} (you
+will need to register at first time). Please pay attention when filling the form.
+Especially the Version Number field is often filled wrongly what confuses the Plugin
+Installer and causes false notifications of available updates.
+\end{itemize}
+
\subsection{Further information}
As you can see, you need information from different sources to write PyQGIS
More information about the QGIS-commit
mailing list