Splitting Windows
Volume Number: 11
Issue Number: 1
Column Tag: Improving The Framework
Splitting Windows in MacApp 
You know, programming in MacApp is a lot like playing golf.
By Tom Otvos, EveryWare Development Corp.
Note: Source code files accompanying article are located on MacTech CD-ROM orsource code disks.
You know, programming in MacApp is a lot like playing golf. With a little bit of
practice, you can become fairly competent and hit a respectable score, and with about
the same amount of practice, you can write a respectable, Mac-looking application.
There will come a time, however, when you want to stretch the bounds a little bit, and
add some cool user interface gadget that will differentiate your application from
another. You want to hit a birdie on that par four 15th. To make that kind of advance,
you need a little bit more than practice; you need a deeper understanding of the game,
and the ability ”to read the greens”. You need to understand how some of these
disparate parts of a rather complicated application framework come together, so you
can not only make it do what you want, but do it the right way.
Before I lead you too far along, I should say at this point that I am not a very good
golfer. I have not yet made that transition to really knowing what I am doing, and then
merely applying that knowledge to the situation at hand. Okay, let’s cut to the chase. I
am struggling. I have been doing MacApp a bit longer, however, and so I can generally
get it to do what I want in the way that I want it with relative ease. Along the way, I
have picked up a few tricks that, in the end, are really very simple, but they achieve a
neat effect that has a lot of application. In this article, I want to talk about a useful
trick that, amazingly, I was not able to find documented anywhere else, namely
splitting windows. I really needed to split windows for an app that I am working on, so
I created the following two classes to do it. Since it was really very simple and a
trivial amount of code, I figured that sharing it would be the right thing to do. I hope
you find it useful.
Splitting components
So that we have a clear picture in our heads during the following discussion, let’s look
at the geometry a bit. Splitting windows, in MacApp terms, really reduces to taking
two TView objects and adjusting their sizes inversely relative to each other. In the
simplest case, picture two views joined along one edge, and then dragging that edge so
that as one view grows in size, the other shrinks. If the two view objects are the same
class, then you can easily implement the classic word processing implementation of
splitting, where you are looking at the same document in two or more panes, each
displaying a different region of the document. Or, the two views can be from very
different classes that display some common data in different ways. An example might
be a view editor that shows the view hierarchy as it would appear on screen in one
area, and a list representation of the hierarchy in another area.
To split a window, I have created two classes: TSplitterControl and
TSplitterTracker. The TSplitterControl class does two very simple things. First, it
provides a user interface to the splitting action, giving the user a “knob” to direct the
split. Second, it is responsible, at the programmatic level, for initiating the splitting
by instantiating the splitter tracker. The TSplitterTracker class is the workhorse of
the pair, as it tracks the mouse during splitting, providing continual user feedback
and, ultimately, reconfiguring the views after the splitting is done. [Because the code
for these classes is so simple, I will include it in the text of this article. Some code
polish that I have added to my classes will be omitted, but I assure you that nothing
important will be left out.]
TSplitterControl
The class definition for the TSplitterControl is reproduced below.
class TSplitterControl : public TControl
{
private:
TView* fFirstView;
TView* fSecondView;
public:
virtual pascal void Initialize();
virtual pascal void DoMouseCommand(
VPoint& theMouse,
TToolboxEvent* event,
CPoint hysteresis);
virtual pascal void Draw(const VRect& area);
// override
virtual pascal void SuperViewChangedFrame(
const VRect& oldFrame,
const VRect& newFrame,
Boolean invalidate);
virtual pascal void SetSplitViews(
TView* firstView,
TView* secondView);
};
The only method that is of any real consequence is DoMouseCommand():
pascal void TSplitterControl::DoMouseCommand(
VPoint& theMouse,
TToolboxEvent* event,
CPoint hysteresis)
// override
{
// mouse hits in our control will immediately post a splitter
// tracker command
TSplitterTracker* splitter = new TSplitterTracker;
splitter->ISplitterTracker(fFirstView,
fSecondView, this, theMouse);
this->PostCommand(splitter);
inherited::DoMouseCommand(theMouse, event, hysteresis);
}
The only function of this method is to detect mouse hits in our control and post an
instance of our splitter tracker. Note that in MacApp a TTracker is a TCommand
subclass and needs to be posted in the command queue to get executed. Also note that the
control passes to the tracker two views as part of its initialization. These two views
are the views that are going to be adjusted at the end of the splitting process.
The remaining methods of this class are what I lump into “polish”, and you can
provide your own variations as you see fit. Specifically, the Draw() method can be
overridden, as I originally did, to draw a filled rectangle as the splitting knob. Users
of Microsoft Word or MPW will find this type of splitter familiar. Ultimately, I opted
for a splitting more like Object Master or MacBrowse, in which window panes are
dragged by their edges to reconfigure their sizes. In this case, the Draw() method is
superfluous, and the default MacApp drawing with appropriate adornment suits me
just fine. The override to SuperViewChangedFrame() is necessary if you position your
control such that its location needs to be modified when the window is zoomed or
otherwise resized. I can never understand why MacApp views do not have a position
determiner instance variable, with values like posRelRightEdge, so that I do not always
have to override this method.
In my implementation, I always had two views defined in my window and so
effectively, my window was already split. The splitter was merely adjusting the
relative sizes of these views. However, you could easily envision a case where you
would want to do true splitting, and every time you dragged down on the splitter
control, you would split off a new pane of the existing view. I haven’t tried this, but I
would guess that the best way to do this would be to clone the view you wish to split in
the DoMouseCommand() method, insert it into the superview at an appropriate
location, set its initial size to zero, and then pass it into the TSplitterTracker as one of
the views.
One other user interface tip: You can have MacApp automatically change the
cursor when it tracks over your control without writing a single line of code. Just use
your favorite view editor to tell MacApp that the control is going to handle the cursor
(fHandlesCursor), and specify a cursor resource ID (fCursorID) that should be used. I
use a neat double-headed arrow
TSplitterTracker
The tracker does most of the work required for splitting, and MacApp handles
most of the work required for tracking. Typically, you only need to override methods
of TTracker to provide specific user feedback, to constrain tracking in a particular
direction, and to “do something” when the tracking is done. The class definition of
TSplitterTracker is shown below:
class TSplitterTracker : public TTracker
{
private:
VCoordinate fDelta;
TView* fFirstView;
TView* fSecondView;
TView* fSplitter;
public:
virtual pascal void ISplitterTracker(
TView* firstView,
TView* secondView,
TView* splitter,
VPoint& itsMouse);
virtual pascal void TrackConstrain(
TrackPhase aTrackPhase,
const VPoint& anchorPoint,
const VPoint& previousPoint,
VPoint& nextPoint,
Boolean mouseDidMove);
// override
virtual pascal void TrackFeedback(
TrackPhase aTrackPhase,
const VPoint& anchorPoint,
const VPoint& previousPoint,
const VPoint& nextPoint,
Boolean mouseDidMove,
Boolean turnItOn);
// override
virtual pascal void DoIt(); // override
};
I always found trackers a rather mystifying element of the MacApp architecture,
until I sat down and actually wrote a couple. They turn out to be quite simple largely
because MacApp handles a lot of the gory details for you. For example, if you want to
limit tracking in a single direction, the only thing you have to do is override
TrackConstrain() and do something like this:
inherited::TrackConstrain(aTrackPhase, anchorPoint,
previousPoint, nextPoint,
mouseDidMove);
if (mouseDidMove)
// limit tracking to one direction only
nextPoint.h = previousPoint.h;
Basically, this method gives you a chance to recalculate the position of the mouse,
so that MacApp thinks that it only moved in one direction. In the example above, I am
forcing the tracker to only track in the vertical direction.
Initializing the tracker includes one important detail that you must pay attention
to. When you call ITracker, you must provide a view with which the tracker is
associated. One of the side effects of this is that tracking will be clipped to this view,
so typically you would specify an enclosing view that will contain all of the tracking,
such as, in our case, the window being split.
The TrackFeedback() method, not surprisingly, allows you a chance to provide
whatever feedback you wish to the user, as well as hook in during the various track
“phases” to extract whatever information you might think is necessary. For example,
in the code below, I use my override to initialize an instance variable that will be used
to determine how much tracking was done, and when the tracking is done, I calculate
how far the mouse tracked in the vertical direction:
switch (aTrackPhase) {
case trackBegin: // initialize our track delta
fDelta = 0;
break;
case trackEnd: // how far did we go?
// anchor point is always in splitter coordinates
anchor = anchorPoint;
fSplitter->LocalToWindow(anchor);
next = nextPoint;
// next point is always in view coordinates
fView->LocalToWindow(next);
fDelta = next.v - anchor.v;
break;
}
// draw some nice feedback for the user
PenSize(2, 2);
PenPat(&qd.gray);
fView->GetQDExtent(qdExtent);
MoveTo(qdExtent[topLeft].h, nextPoint.v);
LineTo(qdExtent[botRight].h, nextPoint.v);
Additionally, regardless of the track phase, I draw a thick gray line across the
width of the views being split, giving the user clear and easily understood feedback.
MacApp provides some default feedback for you, if you wish to use it, in the form of a
gray outline of the view to which the tracker is attached, but generally, I find that I
have to provide my own feedback for one reason or another.
As mentioned earlier, the TTracker class descends from TCommand, and it uses
the DoIt() method of TCommand to signal when tracking is complete and you need to
react to it in some way. Here is the DoIt() method in its entirety:
pascal void TSplitterTracker::DoIt()
{
VRect frame1, frame2;
// adjust fDelta so neither view becomes invalid
fFirstView->GetFrame(frame1);
if (fDelta < frame1.top - frame1.bottom)
fDelta = frame1.top - frame1.bottom;
fSecondView->GetFrame(frame2);
if (fDelta > frame2.bottom - frame2.top)
fDelta = frame2.bottom - frame2.top;
// adjust the first view from the bottom, the second from the top
frame1.bottom += fDelta;
fFirstView->SetFrame(frame1, kRedraw);
frame2.top += fDelta;
fSecondView->SetFrame(frame2, kRedraw);
}
In the code above, after some preflighting to ensure that neither view becomes
negative in size, the views’ frames are adjusted in the vertical dimension by the delta
amount tracked by the tracker. Note that one view has its bottom adjusted, and the
other has its top adjusted. We could just as easily have tracked in the horizontal
direction, and consequently adjusted the right and left edges. Or, a truly generic
tracker could have been written that could track in either direction, or both. A simple
call to SetFrame() was all that was needed to resize the two views. If your view
hierarchy is set up correctly, then all relevant subviews will resize as necessary.
Additionally, any overrides to SuperViewChangedFrame() in your subviews will also
be called, in case you need to do dynamic repositioning of objects not done automatically
by MacApp.
The Final Word
As I stated at the outset, there is not a lot of code required to achieve the view
splitting effect in MacApp. I was actually amazed that there was not already some
sample code out there that I could mooch from. Equally amazing was that cries for help
on MacApp3Tech$ from others looking for similar code went unanswered. Well,
someone was listening, and I hope that this article helps.
Now, if someone can only help me cure my slice