Motivation
----------
Example Tool should help new GRASS GUI programmers who are interested in
adding or improving GRASS GIS functionality or writing GRASS GIS GUI-based
application for their own purposes.

How to use Example Tool
-----------------------
Example Tool is a simple template for applications which are
supposed to display maps and make computations using GRASS modules.
It covers several often occurring tasks. It can be helpful for all
new developers who are interested in wxGUI programming.
Run Example Tool, have a look at wxGUI.Example.html and than
look at the source code to see how it works.

Run Example Tool
----------------
To run Example Tool can run as a standalone application (in GRASS environment)
or it can be launched from the console.

1. Go to GRASS root directory

2. Copy directory ./doc/gui/wxpython/example to ./gui/wxpython/example

3. Now you should be able to run Example Tool as a standalone 
application in GRASS environment. Start GRASS GIS and start application:

    > python ./gui/wxpython/example/frame.py

If you want to add Example Tool in the compilation.

4. Move file ./gui/wxpython/example/wxGUI.Example.html to ./gui/wxpython/docs/

5. Edit ./gui/wxpython/Makefile:

 SRCFILES := $(wildcard icons/*.* scripts/* xml/*) \
-	$(wildcard core/* dbmgr/* gcp/* gmodeler/* ... \
+	$(wildcard core/* dbmgr/* example/* gcp/* gmodeler/* ... \
 
-PYDSTDIRS := $(patsubst %,$(ETCDIR)/%,core dbmgr gcp gmodeler ... \
+PYDSTDIRS := $(patsubst %,$(ETCDIR)/%,core dbmgr example gcp gmodeler ... \

6. Run make (in ./gui/wxpython)
    
If you want to access Example Tool from Layer Manager menu, there are
a few more things to be done.

7. Edit ./gui/wxpython/xml/menudata.xml. Add following code to appropriate place:

    <menuitem>
      <label>Example</label>
      <help>Example help (for statusbar)</help>
      <keywords>raster</keywords>
      <handler>OnExample</handler>
    </menuitem>
    
8. Add folowing event handler to class GMFrame in ./gui/wxpython/lmgr/frame.py:

    def OnExample(self, event):
        """!Launch ExampleTool"""
        win = ExampleMapFrame(parent = self)
        win.CentreOnScreen()
        
        win.Show()
        
and don't forget to insert following line at the beginning of the file:

    from example.frame import ExampleMapFrame

9. Run make again.


Note
----
Feel free to improve Example Tool or suggest possible improvements.
