HOMEWORK 2: Building Custom Swing Components

This is an INDIVIDUAL assignment.

Objective

In the last assignment you learned how to put together Swing applications by using existing components. In this assignment, you'll learn how to create your own Swing component from scratch. We'll be building the "user content area" that resides in the right hand side of the Courier application. The component you write will have to respond to both keyboard and mouse input (using the mouse to simulate a pen), and render appropriate output.

The learning goals for this assignment are:

Experience with basic component architecture.
Experience with the Swing drawing and repaint pipeline.
Experience with handling a variety of input events.

Description

Don't be intimidated by the length of the homework description! Although long, most of this writeup is here just to provide detail about what I expect from this assignment, as well as some hints about how best to do the implementation.

In this homework, we'll create a custom Swing component that serves as the user content area for the Courier application. The basic idea is that this journal page component serves as a container for text, drawn strokes, and graphical figures, simulating the appearance of a page in a paper notebook. There are a number of specific requirements for this assignment:

#1: Paper-like background

Your component must have a background that looks like a common notebook page. So, for example, you could do a blue graph paper background, or a yellow legal pad style, or something else. This background will be rendered underneath any content that's on the page.

Hint: you can simply write a little routine that draws the necessary fills and lines, and call it first thing in your UI class's paint routine. This will ensure that it gets drawn before any stuff that you render late in that routine.

#2: Support for free-form drawn strokes and shapes

Your component should allow the user to draw onto the page using the mouse (if you're using a pen tablet, the pen also produces mouse events and so this sort of implementation will also work nicely on a pen-based computer).

When the user has selected the free-form ink radio button at the bottom of the content area, the user should be able to draw freehand strokes by dragging the mouse on the page with the button pressed. The component should show the stroke while it is in the process of being drawn, to give appropriate feedback to the user.

When the user has selected the rectangle or oval radio button at the bottom of the content area, the user should be able to draw those shapes in the content area, much as in a normal drawing program (press to position the initial corner, then drag out to change the size, then release to "finalize" the shape). During the drag, you must show the shape to give feedback to the user; this includes "rubber band" behavior, where previous iterations are "undrawn".

Hint: Remember that you'll need to redraw all of these same strokes and shapes anytime the Swing repaint pipeline tells you that you need to paint your component. So, the classic way to do this is to add strokes and shapes to a *display list* that contains the things to be rendered, and then in your paint code you simply iterate through the items to be painted, rendering them to the screen.
Hint: Confused about how to "undraw" the previous shape during a drag? The trick is to remember that you write your paint code so that it always draws the current state of the world. In other words, when the mouse is moved so that the previously drawn iteration of the shape is out of date, the mouse event handling code needs to simply update the display list to reflect the new size of the shape and then initiate a repaint again. (For cases like this, where you might be in the process of drawing a shape that's not yet finalized, you may want to keep a variable called inProgressShape (or some such) that holds any shape that's currently in the process of being drawn. Your mouse handling code would then just update the coordinates in the shape referred to by that variable and initiate a repaint.)
Hint: Painted strokes will look *much* better if you use Java2D's anti-aliasing mechanism. Look at the setRenderingHints() method on Graphics2D.

#3: Support for typed text

Your component should also allow typed text to be entered onto the page. This is functionality that's not included in the real Courier prototype (since it has no keyboard), but we're going to do this to give you experience with text handling in GUI components.

Here's how text entry should work. First, the user selects the Text radio button in the content area (from Homework 1), then mouses out a rectangular region into which the text will go. This region should have a distinct appearance, such as a yellow post-it note. Next, when the user begins typing, the text should appear in the post-it, starting inside the top left, and fill out to the edge of the box. Once a line of text hits the edge, the system should word-wrap to the next line. If the user types more text than can fit in the post-it vertically, the post-it should expand vertically to accommodate the additional text.

While you don't have to do any especially fancy text processing (no ligatures or custom fonts or anything like that), you should make the basics work correctly. The basics are:

You should implement word wrap. This means that when your typing hits the edge of the post-it you should find the rightmost whitespace in the line, break the line there, and put the remaining word on a new line. If there is no whitespace in the line then you can just break the line at the last character that will fit on the line.
Use reasonable linespacing. Remember: ascent + descent + leading.
It's ok to have overlapping post-it notes, and post-its on top of others will visibly block them.

You do not have to implement more complicated features (although you're welcome to for extra credit). For example, you do not have to implement:

Backspacing over already entered characters.
The ability to put the insertion point into already-entered text and edit it.
The ability to select a span of text.

Hint: It's probably possible to build the text functionality by building off the existing JTextArea component in some funky way. Please do NOT do this for this assignment, however. My goal is for you to learn how to do low-level text processing code from scratch. This approach also gives you more control over the text and its appearance.

Hint: While all the word wrapping and repainting stuff may seem difficult, it's possible to architect the code in a way that makes it pretty straightforward. The key is to remember that, like with stokes above, you'll need to keep a data structure containing the text that will be rendered by your component. So one way to architect things is to simply create a new object (called TextRegion perhaps) whenever the user draws the post-it; at a minimum, this object needs to remember the X and width of the post-it, and the set of characters that are associated with it. Whenever characters are typed they are simply added to the string in the current TextRegion object. The job of your paint code, then, is simply to iterate over the list of TextRegions in your display list and draw them to the screen, wrapping as you draw based on the width of the region. In other words, rather than precomputing and saving the positions of every substring, you just figure it out each time when you paint.

#4 Integration with the rest of the application

Once you've implemented and debugged your journal page component, it's time to integrate it into the application you wrote for Homework #1. When your application starts up, it should create one initial instance of the journal page component that represents the first (and only) page currently in your journal. This component should be used in the right side user content area of your application, should resize properly when the window is resized, etc.

Hint: A good overall resize strategy to use is to start the content component at a "reasonable" initial size to allow it to fill the right side of the app without scrolling. Then, allow the content component to be arbitrarily stretched as the user resizes the window, and set the actual size of the content component to be the *maximum* size that it ever acquires after a resize. If the currently available space is smaller than the current size of the component, scroll bars should allow the user to view the entire content area. Any content that's occluded when the window is shrunk would be revealed when the window is later enlarged.

Selecting New Page should create a new page and take you to it. Selecting Delete Page should delete the current page (unless there's only one page--your notebook should always have at least one page). You'll probably want to update your application to have a list of your journal page components so that you can keep track of them.

Selecting Previous and Next should move between the pages.

Hint: I'd recommend that you create a separate PageComponent instance for each page in your application, rather than keeping just one PageComponent and swapping out its data structures. This means, of course, that you'll need to make sure you're only displaying one PageComponent at a time, and switch between which one is visible when next/previous/delete are selected. You can do this by juggling the visibility of your components to ensure that only one's showing at a time (setVisible()), by swapping out which component is contained in the parent at any given time, or by using a layout manager such as CardLayout.

Extra Credit

There are a lot of ways to augment this assignment, should you choose to. Some obvious ways are:

Fancier text processing
- Allow editing of already-entered text. +2 points
- Support backspace to erase text. +1 point
- Fancier post-it note behavior
  - Make the post-its look better, such as with folded corners or drop-shadows.
  - Allow post-its to be dragged
More options
- Customizable fonts, either on a page-wide basis (+1 point) or for individual spans of text (+3 points).
- Customizable pen sizes and ink color. +2 points.
Drag-and-drop, or copy-and-paste
- Add features as seen on the Courier videos, where you can drag-and-drop or copy-and-paste content from the left side window into the right side. For example, you might drag over an address book item, or an image from a web page, to embed it in a journal page on the right. See the Swing data transfer docs (here, here) for details. +1 to +5 points, depending on complexity.
Fancy features
- Saving and loading of pages between restarts. It would be especially cool if this happened automatically as strokes or characters are entered, so that you never explicitly have to hit "save." +3 points
- Other stuff. If you build in some particularly neat feature, make sure you let us know about it in your README.txt file and we'll consider it for possible extra credit.

Special Extra Credit Opportunity

Swing has a pattern called Model-View-Controller (MVC) that represents an optional, different way to architect components. In "normal" components, the paintComponent() method does all the drawing. This works fine, and is what was used by all Swing components up and until Swing acquired a pluggable look-and-feel (PLAF) mechanism. When PLAF came around, Swing introduced a new way to structure components, based on a modified Model-View Controller architecture.

For special extra credit, you can use this style of implementation in your component. Be forewarned that this takes a bit more work, and is a bit more difficult to debug. It does, however, give you lots of flexibility in the future. I would not recommend starting down this path until you've got the basics already working (and save a copy of that version!)

The Java Swing book that I've recommended for the class has details on how to use the MVC pattern in Swing.

In order to use MVC, you need to do several things:

Create a separate model class for your component. The model is the piece that contains the core data structures that represent the state of your component. In this assignment, the model will likely contain the display lists for strokes, shapes, and text associated with the page.
Create a separate UI class for your component (in Swing the UI essentially combines the View and Controller from MVC). This class should be responsible for responding to user input (mouse and key clicks), as well as for drawing the component.
Application programmers do not typically work with the model or the UI classes directly; rather, these classes are an internal architectural feature of a component's implementation. Your new journal page component should extend JComponent and have the necessary boilerplate to set up the model and UI objects that it'll use internally.

There's a bit of standard code that you have to write that sets things up correctly. For example, the model needs to communicate with the UI through ChangeEvents whenever the model's state changes (whenever a new stroke is drawn, for example). This gives a nice, loose coupling between the model and UI, allowing different UIs to be combined with the same model. There are also a few standard methods that you'll have to implement that have to do with telling models about UIs and vice versa.

Hint: Look at the "MVC Meets Swing" link off the Supplemental Readings list for an overview of how this all works. Also, the Java Swing book has a nice section that shows how to do this in detail; look at pages 1133-1155.

To get credit for this architectural style, note that you have to do more than just lump all your data structures into a "model" class. The model, UI, and component classes need to be cleanly separated from each other, communicating via ChangeEvents or PropertyChangeEvents. All event handling code needs to be delegated to the UI class.

If you correctly follow the MVC pattern we'll give up to +10 points on this project. Please let us know in the README if you've implemented this functionality.

Deliverable

See here for instructions on how to submit your homework. These instructions will be the same for each assignment.