Early Access: Creating Custom Components (Outline Only)

Below is the new outline for the "Custom Painting" lesson. We're changing the lesson title to "Creating Custom Components" and will be providing a number of technical updates to make the material current with JDK 6. I've also changed the flow of the discussion to become a little more direct and to the point. Below is the proposed outline for the new lesson. If you have suggestions for anything else to add to it, now is the time to tell us! Or if you think this outline makes sense as-is, we'd like to hear that too. I hope to have the first draft of this lesson ready for review within the next month or so.

-- Scott Hommel

---

Introduction

What are Custom Components?

This section will provide an overview of custom components. This should contain a screenshot or two showing some standard Swing component (like JButton), followed by a custom component (like MyButton.) The reader will create this custom component near the end of the lesson. The narrative should explain that in most cases the default swing components will be enough, but if you really need to, you can create custom components as described in this lesson. This section should describe that custom components are classes of your own design that extend specific Swing classes, such as JComponent. By the end of this introduction the reader should clearly understand what we mean when we say "custom component" or "custom painting."

What You Will Learn in This Lesson

This section will provide a summary about the concepts that will be explained in this lesson. When the reader finishes the introduction there should be a clear understanding of this lesson's scope. For example, the reader will know that default behavior is covered first, followed by a discussion of the coordinate system, followed by ... etc.

General Checklist Before Proceeding

The narrative for this section should describe a general checklist of criteria to help the reader decide whether or not creating a custom component is even necessary. For example, it would not make sense to create an "image button" class when JButton can already display an image. We should probably provide links here to all of the other "How to use..." lessons. The content for this checklist could be based on the material that is currently at the end of this lesson, but I would like to make it more complete. I don't have details for this checklist at this point but am open to suggestions from Swing engineering and our online readers.

How Swing Components are Displayed

The narrative for this section will state that all Swing GUIs have a containment heirarchy; a simple application (such as the existing SwingApplication demo) might be composed of a JFrame, which then contains a JPanel, which then contains a JButton and a JLabel. [Insert GUI screenshot here, followed buy a diagram of the containment heirarchy for it.] This will start the reader off with something concrete that can be imagined easily. Point out that generally speaking, Swing components will repaint or resize themselves automatically in response to various actions such as restoring a minimized window or typing text into a textfield. State that your custom components will inherit this default behavior; to understand how components are painted, you only really need to learn three painting-specific methods (defined by JComponent):

• protected void paintComponent(Graphics g)
• protected void paintBorder(Graphics g)
• protected void paintChildren(Graphics g)

Of these three methods, paintComponent paints the background (with the help of ComponentUI), paintBorder paints the border, and paintChildren paints any of the contained components.

[insert the illustration here.]

Note that we should not be showing any custom code at this point. This section is just about understanding how the core components paint themselves, not how to override that behavior.

We could finish this section with a discussion of Opaque vs. Non-Opaque components. Must find out from engineering what this discussion should cover. The existing section on transparent components needs some technical corrections... do we bring forward the miscellaneous content that was scattered throughout the current lesson? (Custom hit detection for non-opaque components, etc.) or create new content? Depends on what engineering feels is most important to discuss.

Understanding the Coordinate System, Graphics, and Graphics2D Objects

This section explains the coordinate system, Graphics, and Graphics2D objects. I'm going to move the extra links for Graphics and 2D docs to somewhere else, like at the end of the chapter. In general we find that too many forward references leave the reader with an uneasy feeling.

The Coordinate System

Will retain much of this information; images need updating to use grids for illustrative purposes. The border discussion needs some adjustment since borders are a little trickier than what is described here. Narrative to discuss how each component has its own coordinate system ranging from (0,0) to (width-1,height-1). Mention related methods such as getWidth/getHeight. The existing discussion reads fine and I won't change it much except for the technical corrections and coding recommendations provided by engineering. However, I may move the paintComponent code snippet somewhere else though, because it currently interrupts the flow of coordinate system discussion -> coordinate system demo applications.

As for the demo applications, my recommendation is to keep only the first demo, which is intended to help the user get a feel for the coordinate system. Its source code isn't discussed anywhere (and shouldn't be); its just an aid for exploring the coordinate system with mouse clicks. The second demo, however, doesn't seem to fit. It basically demonstrates the same thing as the first demo, but spends effort explaining rectangles and special clip areas... we really don't want to go off on a tangent here about this. One example is enough to give the user a feel for the coordinate system.

The Graphics and Graphics2D Objects

The basic idea of this section is to explain that paintComponent (and related methods) receive a single Graphics object as their parameter. Graphics provides a context and some basic methods like drawRect, fillRect etc. This object can be cast to a Graphics2D object, which provides additional methods. This sections need to be rewritten to explore the relationship between these two classes, and why you would choose one over the other. The narrative will also mention the state of the Graphics object, similar to the current discussion, but we should move the code snippets from here to the end of the lesson where we are actually coding an application.

Implementing a Custom Component

THIS is the place to provide code examples. Here we will develop a custom component and walk the user through its design and implementation. The narrative for this section will recommend best practices, such as preserving the Graphics state. The bullet items of this page raise some good points, but it should be worked into the narrative. They are currently out of place because the lesson has not yet walked the reader through the process of creating anything; we don't want to provide a list of "reminders" before the reader has actually worked through an example.

The demo on this page is currently a custom component called "IconDisplayer". It then spends the rest of the page describing its implementation. I plan to replace this example with one that would be more useful as a reusable component in real-world applications. Question: Should this section contain just one example? Or should we provide two or three code examples (components) instead?

Summary

This section will summarize the key concepts taught in this lesson.

Solving Common Painting Problems

This section will be based on the current tutorial, updated as needed with suggestions from engineering.

Posted at 05:32PM Mar 20, 2007 by The Java Tutorial Team  |  Comments[6]