CSE 303: Autumn 2006, Assignment 7

Due: Wednesday 6 December 2006, 2:00pm

Updates

Monday, December 4: It was pointed out today that this assignment does not specify whether or not Polygons should be saved in "world coordinates" or "polygon coordinates." You may assume either.

Monday, December 4: The link to the to optional survey at the end of the assignment was incorrect, and has now been fixed.

Wednesday, November 29: We've figured out how you can do this assignment while working on the lab windows machines. The details appear at the bottom of the "Getting Started" section.

Assignment Overview

In this assignment, you will finish building a graphical polygon editor. You will begin by understanding the various classes in the skeleton system we provide you, and then you will design and implement two new classes to complete the system. Completing this assignment will require you to become familiar with some concepts in user interface programming, but it will not require you to understand any particular toolkit. You must do this assignment with the same partner you had for HW6.

Getting Started

Either you or your partner should begin this assignment by downloading hw7.tgz, unpacking it with tar -xvzf hw7.tgz, and copying the files to a polyedit working directory. This package contains six files which you will need to do this assignment (Makefile, Main.cpp, Graphics.h, Graphics.cpp, Controller.h, and Controller.cpp). When the files in hw7.tgz are placed in the same directory with the files Point.h, Point.cpp, Polygon.h, and Polygon.cpp from HW6, you should be able to compile and run a skeleton version of the system that opens a black window but does little else. Once you get this working, commit this skeleton version to your subversion repository.

Note the following:

• If you don't trust your own Point and Polygon classes, you are free to use the versions that appear in the HW6 solutions.
• If you wish to keep the test code you created for HW6 in your project, you may need to merge the new Makefile we provide with the the Makefile you created in HW6.
• To run this program, you must have a working connection to an X server. We recommend you do this in one of the follwing two ways:
  • Do your work on one of the Linux machines in the lab.
  • Do your work on one of the windows machines in the lab by logging on to attu in the standard way, which runs the ReflectionX server. For this to work, you will need to modify the configuration of the Reflection X server. Locate the ReflectionX icon in the task tray. (This is the the small blue pyramid with the "X" on it in the lower, right corner of the screen). Right click on this icon and select "Settings" in the menu. In the "Server" category, you will find a button that says "GLX Advanced." Click on this button, check the two check boxes in the dialog box that appears, and click "OK". This will allow you to do work on a windows machine, with the following caveats:
    • You may need to reset ReflectionX in order for this to work.
    • You may find that parts of your window won't draw until you resize the window.
    • You may have to repeat the above procedure every time you log in.

Polyedit

The skeleton program we provide you explains how it should operate. The program takes one or two arguments, an optional input file name followed by a mandatory output file name. When the program starts normally, the following text is printed to the terminal:

     --------- polyedit: A polygon editor ----------
     
     Usage: polyedit [InFile] OutFile
     
     Polyedit allows you to view and create polygons.
     If "InFile" is specified, a polygon is read from
     that file. If the program exits as defined below,
     the current polygon is written to "OutFile"
     
     The following commands are available while Polyedit is running:
     
     Mouse Commands
        Left Button Click: Add a point to the current polygon
        Right Button Drag: Move the polygon around the screen
     Keyboard Commands
        'c'  : Clears the current polygon
        'Esc': Exits the program and writes the polygon to OutFile
     
     ------------------------------------------------

Your goal is to make polyedit behave as defined above. You will do this by creating two new classes, MyController and MovablePolygon, as described below. You will not be allowed to make edits to the other files, except for minor changes to Main.cpp and the Polygon class, as described below.

Note that the file format is nothing special. It is simply the format input and output by operator<< and operator>> for Polygons which appeared in HW6. If you'd like to test out a working version of this program, you may download the following files to a Linux machine and try them out.

• polyedit: a working version of the program
• cse-building.poly, lilies.poly, mona-face.poly, penguin.poly: polygon files for recognizable objects.

Understanding the Code

Your next step should be seeking to understand the code we have provided you. You'll discover most of what you need to know by looking at the main function in Main.cpp and the header files for the two new classes Controller and Graphics.

• Graphics: This class handles all the details of parsing the command line, printing messages to the terminal, opening files for reading/writing, opening a user interface (UI) window, and receiving messages from the UI toolkit. However, this class does not actually handle UI messages, nor does it handle the streaming of data into or out of a polygon. Instead, it defers all of this work to a Controller class, described below. Graphics is a large and complicated class, but the public interface to this class, documented in Graphics.h, is rather simple. In fact, you can do the entire assignment if you understand nothing more than the DrawLine method, as we'll see below.
• Controller: This is the class that actually handles the various "Commands" issued by the user and the UI toolkit. If you look in Controller.cpp, you'll notice that Controller doesn't actually do anything. You will implement a new subclass of Controller called MyController that contains a polygon and overrides the methods in Controller, causing polyedit to have the behavior defined above. Controller.h gives specifications for six methods that respond to commands, plus a destructor. The following is a summary of the methods:
  • ~Controller: You may or may not need to override the destructor and/or provide new constructors, depending on how you design your controller.
  • ClearCmd, AddPointCmd: You will need to override these two methods for manipulating the polygon data.
  • DragCmd: Overriding this method allows you drag the polygon around in the window. This introduces significant complications, as explained in the next section.
  • RenderCmd: This command is called by Graphics every time the the UI system needs to draw the window. You must override this method and draw the current polygon. You will do this by calling the DrawLine method on the Graphics object supplied as an argument to this method.
  • ReadCmd, WriteCmd: You must override these methods in order for receive polygon data from a file or write it to a file.
• main: This function in Main.cpp handles Initializing the Graphics class, passing it a Controller, and starting the main event loop. You shouldn't need to modify this file except to make it instantiate your new MyController class, instead of a Controller class.

World Coordinates and Polygon Coordinates

As mentioned above, the ability to drag a polygon around the screen introduces a significant complication to our system. If polygons never moved, then receiving points from AddPointCmd and drawing them with DrawLine would be a simple matter. Because polygons can move, your program must be aware of two different coordinate systems, "world coordinates" and "polygon coordinates."

• World Coordinates: The Graphics object works in this coordinate system. These coordinates correspond to the location of pixels in the window. The origin (i.e., the point (0,0)) is at the top, left corner of the window. X coordinates increase to the right, and Y coordinates increase down.
• Polygon Coordinates: The Polygon class works in this coordinate system. When a polygon moves, the origin for this polygon will no longer be at the top, left corner of the screen.

In order to handle these two different coordinate systems, you must create a new subclass of Polygon called MovablePolygon. This class will separate these two coordinate systems, and your controller will use this class instead of Polygon. You will need to modify Polygon slightly in order to make your subclass, but you are only allowed to declare/define one new method. Also, you are not allowed to change the name, arguments, or return values of any existing Polygon method. Apart from these constraints, you may design and implement MovablePolygon in any way that you wish.

Note: This method of separating out different coordinate systems is a simplified version of the way most graphical user interfaces work.

Advice

Take some time to think about how MyController and MovablePolygon should work with each other and work with your partner to design an interface for MovablePolygon. It may be best for each person to implement one class. In that case, it may be possible for each person to work somewhat independently of the other. MyController can use Polygon until MovablePolygon is ready, and everything except DragCmd should work. A unit test for MovablePolygon can suffice until the pieces are put together.

If you don't know where to begin with MovablePolygon, consider keeping a separate origin in the class. The DragCmd can update this origin and other methods can translate between the two coordinate systems.

To give you a sense of how complicated each class needs to be, here's a rundown of the sample solution:

• MyController.h: 27 lines, including 7 lines of white space
• MyController.cpp: 49 lines, including 10 lines of white space
• MovablePolygon.h: 55 lines, including 9 lines of white space and and 32 lines of comments
• MovablePolygon.cpp: 27 lines, including 6 lines of white space

Survey

Both team members should consider filling out this optional survey once the rest of the assignment is turned in. The survey gives you an opportunity to express your feelings about how work was shared on HW6 and HW7. It also gives you an opportunity to let us know when you can come to an exam review session.

Assessment

Your solutions should be

• Correct C++programs that build and run using "make" on attu.cs.washington.edu and work as specified
• In good style, including indentation and line breaks
• Of reasonable size

Turn-in instructions

Use the standard turn-in instructions described here. You should turn in all files required to build and run polyedit, plus a readme.txt file if you have anything to report.