Using Chain of Responsibility in REALbasic

So you're writing a complex application and you stumble across a problem. You're coding the Action event for some menu or button and you realize that you don't have access to the instance of some other object where you want the action to occur. For example, you push a button and you want a floating window to display a picture -- but you don't have a reference to the floating window in question. So how do you deal with this sort of situation? You use the Chain of Responsibility pattern, of course! I tend to (mistakenly) refer to this as the Command pattern because the basic concept is that you send "commands" out into the ether, and whoever is responsible for handling that command will get the message and deal with it.

So to be more clear -- you use this pattern whenever you want an arbitrary object to handle a command, but you don't have direct knowledge of the object. However, there's a side benefit to using this pattern, which is that your application becomes easier to control (a topic which I will discuss a little later). However, there is a downside to using this pattern. Because you don't know what object is going to handle the command, you can't be certain of whether any object will handle it. It's possible that you throw a command out that gets dropped on the floor because nothing handles it.

The way this pattern works is quite simple. There's a main module that is responsible for dispatching commands to all the windows in your application. So the caller simply says "Dispatch this message", and then windows begin getting a "message dispatched" event so they can handle it. Once a window handles the message, the entire process stops. So let's take a look at how the code works.

First, we need to be able to tell which windows are able to handle commands. To do that, we need an Interface:
[rbcode]
Interface Commandable
Function HandleCommand( cmd as String ) as Boolean
End Function
End Interface
[/rbcode]
That's pretty simple -- there's one function that the window needs to implement, which is the function to handle commands. Commands need some sort of unique identifier, so we'll use strings to clarify which message occurred. You could use an Integer if you'd like, but I like using strings because they're easier to work with (you can print debug information about them much easier).

Before we continue, I want to talk about how to make a window implement an interface. You need to make a new Class, set its Super to Window and then make the class implement the interface. Then, take your Window object and set its Super to the new class you just made. If you'd like, you can override the class' interface implementation (so that you can have access to everything in the window such as controls). It's a royal mess. Thankfully, in RB 2005 the process got *much* easier -- just tell the window to implement the interface in the project editor tab like you would with any other class. Continuing on....

Now we know what function we're calling, so let's take a look at how the dispatcher works. It simply needs to loop over windows to see which ones are commandable and then call HandleCommand on them. Check it out!
[rbcode]
Module Commands
Protected Sub Dispatch( cmd as String )
Dim i, count as Integer

// Get the number of windows so that we can loop over them
count = WindowCount
for i = 0 to count - 1
// Check to see if the window is commandable or not
if Window( i ) IsA Commandable then
// If the window handles the command, then we should
// bail out.
if Commandable( Window( i ) ).HandleCommand( cmd ) then return
end if
next i
End Sub
End Module
[/rbcode]
As you can see, the method is quite simple. It loops over all the windows in the project and looks for the ones which are Commandable. When it finds one, it calls HandleCommand. If the call returns true, then we're done (the command was handled), otherwise we continue on to the next window in the list.

Now that we have the building blocks for the pattern done, let's make it much more powerful. The astute reader may have noticed there are two places we can improve this concept. The first way we can make it more powerful is by including controls in our list of things to search. By doing this, you can have a custom control on a window which is in charge of handling a command. For example, you could have a GraphCanvas class which handles the "New Data Point" command. If we leave things the way they are then then window is responsible for handling the command and passing the information along to the canvas. This is too tight of coupling for my tastes though. The other improvement to make stems from the fact that a string command doesn't always give enough information. For example, let's say you want to make a command called "Open Document". Simply knowing that you need to open a document isn't enough information to handle the command; you need information about what file to open. So we're going to give ourselves more information by creating a Command class which others can then subclass.

The Command class will continue to encompass the string data type. In fact, you will use the class as it if really were a string with copious use of operator overloading. However, you can subclass the Command class and add on any extra information you need. So let's take a look at this special class, and how to properly use it.
[rbcode]
Class Command
Protected Dim mType as String

Function Operator_Compare( rhs as String ) as Integer
// If the types match, then return 0 to say we're "equal"
if rhs = mType then return 0

return -1
End Function

Sub Operator_Convert( rhs as String )
// Assign the given string to our type
mType = rhs
End Sub
End Class
[/rbcode]
That's all there is to it. We overload the comparison operator so that we can be compared to a string. This lets a Command object be used in a select case statement or if statement without having to muck around with the internals of the class. We also overload the conversion operator so that the user can assign a string to a Command object. Let's see how you'd properly construct and use one of these classes.
[rbcode]
// Creating one
Dim cmd as new Command = "Ring the Bell"

// Using one
select case cmd
case "Ring the Bell"
Beep
end select
[/rbcode]
And most importantly, how do you properly subclass a Command object so that it can be used properly?
[rbcode]
Class OpenDocumentCommand Inherits Command
Dim mFile as FolderItem

Sub Constructor( f as FolderItem )
mType = "Open Document"
mFile = f
End Sub
End Class

// Using it now
select case cmd
case "Open Document"
App.OpenDocument( OpenDocumentCommand( cmd ).mFile )
end select
[/rbcode]
You may be wondering, "how does Aaron typecast a string (cmd) into an OpenDocumentCommand?" Simple! We're going to change the dispatcher so that it works with Commands instead of strings. Again, we're going to be sneaky about it though since you probably don't want to have to make new Command objects every time manually. Here's the new dispatcher code:
[rbcode]
Module Commands
Private Dim mHandled as Boolean

Sub Dispatch( cmd as Command )
// We want to loop over everything in the system
// and give it a chance to handle the command.
mHandled = false

// Loop over every window and give it a shot
dim i, count as Integer
dim j, childCount as Integer
dim wnd as Window

count = WindowCount
for i = 0 to count - 1
// If the window itself is commandable, then we
// need to fire it on the window
wnd = Window( i )

// First loop over all the child controls of the window
// and make sure they get their shot too
childCount = wnd.ControlCount
for j = 0 to childCount - 1
if wnd.Control( j ) IsA Commandable then
if Commandable( wnd.Control( j ) ).HandleCommand( cmd ) then
mHandled = true
return
end if
end if
next j

// Then check the window itself
if wnd IsA Commandable then
if Commandable( wnd ).HandleCommand( cmd ) then
mHandled = true
return
end if
end if
next i

// Finally, ask the App class if it wants to handle it
if App IsA Commandable then
if Commandable( App ).HandleCommand( cmd ) then
mHandled = true
return
end if
end if
End Sub

Sub Dispatch( type as String )
// Make the command object
dim cmd as new Command
// Set it's type
cmd = type
// Dispatch it
Dispatch( cmd )
End Sub

Function CommandWasHandled() as Boolean
return mHandled
End Function

End Module
[/rbcode]
You'll notice that we're now dispatching to child controls of each window as well as the App class (if appropriate), and that we're overloading the Dispatch method. One takes a Command object (so that you can do things like the OpenDocumentCommand), and the other takes a string (so you can make generic command objects still). You'll also notice that I snuck in a way for you to tell whether the last command was handled or not.

The last thing to look at is how to properly work with the HandleCommand function. This is the part where all the real work happens, so the example is going to be rather contrived.
[rbcode]
Class SomeClass
Function HandleCommand( cmd as Command ) as Boolean
select case cmd
case "New Document"
App.NewDocument

case "Open Document"
App.OpenDocument( OpenDocumentCommand( cmd ).mFile )

case "Beep"
Beep

else
// We don't handle this command, so bail out
return false

end select

// If we got here, it's because we handled the command
return true
End Function
End Class
[/rbcode]

Now you're ready to use the extremely powerful Chain of Responsibility design pattern! But you may be wondering, why would I use this and what makes it so powerful?

When used properly, this design pattern allows you to do things like easily script your application. Imagine having a console window where you could construct commands and dispatch them in a generic fashion? This way you don't have to fuss with the UI to test functionality out. Or you can add power features that aren't ready to be exposed yet. Or you can add testing features (like DebugDumpObjects) without bothering to add UI to do so. You could also construct commands from command line parameters and automate the way your application works. Any number of very useful things can be done by using this design pattern. And I can attest for its ease of use -- we use this pattern extensively in RB 2005. For example, every menu item dispatches a command instead of handling the functionality in the menu handler itself. This allows us to decouple the function from the UI so we can have the same functionality when you press a toolbar button as you get when you use a contextual menu, or a real menu, etc.

To see how this works, I made a sample project that you can download here.