Developing a PythonWin Sample Application
During the rest of this section, we will develop a sample application using PythonWin. This will lead us through many of the important MFC and PythonWin concepts, while also leveraging the dynamic nature of PythonWin.
MFC itself has a tutorial/sample called Scribble, which delivers a basic drawing application. We will develop a version of Scribble written in Python.
We will make use of some of the features of PythonWin to demonstrate how rapidly you can create such an application. Specifically, we will develop the Scribble framework first to run under the existing PythonWin framework, then make changes to it so it can run standalone. This is in contrast to the traditional technique of developing MFC applications, where the application object is often one of the first entities defined. A key benefit in using the PythonWin application object is that you get the full benefits of the PythonWin IDE, including error handling and reporting in the interactive window. This makes development much easier before we finally plug in our custom application object.
The general design of the Scribble application is simple. Define the document object to keep a list of strokes. A stroke is the start and end coordinates of a line. The document object also can load and store this list of strokes to a file. A view object is also defined that can render these strokes onto a Window.
The first step in the sample is to provide a placeholder for the document template, document, and view objects. Once this skeleton is working, we fill out these objects with a useful implementation.
Defining a Simple Framework
Our first step is to develop a simple framework with placeholders for the major objects.
We define three objects: a
ScribbleDocument, and a
ScribbleView. These objects derive their implementation from objects in the
pywin.mfc.docview module. The
ScribbleTemplate object remains empty in this implementation. The
ScribbleDocument object has a single method,
OnNew-Document(), which is called as a document object is initialized; the implementation defines an empty list of strokes. The view object is based on a
PyCScrollView (i.e., an MFC
CScrollView) and defines a single method
OnInitialUpdate(). As the name implies, this method is called the first time a view object is updated. This method places the view in the correct mapping mode and disables the scrollbars. For more information on mapping modes and views, see the MFC documentation.
The final part of the skeleton registers the new document template with the MFC framework. This registration process is simple, just a matter of calling
AddDocTemplate() on the application object. In addition, this code associates some doc strings with the template. These doc strings tell the MFC framework important details about the document template, such as the file extensions for the documents, the window title for new documents, etc. For information on these doc strings, see the PythonWin Reference for the function
The term doc strings has a number of meanings. To Python, a doc string is a special string in a Python source file that provides documentation at runtime for specific objects. In the context of an MFC document template, a doc string is a string that describes an MFC document object.
A final note before we look at the code. This application has no special requirement for a frame window. The standard MFC/PythonWin Frame windows are perfectly suitable for the application. Therefore, we don't define a specific Frame window for the sample.
Let's look at the example application with the described functionality:
# The starting framework for our scribble application.
"""Called whenever the document needs initializing.
For most MDI applications, this is only called as the document
self.strokes = 
self.SetScrollSizes(win32con.MM_TEXT, (0, 0))
# Now we do the work to create the document template, and
# register it with the framework.
# For debugging purposes, we first attempt to remove the old template.
# This is not necessary once our app becomes stable!
# haven't run this before - that's ok
# Now create the template object itself...
template = ScribbleTemplate(None, ScribbleDocument, None, ScribbleView)
# Set the doc strings for the template.
docs='\nPyScribble\nPython Scribble Document\nScribble documents (*.psd)\n.psd'
# Then register it with MFC.
Notice there's some code specifically for debugging. If you execute this module multiple times, you'd potentially create multiple document templates, but all for the same class of documents (i.e., the
ScribbleDocument). To this end, each time you execute this module, try to remove the document template added during the previous execution.
What does this sample code do? It has registered the
ScribbleTemplate with MFC, and MFC is now capable of creating a new document. Let's see this in action. To register the template in PythonWin, perform the following steps:
- Start PythonWin.
- Open the sample code in PythonWin using the File menu and select Open.
- From the File menu, select Import. This action executes the module in the PythonWin environment.
To test this skeleton, select New from the File menu. You will see a list of all the document templates registered in PythonWin. The list should look something like Figure 20-4.
You can now select the Python
ScribbleDocument and see what happens. You should see a new Frame window, with the title
PyScribble1. MFC has given the new document a default name based on the doc strings you supplied the template.
Because you haven't added any code for interacting with the user, your application won't actually do anything yet! We will now develop this skeleton into a usable Scribble application.