Streams are the Fundamental Abstraction of java.io.*

java.io consists of around 50 separate classes, and you can divide them up in a few ways. Almost all deal with the input or output of a stream. A stream really isn’t anything formal; it’s just a sequence of bytes that you interpret as data.

Streams may not necessarily be intuitive in some ways, though, so I’ll go over some of the concepts. Understanding these is critical to avoiding alot of the weird situations that you can find yourself in with streams.

Streams have no Implied Structure

The data contained inside a stream has no real indication of its structure; it’s up to the programmer to read it correctly. Java provides two sets of classes to deal with the two common forms of data: InputStream or OutputStream interpret data merely as bytes. Reader or Writer assume your data is textual, and they interpret data as a series of characters. These four abstract classes are the core of the IO package. Other classes supplement these to allow a wider range of expression and abstraction when dealing with data.

The Length of a Stream May Not Be Known

An easy analogy for streams is that they are like arrays. The stream contains a sequence of units of data, the programmer reads them in bits and pieces, and from them, the programmer gains useful information about something.

The analogy breaks down when it comes to finding a length. If you imagine an array, its size is known and fixed. You can access any piece of it at any time, instantly. The entire thing is immediately available. On the other hand, a stream’s size is not known. It’s assumed to end at some point, but may very well not depending on its source.

To belabor this point (and probably appear very patronizing), arrays are crayon boxes. You can pull out any given crayon without having to deal with any other crayons. Streams are like coke machines. You can access one unit of coke per request. Many different functions make this more convenient and faster, but in the end, you (or the methods you’re calling) are stuck dealing with one coke can at a time. You don’t know how many coke cans there are in the machine until the machine tells you it doesn’t have any more.

Of course, we’re talking about streams in the purest sense; for our examples, we know the length of the stream because we provide the data explicitly. The length of files may also be known since the array that we’re “streaming” from is local. So while a stream has no concept of its length, that doesn’t necessarily mean we never know its length. It just means that streams have no concept of their own size.

Streams Do Not Need To Immediately Return; They May Block

The power of streams is in their abstraction. Streams are merely sequences of data. The format is freeform, the length is not a concern, and the source need not be local. This flexibility has its limitations, however. The format must be explicitly given to the user of the stream, an unknown length requires care on the part of the programmer, and non-local sources may take a long time to return.

I’ve mentioned the first two, but the third point definitely requires some mention. A stream is dependent on its source for information. The speed at which that source provides our stream with data is not known, but we are ultimately dependent on that speed. While we’re waiting for that data, we must wait. This state of waiting is known as blocking – we’re blocking any further progress while we wait.

For an example, I’ll return to the crayon box/coke machine example. Getting a crayon from the crayon box is dependent only on how fast you yourself retrieve it. There’s no waiting because between the two concepts of “wanting the crayon” and “having the crayon,” you’re working towards the latter.

If you’re waiting in line at a coke machine, there’s still the two concepts of “wanting a coke” and “having a coke.” However, between these two concepts is a large amount of doing nothing. You’re waiting for other people to do stuff; you’re not working towards the goal directly. The coke machine and its users are blocking you from getting your coke.

There’s a couple clarifications to be made here when relating it to streams. First, the concept of blocking can occur with local things; accessing the hard drive is very expensive compared to accessing memory directly. In this example, your request for data on the hard drive will block until that data is available to use. Even if your request is the only one active, you’ll still have to wait for that process to succeed. Blocking simply means ‘the program cannot continue to execute until this method call successfully returns.’

Blocking Resources Do Not Always Need to Block

Blocking isn’t really an exact term. Waiting for a webpage to load is apparent blocking; you can’t use the webpage until it’s fully loaded. (Of course, there’s incremental loading of pages, but just work with me here.) You can see and feel the waiting. On the other hand, file I/O may not be perceivable. Large files, maybe, but small ones won’t. Memory access, processor cache access are all used with completely inapparent, but existent, wait-times between request and response.

These waits are blocking in the conceptual sense. Of course, we talk about blocking when it comes to network and file I/O but don’t talk about it when it comes to memory I/O. There are two reasons for this: The first is convention – file and network access take long enough to perceptibly block.

The other is more arcane: File and network access do not offer themselves exclusively to the requester. They may be servicing many concurrent requests at once, so we might be queued. These non-exclusive places require may require some form of blocking before they’re actually doing any work at all on our request. This is not true to exclusive resources; these service one person exclusively and constantly.

This last point is more important than it appears: The fact that non-exclusive resources may block means that they’re considering blocking resources. Whether they block on any given request is irrelevant. This marks a distinction between the concept of ‘blocking’ and the action of ‘blocking.’ I may not be blocking, but if I can block on some requests, I am a blocking resource.

Understanding blocking will save you alot of trouble when it comes to streams (or any sort of synchronous request). The fact that streams block means that stream is a potential bottleneck. A set of classes in java.io.* exist to minimize the strain these streams may cause to your performance.

read() Returns One Unit of Data from a Stream

The public interfaces of these classes mirror each other. The input classes mirror the output classes and the byte-based classes mirror their character-based ones, so learning one part of it lets you transfer that knowledge to any other set of classes. Very useful. I’ll start with read() and write().

Derivatives of Reader and InputStream function in the exact same way when dealing with simple I/O. Here’s an example to show this:

// Read one character from the stream
private static void doSomeCharIO() throws IOException {
    Reader reader = new StringReader("This is a happy string.");
    int firstValue = reader.read();
    System.out.println(firstValue + " " + (char)firstValue);
    // Output: "84 T"
}

This straightforward example is probably the smallest IO one can do. We create a StringReader which lets us treat a string as a stream. We then call reader.read() to get the first character. Notice that we don’t actually get a char back. Instead, we’re given an int that we have to cast.

One reason this doesn’t return a char is to be consistent with InputStream. (The other reason is negative values are indicative of errors; I’ll talk more later) At any rate, the lesson here is this: When using any input stream or reader, read() returns a single unit of data (a byte or character depending on the class used) that is always in terms of an integer. Casting that integer to a byte or character, respectively, will get you the data you want.

To prove my point that these two classes are basically the same, here’s the above example but using an InputStream:

// Read one byte from the stream
private static void doSomeByteIO() throws IOException {
    byte[] byteArray = new byte[] { 'T', 'h', 'i' };
    InputStream stream = new ByteArrayInputStream(byteArray);
    int firstValue = stream.read();
    System.out.println(firstValue + " " + (char)firstValue);
    // Output: "84 T"
}

Since we’re using a different format, we need to use different classes. However, other than that, the two examples are identical.

write() is Symmetric to its Reading Counterpart

Write does what you’d expect: It writes a single byte or character. The signature of the simplest method is void write(int b). This signature is identical for both OutputStream and Writer. Since the potential range of values in a single char or byte is less than an int, you don’t need to explicitly cast them. Here’s the code for both, just to demonstrate:

private static void doSomeCharWriting() throws IOException {
    int theValueOfT = (int)'T'; // Should be 84.
    Writer writer = new StringWriter();
    writer.write(theValueOfT);
    System.out.println(writer); // Prints 'T'
}

private static void doSomeByteWriting() throws IOException {
    int theValueOfT = (int)'T'; // Should be 84.
    OutputStream stream = new ByteArrayOutputStream();
    stream.write(theValueOfT);
    System.out.println(stream); // Also prints 'T'
}

As you can see, it’s straightforward. We instantiate the correct class, write our value, then can send it directly to System.out. It should probably be noted that neither OutputStream nor Writer guarantee toString() will work in this way for all their derivatives; retrieving the value of a written stream may vary from class to class.

I’m getting a little self-conscious about the rate at which I’m introducing this stuff. I figure these mechanics seem fairly self-evident; my intention is to demonstrate these fundamentals fully before moving on to more complicated stuff. My hope is that this foundation will serve you well when you’re trying to understand the much more complicated stuff later, as you’ll have this to fall back on.

But after all, dealing with streams in terms of single units is not exactly common place. You’ll probably be dealing in terms of groups of bytes or characters. You may abstract even further and deal with streams in terms of primitives and objects. If your data has some parsing involved, you may need to navigate through the stream. Java’s facilities will serve you will in all these cases.

A Stream Can Work With Arrays of Data

read() and write() can understandably be given arrays as well as single units. The character-based and byte-based stream classes differ only in what type of array they’re expecting, so I’ll only demonstrate one such type here. This example will use a CharArrayReader just because we haven’t used one yet; there’s no motive beyond that.

private static void doSomeSimpleCharReading() throws IOException {
    Reader reader = new CharArrayReader("This could be a character array!".toCharArray());
    char[] charArray = new char[4];
    reader.read(charArray);
    System.out.println(charArray); // Prints "This"
    reader.read(charArray);
    System.out.println(charArray); // Prints " cou"
}

This little tidbit fills our charArray with as many bytes as it can hold (in this case, just 4). Notice that since we’re just dealing with data, the array we give it has no concept of being “filled” or not. You can see here that when we call read() again, we overwrite our previous contents. This can be fairly convenient when you’re dealing with data that comes in known quantities.

On the other hand, having it destroy your array every time it reads may not be what you want. Furthermore, the Reader will fill the array with n bytes, where n is the length of your array. You may not necessarily want it to take that many, but don’t want to make many arrays to handle all the different sizes. Java has more advanced capabilities to deal with this sitaution, but for the moment, the idea is useful to show the final version of write():

private static void doSomeExactCharReading() throws IOException {
    Reader reader = new CharArrayReader(
        "This could be a character array!".toCharArray()
    );
    char[] charArray = new char[10];
    reader.read(charArray, 0, 4);
    System.out.println(charArray); // Roughly prints "This"
    reader.read(charArray, 5, 5);
    System.out.println(charArray); // Roughly prints "This coul"
}

This version of read expects a char[] array for its first argument, like the second form. It also expects an offset and a length. These will be used to determine where to start writing in the array you’ve given it, and how many characters to fill. Notice that you’ll be given an IndexOutOfBoundsException if you try to overflow the array.

Streams Do Not Panic When Reaching the End Of A Stream

At some point, you’ll reach the end of your stream. Many languages throw an exception when this occurs. They provide no other means to determine whether you’ve reached this point, so you’re always having to catch it. This condition makes for clever code (since your EOF, or end-of-file for convenience here, logic is separated), but it’s hardly exceptional. I imagine it is merely the cleverness that justifies using the exception. This is an act grates on me.

Luckily for us, Java reacts calmly in the face of EOF. A tempting solution is to use a stream method called available(). This returns an integer that represents an estimate of how many bytes that can be read without blocking on the next invocation of a method for this input stream. It is NOT necessarily the length of the stream; as I mentioned earlier, streams are coke machines. We don’t necessarily know how long the stream is because the stream may not know. For example, one can’t open a file, make an array of the size that available() returns, and live happily ever after assuming that’s the full length of the file.

The definition I heartlessly stole from the API doc’s is very deliberately phrased. [[ To be continued... ]]

Streams Can Optionally Provide Mark/Reset Functionality

[[ To be continued... ]]

Of course, what kind of advice would that be without backing it up with a long post? Without further ado, here’s details on the pros and cons of all three Java GUI toolkits, and how they compare.

AWT vs. Swing

This is one of those presumably old debates. It used to be relevant around ten years ago, but Swing and Java have both so drastically improved that there’s no reason to use AWT. Furthermore, the debate is somewhat moot since Swing is heavily based on AWT; a more apt title would be AWT vs. AWT with Swing-like sprinkles on top.

In fact, you can think of Swing as the successor to AWT rather than a competing toolkit. If you trace the class hierarchy of most Swing classes, you’ll find it has a AWT ancestor. Swing uses vast swaths of AWT functionality, so much that it’s safe to say Swing is built on top of AWT.

Heavyweight components have a native counterpart; lightweight components do not

Of course, both provide a set of ready-to-use GUI components, like buttons, menus, etc. The discussion of which toolkit to use usually means which set of GUI components to use, since the underlying framework in AWT is used directly by Swing.

It’s been commonly said that AWT’s components are “heavyweight” and Swing’s are “lightweight.” These terms do not necessarily mean either component is worse in terms of functionality or performance. They refer to whether a GUI component is “backed” by a native peer. You can think of a native peer as the “real” GUI component that the host platform would use normally. In other words, a native peer is the C or C++ class that you’d instantiate directly if you were programming in C/C++ exclusively.

The problem with this idea is that native peers necessarily vary between host platforms. Since AWT bases its functionality off these hosts, it is forced to the lowest common denominator of capability. This meant that relatively common components, like tables and trees, could not be included in AWT.

It should be mentioned that neither toolkit actually has a monopoly on either lightweight or heavyweight components. AWT is capable of creating lightweight components, and Swing must use heavyweight components when creating top-level components.

Swing has no native peers; it is pure Java

The limitations of AWT’s functionality led directly to Swing. Swing’s components are lightweight; they are pure Java and do not rely on the host platform. Swing’s components are therefore consistent in behavior across platforms.

Java’s aim is to be seamless, both to the developer and the end-user. The appearance of components should ordinarily look like the host platform’s. To solve this, Swing separated the behavior of components from their appearance. The appearance side is broken into many libraries, each implementing a different look and feel for each host platform.

Swing is, roughly, a superset of AWT

Swing is hardly written from scratch. Many components in Swings deliberately mirror their AWT counterparts. Other features use AWT classes directly. For example, all Swing components are derived from some AWT class, typically java.awt.Component.

Swing lies on top of AWT, adding a richness that the constraints of AWT did not allow. This freedom gives Swing the existing power of AWT with the flexibility to extend it as the designers and developers see fit. AWT’s components, on the other hand, are bound by the slow evolution of various host platforms.

There is no debate; use Swing

People usually see these two frameworks and imagine that there must be some choice to be made. After all, both are still around. However, there is no real choice. Swing is the successor to AWT. The reason AWT is still mentioned is because Swing uses an incredible amount of it.

It should be mentioned that there are no great performance gains anymore between AWT and Swing. Initially, AWT was respectably faster than Swing since native peers do allow performance gains in some cases. However, it’s been awhile since those times, and Swing and its companion libraries (like Java2D) have been optimized heavily. Performance is not a reason to use AWT over Swing.

SWT vs. Swing

Discussing Java toolkits should necessarily include this third-party toolkit, known as SWT or Standard Widget Toolkit. Popularized by its use in Eclipse, SWT can be thought of as a rewritten AWT, but with a Swing-fallback. SWT uses native peers if available but can fall back to pure Java components if a certain platform doesn’t support the features required. The reason for this extends beyond simple performance gains; SWT exposes a far greater amount of low-level functionality to the programmer. The intention is to allow a highly customizable interface for developers.

SWT is not standard

SWT has many forces working against it. For one, its name belies the fact that it’s not standard. SWT is a third-party toolkit not available on a vanilla Java install, nor is it necessarily compatible wherever Java can be run. Since it relies heavily on native integration, a SWT library must be written specifically for each native platform. The problem caused with this isn’t that you’ll be out of luck trying to run it on your machine (SWT already has most OS’s covered). Since SWT intentionally exposes alot of low-level capability, the experience may not be symmetric across these platforms. Reconciling these issues is left to the developer.

Swing’s continuing maturity removes many justifications for SWT

SWT seems more like an impatient solution to the problems of the first-party Java GUI toolkits than a real attempt to innovate GUI development in Java. Its low-level emphasis may be useful in certain cases, but I’d be hardpressed to see a case where SWT exposes something that Swing is unable to do.

Now, this last point is only more recently true. Swing did lack some expected features, such as system tray access, the capability to open a native browser or email client, and so forth. However, these things have since been remedied by their inclusion in AWT. Swing’s (and Java’s) performance problems have also diminished significantly, further reducing the need for native peers and low-level exposure.

Low-level exposure works against expectations in Java

On a fuzzier note, I find that SWT simply doesn’t feel like Java. This is aggravated by the fact that Java already has a GUI toolkit, so the standards have already been set. SWT’s design goals of exposing the meat of the interface you’re building on seems to work against the design goals of Java itself. SWT finds you having to do such heinous things as explictly disposing resources when you’re done with them.

Of course, explicitly disposing resources theoretically allows you to perform faster and cleaner than the garbage collector would otherwise allow. I am somehow reminded of standard versus automatic transmissions. I am also reminded of Pareto’s principle. If garbage collection is your bottleneck, you’re doing something wrong (or very odd).

Now, the problem I’m getting at here is not that SWT requires explicit resource disposal. Indeed, anything that’s touching the underlying native interface must concern themselves with disposal. The problem is that low-level access as a rule simply isn’t necessary in GUI toolkits.

It feels like someone missed programming GUIs in C/C++ and decided to write something in Java that mimics it as much as possible. They knew such a thing would be laughed out of existence, so they made Eclipse use it and named it something that makes it sound like it’s official.

There is no debate; use Swing

In all seriousness, SWT did solve some shortcomings with Swing in the past. But as Swing continues to improve, SWT’s reasons for existence deteriorate. SWT will not get you magnitudes of performance increase on a noticeable level. Nor will its low-level programming model afford you customization that you can’t do in Swing. I simply don’t believe there are valid, wide-scale arguments anymore for using it over Swing.

Imagine you’re writing a class for some framework. You expect a healthy amount of people to use it; it’s not disposable. Designing even a simple class for this case can be painful, usually because your design motivations conflict with one another. Let’s approach these from the viewpoints of various people:

You. You, being the developer, want to write a useful class. You’re hoping to write it fairly quickly, and you don’t want to get stuck correcting mistakes and additions to it

The Casual User. He needs the functionality your class provides, but he doesn’t want to waste alot of time trying to use it. The functionality this provides is tangential to what he’s working on. As a developer, this user is highly predictable in how he’s using your class, and you want to minimize time and code spent for this individual.

The One-Off Guy. He wants the functionality of your class, but will need to do some configuration to get it to work like he wants to. He’s not stretching the definition of your class very much, so ideally the effort required should be trivial and obvious.

The Academic. He sees potential in your class to perform something that you’re not likely to anticipate. He’ll probably want to subclass your class, or plug in a subclassed component that your class uses, to get what he wants.

These three individuals all stress different parts of the system. The casual user loves convention; he is, by definition, conventional. Catering to him will make your class seem monolithic. Favoring the one-off guy instead will stress the configuration of your class. His interests will involve indirect access of some small piece of your system.

These two individuals don’t usually clash. Adding configuration to help the one-off guy usually means providing a default for the casual. In many ways, they’re the same person: Slight variance in the design and defaults of the class will make casual users have to be one-off guys and vice versa. If you can be aware of this balance, you can tune your defaults to favor the majority.

Dealing with Academics

Academics are fringe-cases. They may be interested in pieces of your system that aren’t typically touched by other users. For example, they may not be interested in the conventional use of your system, but the workflow that your class provides. A classic example would be a socket stream: he may want to use the interface that the stream provides, but write it to use an entirely different medium, such as accessing a file locally.

The academic may seem like a trivial concern, since they’re heavily outnumbered by the first two. However, academics stress the design of your class directly. Adding file I/O directly to the stream class makes socket-specific functionality senseless. In the face of this, you have a few options:

• Do nothing. You may choose to rely on the intelligence of your users to ignore socket-specific functionality if they’re dealing with files. While easiest for the developer, it’s rude to make users have to guess how your class should work, especially when your interface isn’t consistent.
• Retrofit the Conventional Case. You may be able to get away with fitting the new functionality into existing methods. In this case, a file stream is “connecting” to a file like a socket stream would connect to a wayward socket. This makes the interface seem consistent, but it really isn’t. You’re still relying on the fact that users will use your class conventionally, and you’ve actually done them a disservice by hiding the true intentions of your class.
• Subclass! What the academic seems to want is a new class that uses the functionality of the parent while extending it to his own needs. Subclassing clearly indicates there is a specialization of functionality present, and both options are clear on their own. This seems like the safest solution, but it has hidden dangers in how the breakdown is performed. You can’t just subclass your socket stream, since doing so leaves you with the same consequences as the first two options (Which one you’re left with depends on details of your implementation). While you have a separate class that works with files, you’re still left with a ambiguous interface that people are stuck using.

Now, this is solvable too. If you remove socket-specific stuff and place it in its own subclass, and make the original stream abstract, it’s pretty obvious what you’re doing.

The Problems of Subclassing

The problem I see with this is proliferation. A FileStream and a SocketStream class may themselves be extended to provide specialized functionality. If they are, then the subclasser must decide which type of stream he wishes to specialize. If he tries to do the Right Thing and be as flexible as possible, he must subclass every permutation of the Stream class. So now you have Stream, FileStream, SocketStream, SpecializedFileStream, SpecializedSocketStream. You’re also forced to implement the full interface of Stream (Even if that interface just throws exceptions) since you’re masquerading as a stream.

Wrapping the streams through composition cleans up the hierarchy. You’d have instead your base Stream classes, and your specializer that takes a stream as an argument to its constructor. Composition is a clean alternative to subclassing that doesn’t muck up the class hierarchy. As a rule, flat class hierarchies are much better than deep ones. The problem here is that it’s difficult to justify not subclassing. After all, your Specializer class is essentially a stream. The only difference is that it’s not a stream like the original stream is.

Refactor? The problem isn’t solved by composition or inheritance because the original class is ill-defined and should be refactored. We organized the functionality of the stream into one class because it makes semantic sense to do so: We connect to the socket, send and receive data, then close it. File I/O involves opening a file, reading and writing data, then closing it. Our problems arise because we have two responsibilities, both potentially flexible, in the same class. When this happens, you’ll have this problem of class proliferation. Composition masks the problem, but inhibits the benefits of the class hierarchy.

What we should do is separate the stream class into its two natural components: The connection, and the encoding. We’ll steal a UNIX tradition and treat files and sockets as fundamentally the same thing. This probably isn’t that big a jump for anyone. The strength here is separating the management of the connection from the encoding of data. Instead of making a Stream class for every type of connection, we separate them both entirely into Encoders and Locations. A stream is a composition of these two. A file and a socket are both subclasses of Location, and a specializer and our original Stream class are both encoders. A stream is, for the most part, a convenience class that is given these two components and manages the events of both.

Why Good Decomposition Is Better

One could probably argue that this solution is overly complex. After all the work, we’ll have the Encoder, Location interfaces, and the Stream class. Two classes implement Location, File and Socket. On top of that, we’ll have our DefaultEncoder and SpecializedEncoder to solve the original problem. That’s five classes and 2 interfaces. That’s more than any other solution. However, hear me out: Classes that are decomposed well are better than fewer classes that are decomposed poorly. We found and separated the two responsibilities that were causing us problems earlier, and now we’re left with two hierarchys that are both very specific in their purpose. As a consequence, I’ll imagine they’re very easy to test. Problems with connection management are isolated inside the Location class, and problems during encoding are isolated within the other. Both classes are also extensible to add new methods of encoding or destinations to which to send.

Even further, there is no coupling between the two class hierarchies. While we’ve constructed them to use them together, there’s nothing keeping us from using these two hierarchies elsewhere. The fact that they are separate encourages this possbility. Sensible factory methods (presumably in Stream) will allow the conventional user to use our Stream uninhibited by the newfound flexibilty that we’ve provided him. The logical decomposition of these responsibilities allows the Academic to extend this class with ease. A set of preconstructed locations and encodings will allow the one-off user easy configuration of the stream.

Why OOP Matters

I should stress one final point: The goal of OOP is not code reuse. We benefit from code reuse when we do good OOP, but reusing code does not mean we are practicing good design. The real goal of OOP is to allow decomposition of responsibility in a fashion that closely resembles how we work and think. This contrasts with functional programming, where decomposition is done along the preference of the machine. The original design of the stream class resembles this – we hardcoded the semantics of the conventional use in the design of the class, instead of hardcoding the responsibility of each concept into the classes.

This probably isn’t very clear – a functional approach to decomposition would yield classes that mirror data structures.  The Stream class is defined by how we’d use it, and its functions expose that conventional use. This works as long as we use the class conventionally. However, when we move beyond that, our class becomes a barrier to progress. It’s difficult to extend a class that exposes this kind of interface. A good responsibility-driven approach to decomposition will yield classes that allow extension and facilitate easy maintenance and testing.

Some details on its implementation:

Feeding ScrolledComponent Content

ScrolledComponent accepts any DisplayObject or subclass thereof as its content property. This will be the component that will be scrolled. All Flex components extend UIComponent, which itself extends DisplayObject so you can throw whatever you want in there. The component we made in the “Extending ScrollControlBase” article would be implemented like so:

var scrolled:ScrolledComponent = new ScrolledComponent();
var image:Image = new Image();
image.source = this.someDisplayAsset; // This would be some embedded image, or a URL to one.
scrolled.content = image;
this.addChild(scrolled);

You could (And probably would) do the same thing in MXML via setting the content property. For convenience, ScrolledComponent defaults to using the content property in MXML, so you can just define the content property inline, like so:

<local:ScrolledComponent width="100%" height="100%">
    <mx:image source="{this.someDisplayAsset}"/>
</local:ScrolledComponent>

You can also use it as a item renderer, since it implements IDataRenderer, and can give it a class to use as content via data property.

Changing How Content Is Displayed

ScrolledComponent implements the following styles and properties affecting its display:

• verticalAlign and horizontalAlign – Affects where content is displayed inside the scrolled content. These work like they do in VBox and HBox. Currently, there is no center or middle alignment, since the use case for those is rare, but adding them wouldn’t be too difficult in your own code. (If you need them, just request it here and I’ll throw them in.)
• verticalPinPolicy – Affects how vertical scrolling works. If this is set to true, the list will stick to the bottom as content is added. Scrolling up will “unpin” the document, but if it is scrolled back to the bottom, it will be stick again. This behavior emulates IRC clients and chat message windows.I didn’t add a horizontalPinPolicy, but if the need arises, I’ll do so. If you wish to implement it, it would act the same as the vertical, but obviously in the horizontal direction. (Again, if you need them, just request so in the comments, and I’ll add it.)

I hope this is useful for anyone looking for a generic scroller, and again, here’s the link to the source. Please post any comments or bug findings here, and I’ll see to them. I’m using this component in my own projects, so I hopefully should run into any before you do.

1. Its Internals and Design Philosophy
2. Displaying the Scrollbars
3. Getting Scrolling to Work
4. The Workflow

Implementing scrolling is an intuitive process, involving merely a mask, updateDisplayList, and an event listener. We’ve implemented from scratch, a scrolled image viewer, but the code is simple enough to be expanded to scroll any arbitrary content (Matter of fact, we’ve actually gone out of the way to make it be image-specific).

To summarize, here’s the generic workflow you’ll use to implement ScrollControlBase in your own components:

1. Extend ScrollControlBase – extend the class, set the policies to any defaults as you see fit.
2. Implement commitProperties – Clean up and remove any old content. Add the new content, and set its mask to maskShape
3. Implement measure – Get the default size of your content, and add viewMetrics to it, assigning the calculated width and height to measuredWidth and measuredHeight, respectively.
4. Implement updateDisplayList – Draw your component if necessary. Its position is given by viewMetrics‘ left and top properties, subtracting any current horizontalScrollPosition and verticalScrollPosition. Finally, call setScrollBarProperties(totalColumns, visibleColumns, totalRows, visibleRows) with the intended visible area, along with the total visible area.
5. Implement scrollHandler – Check if 1.) your content is valid, 2.) this ScrollEvent isn’t from a TextField and thus incompatible with your component, and 3.) that this is a finished scroll if liveScrolling is false. If so, then position your content according to the new positions.

And that’s it. If you find out scrolling is expensive, then it’s probably due to alot of content having to be redrawn. ScrollControlBase enables you to use its scrolling capability and its mask independently, so you can produce your own mask over a smaller area, if necessary (ListBase, and therefore, all List-like deriatives of it) use this in many cases to produce a faster rendering by as much as 25% (As it says in the source). As always, the source code provided in the Flex SDK is invaluable in letting you come up with ways to build components and optimizing it as necessary.

Here’s a link to the complete source of what we wrote. It’s free for you to use, modify, or do whatever.

Our component now has a functional implementation of UIComponent’s methods, but is still missing the ability to scroll. It turns out this requires two, separate, but equally important methods: scrollHandler and setScrollBarProperties. Lets talk them over in turn:

Working with setScrollBarProperties

This method is the brains behind ScrollControlBase. Every time your content changes sizes, this method will need to be called. The signature looks like this:

protected function setScrollBarProperties(
    totalColumns:int, visibleColumns:int,
    totalRows:int, visibleRows:int):void

Notice that the property names are pixel-independent. You simply describe how many rows your content has in total, and how many are visible, with the same for the columns. What a row or column is is dependent on your component. In many cases, these are pixels, but for some cases, a row could be a literal row of data as in a table, or a line of text. TextArea makes each rows a line of text, and each column a pixel, so your own rows and columns don’t necessarily have to be of the same unit. Calling this method will set the properties of the scrollbars as necessary to resize to the size of your data.

Our call is probably the simplest call this function can be, and is done at the end of updateDisplayList:

this.setScrollBarProperties(
    this.currentImage.width,
    unscaledWidth - edgeMetrics.left - edgeMetrics.right,
    this.currentImage.height,
    unscaledHeight - edgeMetrics.top - edgeMetrics.bottom
);

Remember that edgeMetrics is the size of the padding, borders, and viewed scrollbars. Our totalRows and totalColumns is simply the dimensions of our image. The visible rows and columns is the unscaled dimensions given to us as parameters, with the applicable edgeMetrics properties subtracted from each.

With this single call, the scroll bars will be properly shown or hidden, with the thumb (The selectable part) the right size to show all the content. You should call this whenever the size of your content changes, but since that’s usually coupled with a call to updateDisplayList, you’re safe to leave it only there in most cases. You shouldn’t call it in measure, though, since you won’t necessarily have correct unscaled dimensions yet.

Of course, proper scrollbars without event handlers are only eye candy. Let’s make them live.

Implementing scrollHandler

scrollHandler is an event listener implemented originally in ScrollControlBase. It receives updates whenever either scroll bar is moved. (It will even fire when liveScrolling is false, so handling whether this variable is set should be done inside the function). You should respond to scrolling events here.

Our implementation is mostly boilerplate:

override protected function scrollHandler(event:Event):void {
  // Immediately return if there's no image.
  if(!this.currentImage)
    return;

  // Return if it's not a ScrollEvent. This is for TextField scroll events bubbling up that
  // we wouldn't understand.
  if(!(event is ScrollEvent))
    return;

  // And finally, if we're not liveScrolling, and we're in the middle of scrolling, return.
  if (!liveScrolling && ScrollEvent(event).detail == ScrollEventDetail.THUMB_TRACK)
    return;

  super.scrollHandler(event);

  this.currentImage.x = this.viewMetrics.left + -this.horizontalScrollPosition;
  this.currentImage.y = this.viewMetrics.top + -this.verticalScrollPosition;
}

There’s the three return if-statements. Each are commented, so I won’t mention them further here. The call to super.scrollHandler(event) will update the horizontal and vertical scroll positions stored inside ScrollControlBase.

Finally, the two calls move our image in the negative direction of the current position. These two lines are all it takes to implement scrolling in most cases, and with those two lines, you’ll have a functioning scrolling image.

(We add the viewMetrics left and top properties to keep our image flush with the edges of the border, otherwise we’d show a border-thickness worth of background when we’re at the bottom, and clip a border-thickness’ worth of image when we’re at the top.)

It might be asked why we don’t call invalidateDisplayList() instead inside scrollHandler, and ideally, that would be what we would do. But in this case, we’re safe to just update the values directly here, and not invoke the overhead associated with a full cycle of validation.

Read on to the next post to read the summary of what we’ve accomplished, along with a cheat sheet on how to implement basic scrolling in any of your components.

Working with ScrollControlBase revolves around two things: Getting the mask to work right, and getting the scroll bars to function correctly with your image. We’ll cover each in turn in a simple example: Getting an image that’s viewed with a ScrollControlBase.

Our example component has a skeleton like this:

package {
  import mx.core.ScrollControlBase;

  public class ScrollingImage extends ScrollControlBase {
    public function ScrollingImage() {
      super();
      this.horizontalScrollPolicy = "auto";
    }
  }
}

That code by itself gives you essentially a ScrollControlBase directly. It gives you the scrolling properties and methods of ScrollControlBase, but applies no mask to its children at all, so adding any components will result in them being unsized unless explicitly sized, in which case they will occlude the border.

One thing of note is the setting of horizontalScrollPolicy. Scroll policies are really easy and have three possible values: off, on, or auto. offnever shows scroll bars, on always does, and auto does only when there’s content needing to be scrolled. By default, verticalScrollPolicy is set to auto, and horizontalScrollPolicy is set to off. We set it to auto here since it’s as likely we’ll need to scroll horizontally as it is vertically.

For our component, the image being displayed is assumed to be an embedded asset, which are of type Class, so the getter and setters look like this:

    public class ScrollingImage extends ScrollControlBase {

    // Constructor and imports omitted for brevity
    protected var _imageClass:Class;
    public function get imageClass():Class {
      return this._imageClass;
    }

    public function set imageClass(imageClass:Class):void {
      this._imageClass = imageClass;
    }

Of course, this code won’t get us the image added to our display list, since we haven’t instantiated it yet. We could instantiate it and add it there, but of course, we wouldn’t know what size it should be, or whether we’ll have a border eventually or not. The addition and positioning of the image should take place within the implementation rules of UIComponent. So we’ll follow this order to draw any image:

1. commitProperties: Remove the old image if any, add the new one.
2. measure: Retrieve the size of the image, and use that, plus any border and padding of the parent, and set measuredWidth and measuredHeight to those values.
3. updateDisplayList

: Position the image, offset by any padding and border, with the width governed by those values, plus the widths and heights of any scrollbars.

Clearly, changing the image will upset all of these, so we change our setter to the following to invalidate the properties, size, and rendering of our component:

    private var imageClassChanged:Boolean = true;
    protected var currentImage:DisplayObject;
    protected var _imageClass:Class; 

    public function get imageClass():Class {
      return this._imageClass;
    }

    public function set imageClass(imageClass:Class):void {
      this._imageClass = imageClass;
      this.imageClassChanged = true;
      this.invalidateProperties();
      this.invalidateSize();
      this.invalidateDisplayList();
    }

Having a flag variable (in this case, imageClassChanged) is a common practice amongst components. We use this flag in commitProperties so that we only update what’s been changed. We keep the image currently being rendered in a new variable named currentImage, with the imageClass being the cheap, inexpensive variable being changed in the setter.

Now for UIComponent’s three methods we’re overriding. With the exception of updateDisplayList, these methods would look the same if you were implementing any kind of component, but I’ll cover them here for completeness:

1. Implementing commitProperties

The code will look like this:

override protected function commitProperties():void {
  super.commitProperties();
  if(this.imageClassChanged) {
    this.imageClassChanged = false;
    if(this.currentImage) {
      // Clear our old image if any.
      this.removeChild(this.currentImage);
      this.currentImage = null;
    }
    if(this.imageClass) {
      // We have a new image, so load it up.
      this.currentImage = new this.imageClass();

      // Make it invisible for now until it's properly positioned.
      this.currentImage.visible = false;
      this.currentImage.mask = this.maskShape;

      // Finally, add it to our display list.
      this.addChild(this.currentImage);
    }
  }
}

This code doesn’t look very different from any other implementation of commitProperties so I won’t cover it in depth. Basically, you check your flag, and if its true, clear out the old image, and add your new one in. The critical pieces are here are the assignments to mask. Remember to clear the old one otherwise any reuse of the removed image will result in unpredictable behavior. Also, remember to set the new image’s mask to the maskShape property.

You should probably also set the new image’s visible property to false, otherwise you might end up with some unwanted flicker of the unpositioned image in its default size and position.

2. Implementing measure

override protected function measure():void {
  super.measure();

  var edgeMetrics:EdgeMetrics = this.viewMetrics;

  var width:Number = edgeMetrics.left + edgeMetrics.right;
  var height:Number = edgeMetrics.top + edgeMetrics.bottom;

  if(this.currentImage) {
    // We have a real image, so get its dimensions.
    width += this.currentImage.width * this.currentImage.scaleX;
    height += this.currentImage.height * this.currentImage.scaleY;

  } else {
    // No image, so just set it to our edgeMetrics, with an added default size of 40x40
    var defaultSize:Number = 40;
    width += defaultSize;
    height += defaultSize;
  }
  this.measuredWidth = width;
  this.measuredHeight = height;
}

Nothing amazing here either. The complicated piece is getting the size of the image, and getting some default size otherwise. An important note here is the use of viewMetrics. That will give you the size of the border in the ScrollControlBase you’re using, along with any visible scrollbar sizes. Forgetting to use this could result in clipping of the scrollbars if your content is unusually small, so add them to your measured values.

3. Implementing updateDisplayList

First, the code:

override protected function updateDisplayList(unscaledWidth:Number, unscaledHeight:Number):void {
  super.updateDisplayList(unscaledWidth, unscaledHeight);

  if(!this.currentImage)
    return;

  var edgeMetrics:EdgeMetrics = this.viewMetrics;

  this.currentImage.x = edgeMetrics.left + -this.horizontalScrollPosition;
  this.currentImage.y = edgeMetrics.top + -this.verticalScrollPosition;

  // Make the image visible.
  this.currentImage.visible = true;
}

Again, using viewMetrics gets you the necessary offsets for your image. Since we’ve assigned mask of our currentImage already, there’s actually nothing ScrollControlBase-specific here at all.

Viewing the component in this state will show you a properly masked image if one’s assigned, surrounded by a inset border. Really, the implementation so far is quite simple, with the complexity coming from simply implementing a custom component; ScrollControlBase doesn’t get in the way at all, and provides its mask for easy use for your component.

Of course, a critical issue here is that while the image is properly masked, there’s no way to scroll with it. We’ll cover this issue in the next post on getting scrolling to work.

ScrollControlBase is one of those mystery classes that does a shitton of actual work, but isn’t mentioned much at all in the API documentation (Aside from the ScrollControlBase Reference, of course). That’s probably because it’s not intended to be used directly, but rather subclassed (Like ListBase, TileBase, and all the other Bases)

The problem is that I need to extend ScrollControlBase to implement a special kind of behavior: Vertically aligned content so that it appears from the bottom up, like in IRC clients, and some chat windows. I managed to do it with regular text by extending TextArea, but now I need to do it with an HTML element, and extending HTML didn’t work for me, so I decided to extend ScrollControlBase to build the functionality in directly. While I was at it, I wrote up what ScrollControlBase actually does for you, and the workflow needed to extend ScrollControlBase properly:

The Design of ScrollControlBase

ScrollControlBase is not a container, as it is intended to be subclassed. This has a few implications: Firstly, ScrollControlBase does not work via composition; it does not take some .content parameter that’s your content and magically positions it. Rather, it does no drawing of your content at all. It draws the scrollbars, any provided border, and exposes an interface to set their position. It displays the scrolled content accurately via a mask.

Understanding Masks

What a mask does is fairly simple. For the visual people, imagine a piece of paper, with the center cut out. Placing that paper on top of some image, or some article “masks” the rest of the image, showing only a portion. Now, for computers, this mask isn’t the paper, but the shape of the cutout. So if you cut out a circle, the mask you’d use would be a rendered circle. Every display object in flash has a mask property that accepts any display object, and those two are used together to render some image.

If you’re interested in how masks work at a technical level, read on. Otherwise, just skip this section:

For those more mathematically oriented, imagine two values in binary. The first value is 11110000, or four ones followed by four zeros. The second is 00111100, or four ones, with four zeros evenly divded on either side. Apply the bitwise & operation (which returns the value where both values are true in that location, 1 & 1 is 1, 0 & 0 is 0, along with 1 & 0, and 0 & 1). The bitwise & applied to our two values returns 00110000. At a bitwise level, a mask is just using & creatively, and neither value is inherently a mask or not.

At a higher level, the mask is usually itself some primitive image. Typically, all of a mask’s values are used to produce the derivation. That is, a black image masked over some source image, would produce an image the shape of the mask, with the image coming from the source. That’s of course not to say that some specific color channel couldn’t be used as the mask, producing the images showing only the reds, greens, or blues in some image.

For further information, check out this post on masks specifically in Flash and their various uses

What ScrollControlBase doesn’t do

ScrollControlBase, as previously mentioned, only draws a mask over its children, and adds interface to support scroll bars, positions, and adding a border. It doesn’t manipulate the position, or size, of the content it contains.

That ScrollControlBase has no default scrolling behavior could be construed as a weakness, since ScrollControlBase could directly manage the position of its content, and not have to have subclasses do it. However, that would mean that the subclasses would have to have their content fully rendered*. For very long lists, this would be very expensive to do. Instead, it lets children build in their own optimizations, like in the case of ListBase, which recycles its renders; as you scrol through the list, fully occluded renders are added to a freed list, and used to display the content coming up from the bottom. This allows list implementations to be as inexpensive as possible, since everything is done just in time.

*One could argue that the list being rendered could just give a filler for the content not exposed, allowing ScrollControlBase to still function as normal. This would work, but you’re still having to recycle renderers to gain the same level of functionality, so you’re not saving yourselves much as far as work needed to do to draw your list. I’d assume Flex developers figured each implementation would differ greatly enough in its optimziation that providing a default way would be too ambiguous to be useful.

Read on to see how to actually implement a sublcass of ScrollControlBase.