HOMEWORK 2: Building Custom Swing Components

This is an INDIVIDUAL assignment.


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:


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. This new component that you create should be subclassed from JComponent, and will serve to display 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 data structure you create that serves as a display list that contains the things to be rendered, and then in your paint code you simply iterate through them, painting them as you go.

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 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. For this assignment, the basics are:

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:

Hint: While you could perhaps build off the JTextArea component as a way to implement the post-it notes, please do not do that for this assignment. 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:


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