Decision 2012 Interactive Election Map

HW 1 - 1st Technology Tutorial - GUIs & .dbf Files


Overview

This semester you will be creating an application/applet that can load Shapefile maps and .dbf files and then render the maps, coloring specific map regions according to data found in database files (historical election data) as well as selections made by the user regarding the 2012 election (what if so and so wins Ohio). Such an application will require a fairly sophisticated Graphical User Interface (GUI) and so this will be a semester-long project, culimating in HW 6, where you will complete your application. We have a long way to go before we get there. Before we code our solution, we first will have to learn all about the necessary technologies to use. This is a common first step in Software Engineering, so get used to it. We will then design our solution, and then code. The HWs will be divided up as follows:


Introduction to Swing

Again, the point of this assignment is to learn about the technology that you will use in the development of your applicatoin. It is imperative that you learn to design your system before implementing it, but it makes no sense to try and design a system using technology that you don't understand. So, your first task is to gain a mastery of the tools and techniques for building GUIs and then rendering and manipulating our maps using Java's Swing library.

Note, I will be giving you a lot of code in this assignment for you to learn from. When you hand in the assignment, you should know what every single line of code does and why I've used it. Think of this as a crash course in GUI programming, it is your obligation to go through every line and figure out precisely what is happening. By completing this assignment, you should know:

Swing is an extensive library with all sorts of ready-made controls for you to use. In order to build an interesting application you will typically make use of many, many different classes and interfaces. There are GUI Controls (like JButtons), Layout Managers (like BorderLayout), Event Handlers (like ActionListener), and many other classes for customizing the look and feel of your GUI, like Border, FileFilter, etc. Below is a sampling of the classes available to us, some of which we'll use here in HW 1 with links to the API documentation for each one. Note that you will have to import these classes when you use them. Certainly eclipse can help you with that.


GUI Controls

In this assignment, we will make use of many different Swing components. Java's Swing library has many capable, easy to use components for our application and the Using Swing Components tutorial explains how to use them. Some of the following may be useful to us, others we may see later on:

You may use other components as well in your project. Note that the more complicated components all have companion model classes. Basically, the model class stores all the data that the component displays. In order to update what is being displayed programmically, one must update the data in the model. When the data in the model is changed, the corresponding component view will automatically be updated. So, if one wants to add an entry to a JComboBox, one would get the component's model and then call methods on it to change the data, which in turn will force an updating of the view. You'll see how in the code I give you.


Layout Managers

Complex desktop applications can have hundreds of controls. This can be very complex to manage and much care must be taken to layout the components inside the GUI such that they are easy to find and use. Java provides a number of built-in layout managers to place components in various ways. The Laying Out Components Within a Container tutorial describes how to do so. In our assignments, we may make use of the following layout managers, though you may choose to use additional ones:


Event Handlers

The user will interact with our application in a number of ways, so we will have to be prepared to handle various types of events. The Writing Event Listeners tutorial explains how to do event handling in Swing. Remember, users interact with different types of components in different ways, so we will have to define many types of event handlers, like:


eclipse

This semester all project development should be done using the eclipse IDE. It's an easy to use, freely available tool that does all the things we need our IDE to do. Note that if you have never used a debugger before, then you need to start now. Debuggers are easy to learn to use, and are an essential tool for any developer. Not using a debugger is essentially a decision to make your own life difficult, so invest a little time in getting to know how it works. Note that online tutorials will be made available through the course Web site to help get you acquainted with the ins and outs of our development tools.


Packages

We will organize all source code this semester using Java packages. This is the professional developer way of doing things. Basically packages will serve as named directories and subdirectories where we can group similar types of source files such that we may more easily find and edit work.


Project Importing

Download ElectionMapViewer.zip and DBFFileEditor.zip. Save them both to a directory where you'll be able to easily find them later. Now, start eclipse and pick a workspace that is different from where you saved the two zip files. A workspace is essentially directory where eclipse will place and manage your projects. Now, from the eclipse menu, select File -> Import, then select the General -> Existing Project into Workspace and hit the Next button. Then select the Select archive file radio button and Browse to the ElectionDataViewer.zip file you just downloaded. Once selected, hit the Open and then Finish buttons and the project should be imported. This is the code you will be adding onto here in HW 1. Look at the src directory and you should find that it contains a number of source files organized carefully into separate packages. Soon enough you'll know everything inside.

What about DBFEditor? Well, we'll be making a complete ElectionDataViewer application in this first HW, which will be loading and playing around with election data stored in .dbf files. The DBFFileEditor.zip file contains a Java application that can open and view all the contents of a .dbf file and even edit and save changes to .dbf files. This will be useful to you in verifying your own program. Note that with the ElectionDataViewer project, there is a setup directory, which contains two subdirectores: buttons, where we may put images for our application's buttons, and maps, where we may put election data. I would advise that you unzip the DBFEditor program and place the it inside the setup/maps directory so that you may easily view the .dbf files you'll be using.


What .dbf files will we be using?

In this assignment, we'll make use of three different types of .dbf files. Note that I have provided the .dbf file-loading functionality to you already, but you should still understand how it works, and of course you'll need to figure out how to access the loaded data properly. The three types of files are:

SVN

You are now at the stage in your career as a software developer where you should start to use version control software for everything you develop. As such, you are required this semester to use a Subversion tool of your choice for keeping track of your work. With such a tool, every time you make significant changes to your project, you should commit your changes to your SVN repository, which will manage your work. If you are developing on Windows, TortoiseSVN provides an elegant integration with Windows Explorer that makes version control easy. Note that with each HW submission, you must also submit a file entitled SVNLog.txt, which contains all of the contents of your SVN log file. This would document all the SVN updates you made in the course of doing your work. Note that if you are using a Mac or Linux, there are numerous SVN tools available as well. Subeclipse integrates seamlessly with eclipse and is a favorite among Mac users and GIT, while not precisely the same thing as SVN, is a favorite version control technology for Linux users. Our classroom and the rest of the department's Windows Lab comes equipped with TortoiseSVN. The following walks you through on how to use this tool:

Setup your SVN Repository: After installing TortoiseSVN, open Windows Explorer and make a directory called ElectionDataViewer_Repository somewhere outside of any eclipse projects. This will be the place where all your code will be committed to this semester, so put it somewhere easy to find, and not inside any eclipse projects. Now, right click on this directory and select TortoiseSVN-->Create repository here.

SVN Checkout: For your eclipse project, we now want to connect the src directory to the SVN repository such that we can easily commit our changes. In Windows Explorer, right click on your project's src directory and select SVN Checkout. You must then type the full path (or copy and paste) of your repository's directory in the URL of repository field. Make sure to start that URL with file:/// followed by the full C:/... path. Specify your project's src directory as the Checkout directory. Make sure Fully recursive is selected for the Checkout Depth field and click OK. Your project source code is now connected.

SVN Commit: Now, whenever you make significant changes to your project, commit your work to the repository through Windows Explorer by right clicking on the src directory and selecting SVN Commit. Note that every time you commit, you should provide a brief note that explains the changes being committed.

Viewing the SVN Log: Again, for each programming HW, you must submit an SVN log file (SVNLog.txt) that notes all the changes you committed to your repository for the project. To view this log, in Windows Explorer, right-click on your project's src directory and select Tortoise SVN-->Show log. From the view provided by this function, you may select all the log rows and copy them into a text file for you to submit.


Where do we start?

In this HW we will be making a tool for viewing US Presidential Election data for any given year for which we have data. I have only provided you with data for the 1832 and 2008 elections, but during grading we will test other years as well. You are welcome to use the DBFEditor program to make test files for other years if you like. To start with, run the ElectionDataViewer program and you'll see that it provides controls for letting the user select a .dbf file to load (user should select a USPresidentialElectionResultsXXXX.dbf file) and then load it and the corresponding candidates file into our application's data model (ElectionDataModel). What's a data model? Well, as I mentioned with regards to Swing data models, these are classes for managing the data of an application. You see, it's hugely beneficial to efficient development, testing, and maintenance to keep data management code separate from presentation code. So all processing and manipulation of our election data should be done inside the data model, which all presentation manipulation should be done inside the ElectionDataViewer class, which will serve as our view, and focal point/organizer for the entire application.

Election Data Viewer program at startup

Now, run the ElectionDataViewer application and it should startup and load the GUI shown to the right. You'll notice that the application has funtioning Open and Exit buttons. In fact, when you select Open and then choose an election results file, it will load all the data, including candidates, into the data model. It will not, however, display the election data. This is where you'll come in. But before we get to that we need to think about the following:


Again, I am giving you a large amount of code in this assignment you may use in all subsequent assignments. Make sure by the time you handin your HW 1 that you understand what every single line of code does. As you work on this project, test your progress periodically after adding each code snippet. Without doing so you will be skipping and important learning step: FEEDBACK.


The Debugger is your Friend

Using eclipse, put a Breakpoint on the first line of code in the ElectionDataViewer's main method and Run the debugger for the application. It should start at that breakpoint. Then, very slowly, press Step Into to walk through the code. By doing this you'll see how the program is initialized. Once you reach the setVisible method call you should step over it and the frame should open. Then, go to the DBFOpenHandler class and put a Breakpoint on the first line of code of the actionPerformed method. Now, when you press the Open button, you'll be able to witness the event handler in action. The handler will open a dialog that asks the user to select a file, which you should do, and then will load that file into the data model. Carefully watch this entire process. The debugger is a great tool for learning how someone else's code works, which is a skill you'll need your entire programming career.


Your Additional Contributions

As is, the program compiles and runs, allowing the user to load election data, but of course, we'll need to add lots of functionality. In order to complete the assignment, add the following:

Remember, one of the most important principles for you to learn this semester is to plan, then do. You must learn how all of the code works and why it is arranged as is before starting, and you must plan your approach before coding. Don't just march off to the north pole in your underwear and hope for the best. The image below provides an approximation of how your application should look and behave, and of course demonstrations of my solution are being given during lecture.

Completed Election Data Viewer App


Handin Instructions

Go to the hand-in instructions page for the details on the required handin procedure. You must hand in by the designated due date and time in the course schedule for credit. Late assignments will not be graded. For this assignment you will need to handin the following:



Grading

Note that grading for this assignment will be done in two stages using the HW 1 Grading Criteria spreadsheet. Note that in this file there are two Worksheets, one for each grading component:



SUNYSB CSWeb page created and maintained
by Richard McKenna