[QGIS Commit] r14106 - docs/trunk/english_us/developer_cookbook/source

[svn_qgis at osgeo.org]

Author: timlinux
Date: 2010-08-18 20:21:30 +0000 (Wed, 18 Aug 2010)
New Revision: 14106

Modified:
   docs/trunk/english_us/developer_cookbook/source/canvas.rst
Log:
Some language cleanups and wrap at 80chars

Modified: docs/trunk/english_us/developer_cookbook/source/canvas.rst
===================================================================
--- docs/trunk/english_us/developer_cookbook/source/canvas.rst	2010-08-18 10:24:34 UTC (rev 14105)
+++ docs/trunk/english_us/developer_cookbook/source/canvas.rst	2010-08-18 20:21:30 UTC (rev 14106)
@@ -4,26 +4,37 @@
 Using Map Canvas
 ================
 
-Map canvas widget is probably the most important widget within QGIS, because it shows the map composed from overlaid map layers
-and allows interaction with it. The canvas shows always a part of the map defined by the current canvas extent.
-The interaction is done through the use of **map tools**: there are tools for panning, zooming, identifying layers, measuring, vector editing and others.
-Similar to other graphics programs, there is always one tool active and the user can switch among the available tools.
+The Map canvas widget is probably the most important widget within QGIS because it
+shows the map composed from overlaid map layers and allows interaction the map and layers.
+The canvas shows always a part of the map defined by the current canvas extent.
+The interaction is done through the use of **map tools**: there are tools for
+panning, zooming, identifying layers, measuring, vector editing and others.
+Similar to other graphics programs, there is always one tool active and the
+user can switch between the available tools.
 
 
-Map canvas is implemented as :class:`QgsMapCanvas` class in :mod:`qgis.gui` module.
-The implementation is based on the `Qt Graphics View framework <http://doc.qt.nokia.com/graphicsview.html>`_
-This framework generally provides a surface and a view where custom graphics items are placed and user can interact with them.
-We will expect you are familiar with it to a degree where you understand the concepts of the graphics scene, view and items.
-If not, please read the overview of the framework.
+Map canvas is implemented as :class:`QgsMapCanvas` class in :mod:`qgis.gui`
+module.  The implementation is based on the `Qt Graphics View framework
+<http://doc.qt.nokia.com/graphicsview.html>`_ This framework generally provides
+a surface and a view where custom graphics items are placed and user can
+interact with them.  We will assume that you are familiar enough with Qt to 
+understand the concepts of the graphics scene, view and items.  If not,
+please read the overview of the framework.
 
-Always when the map has been panned, zoomed in/out (or some other action triggered the refresh), the map is rendered again within
-the current extent. The layers are rendered to an image (using :class:`QgsMapRenderer` class) and that image is then displayed in the canvas.
-The graphics item (in terms of the Qt graphics view framework) responsible for showing the map is :class:`QgsMapCanvasMap` class.
-This class also controls refreshing of the rendered map. Besides this item which acts as a background, there may be more **map canvas items**.
-Typical map canvas items are rubber bands (used for measuring, vector editing etc.) or vertex markers. The canvas items are
-usually used to give some visual feedback for map tools, for example, when creating a new polygon, the map tool creates a rubber band
-canvas item that shows the current shape of the polygon. All map canvas items are subclasses of :class:`QgsMapCanvasItem` which
-adds some more functionality to the basic ``QGraphicsItem`` objects.
+Whenever the map has been panned, zoomed in/out (or some other action
+triggers a refresh), the map is rendered again within the current extent.
+The layers are rendered to an image (using :class:`QgsMapRenderer` class) and
+that image is then displayed in the canvas.  The graphics item (in terms of the
+Qt graphics view framework) responsible for showing the map is
+:class:`QgsMapCanvasMap` class.  This class also controls refreshing of the
+rendered map. Besides this item which acts as a background, there may be more
+**map canvas items**.  Typical map canvas items are rubber bands (used for
+measuring, vector editing etc.) or vertex markers. The canvas items are usually
+used to give some visual feedback for map tools, for example, when creating a
+new polygon, the map tool creates a rubber band canvas item that shows the
+current shape of the polygon. All map canvas items are subclasses of
+:class:`QgsMapCanvasItem` which adds some more functionality to the basic
+``QGraphicsItem`` objects.
 
 To summarize, the map canvas architecture consists of three concepts:
 
@@ -35,25 +46,32 @@
 Embedding Map Canvas
 --------------------
 
-Map canvas is a widget like any other Qt widget, so using it is as simple as creating and showing it::
+Map canvas is a widget like any other Qt widget, so using it is as simple as
+creating and showing it::
 
   canvas = QgsMapCanvas()
   canvas.show()
 
-This produces a standalone window with map canvas. It can be also embedded into an existing widget or window. When using .ui files and Qt Designer,
-place a ``QWidget`` on the form and promote it to a new class: set ``QgsMapCanvas`` as class name and set ``qgis.gui`` as header file. The ``pyuic4`` utility
-will take care of it. This is a very convenient way of embedding the canvas. The other possibility is to write manually the code to construct
-map canvas and other widgets (as children of a main window or dialog) and create a layout.
+This produces a standalone window with map canvas. It can be also embedded into
+an existing widget or window. When using .ui files and Qt Designer, place a
+``QWidget`` on the form and promote it to a new class: set ``QgsMapCanvas`` as
+class name and set ``qgis.gui`` as header file. The ``pyuic4`` utility will
+take care of it. This is a very convenient way of embedding the canvas. The
+other possibility is to manually write the code to construct map canvas and
+other widgets (as children of a main window or dialog) and create a layout.
 
-By default, map canvas has black background and does not use anti-aliasing. To set white background and enable anti-aliasing for smooth rendering::
+By default, map canvas has black background and does not use anti-aliasing. To
+set white background and enable anti-aliasing for smooth rendering::
 
   canvas.setCanvasColor(Qt.white)
   canvas.enableAntiAliasing(True)
 
-(In case you are wondering, ``Qt`` comes from ``PyQt4.QtCore`` module and ``Qt.white`` is one of the predefined ``QColor`` instances.)
+(In case you are wondering, ``Qt`` comes from ``PyQt4.QtCore`` module and
+``Qt.white`` is one of the predefined ``QColor`` instances.)
 
-Now it is time to add some map layers. We will first open a layer and add it to the map layer registry.
-Then we will set the canvas extent and set the list of layers for canvas::
+Now it is time to add some map layers. We will first open a layer and add it to
+the map layer registry.  Then we will set the canvas extent and set the list of
+layers for canvas::
 
   layer = QgsVectorLayer(path, name, provider)
   if not layer.isValid():
@@ -73,12 +91,14 @@
 Using Map Tools with Canvas
 ---------------------------
 
-The following example constructs a window that contains a map canvas and basic map tools for map panning and zooming.
-Actions are created for activation of each tool: panning is done with :class:`QgsMapToolPan`, zooming in/out with
-a pair of :class:`QgsMapToolZoom` instances. The actions are set as checkable and later assigned to the tools to
-allows automatic handling of checked/unchecked state of the actions -- when a map tool gets activated, its action
-is marked as selected and the action of the previous map tool is deselected. The map tools are activated using
-:func:`setMapTool` method.
+The following example constructs a window that contains a map canvas and basic
+map tools for map panning and zooming.  Actions are created for activation of
+each tool: panning is done with :class:`QgsMapToolPan`, zooming in/out with a
+pair of :class:`QgsMapToolZoom` instances. The actions are set as checkable and
+later assigned to the tools to allows automatic handling of checked/unchecked
+state of the actions -- when a map tool gets activated, its action is marked as
+selected and the action of the previous map tool is deselected. The map tools
+are activated using :func:`setMapTool` method.
 
 ::
 
@@ -136,23 +156,29 @@
       self.canvas.setMapTool(self.toolPan)
 
 
-You can put the above code to a file, e.g. ``mywnd.py`` and try it out in Python console within QGIS.
-This code will put the currently selected layer into newly created canvas::
+You can put the above code to a file, e.g. ``mywnd.py`` and try it out in
+Python console within QGIS.  This code will put the currently selected layer
+into newly created canvas::
 
   import mywnd
   w = mywnd.MyWnd(qgis.utils.iface.activeLayer())
   w.show()
 
-Just make sure that the ``mywnd.py`` file is located within Python search path (``sys.path``). If it isn't,
-you can simply add it: ``sys.path.insert(0, '/my/path')`` --- otherwise the import statement will fail, not founding the module.
+Just make sure that the ``mywnd.py`` file is located within Python search path
+(``sys.path``). If it isn't, you can simply add it: ``sys.path.insert(0,
+'/my/path')`` --- otherwise the import statement will fail, not finding the
+module.
 
 Rubber Bands and Vertex Markers
 -------------------------------
 
-To show some additional data on top of the map in canvas, use map canvas items. It is possible to create
-custom canvas item classes (covered below), however there are two useful canvas item classes for convenience:
-:class:`QgsRubberBand` for drawing polylines or polygons, and :class:`QgsVertexMarker` for drawing points.
-They both work with map coordinates, so the shape is moved/scaled automatically when the canvas is being panned or zoomed.
+To show some additional data on top of the map in canvas, use map canvas items.
+It is possible to create custom canvas item classes (covered below), however
+there are two useful canvas item classes for convenience:
+:class:`QgsRubberBand` for drawing polylines or polygons, and
+:class:`QgsVertexMarker` for drawing points.  They both work with map
+coordinates, so the shape is moved/scaled automatically when the canvas is
+being panned or zoomed.
 
 To show a polyline::
 
@@ -166,11 +192,12 @@
   points = [ [ QgsPoint(-1,-1), QgsPoint(0,1), QgsPoint(1,-1) ] ]
   r.setToGeometry(QgsGeometry.fromPolygon(points), None)
 
-Note that points for polygon is not a plain list: in fact, it is a list of rings containing
-linear rings of the polygon: first ring is the outer border, further (optional) rings
-correspond to holes in the polygon.
+Note that points for polygon is not a plain list: in fact, it is a list of
+rings containing linear rings of the polygon: first ring is the outer border,
+further (optional) rings correspond to holes in the polygon.
 
-Rubber bands allow some customization, namely to change its color and line width::
+Rubber bands allow some customization, namely to change their color and line
+width::
 
   r.setColor(QColor(0,0,255))
   r.setWidth(3)
@@ -181,23 +208,28 @@
 
   canvas.scene().removeItem(r)
 
-(in C++ it's possible to just delete the item, however in Python ``del r`` would just delete the reference
-and the object will still exist as it is owned by the canvas)
+(in C++ it's possible to just delete the item, however in Python ``del r``
+would just delete the reference and the object will still exist as it is owned
+by the canvas)
 
-Rubber band can be also used for drawing points, however :class:`QgsVertexMarker` class is better suited for this
-(:class:`QgsRubberBand` would only draw a rectangle around the desired point). How to use the vertex marker::
+Rubber band can be also used for drawing points, however
+:class:`QgsVertexMarker` class is better suited for this
+(:class:`QgsRubberBand` would only draw a rectangle around the desired point).
+How to use the vertex marker::
 
   m = QgsVertexMarker(canvas)
   m.setCenter(QgsPoint(0,0))
 
-This will draw a red cross on position [0,0]. It is possible to customize the icon type, size, color and pen width::
+This will draw a red cross on position [0,0]. It is possible to customize the
+icon type, size, color and pen width::
 
   m.setColor(QColor(0,255,0))
   m.setIconSize(5)
   m.setIconType(QgsVertexMarker.ICON_BOX) # or ICON_CROSS, ICON_X
   m.setPenWidth(3)
 
-For temprary hiding of vertex markers and removing them from canvas, the same applies as for the rubber bands.
+For temprary hiding of vertex markers and removing them from canvas, the same
+applies as for the rubber bands.
 
 Writing Custom Map Tools
 ------------------------