Subject: POW -- change page margins
From: Paul Rohr (paul@abisource.com)
Date: Wed Mar 01 2000 - 16:31:19 CST
It's time for another Project of the Week (POW)!
If you're interested in using XP (cross-platform) code to do some snazzy GUI
work, this week's project is for you.
background
----------
Currently, our rulers allow users to interactively adjust the following
properties:
paragraph -- margin-left, left-indent, margin-right, tabstops
section -- column-gap
In each case, the way this works is we hit-test mouse clicks and drags to
see if they're "over" a ruler control. If so, we redraw the ruler on-the
fly to reflect the updated position of that control, giving immediate
feedback to the user. While dragging, we also draw an XOR guideline over
the document, which helps line things up. Then, when the mouse is released,
we check to see if the control moved from its original spot. If so, we
change the appropriate properties for the current selection.
Better yet, all of this logic happens in XP code, which means that once it's
coded and tested on one platform, it Just Works on all the others. Pretty
cool, huh? :-)
scope
-----
Your mission, should you choose to accept it, is to do the same thing for
page margins. They're currently already drawn properly on the rulers (that
light gray stripe between the white body of the ruler and the dark gray
margins).
What you'll be doing is making those controls draggable (just like the
paragraph, tab, and column-gap controls), and using it to update the
following section-level properties:
top ruler -- page-margin-left, page-margin-right
left ruler -- page-margin-top, page-margin-bottom
The formatter already honors these properties, so you can focus on just
doing the GUI work required.
The work you'll need to do can be divided into three steps. Since you'll be
changing a section-level property, in each case you'll be mimicking the
existing code for another section-level property ("column-gap").
step I: first, do a little tidying over in the View
------
Take a look at the existing FV_View::getSectionFormat() implementation.
abi/src/text/fmt/xp/fv_View.cpp
See where it lists the "columns" and "column-gap" properties? Add the four
new section properties here as well.
step II: get the top ruler working
-------
This one should be fairly easy. Start by looking at all of the DW_COLUMNGAP
cases in the following file:
abi/src/wp/ap/xp/ap_TopRuler.cpp
You should be able to easily figure out how to implement similar code for
DW_LEFTMARGIN and DW_RIGHTMARGIN in each spot, such as:
mousePress()
mouseRelease()
mouseMotion()
_ignoreEvent()
In fact, some of the necessary code is already there, but #if 0-d out. Your
job is to turn it all back on, and fiddle with things until all the subtle
behaviors "feel" right.
For example, some of the controls draw in a "ghostly" fashion while being
dragged, so that you can see where it started, as well as where you
currently are. Does that feel right for page margins, or should the change
look more live than that? If so, how much of the ruler (and tick marks)
will need to be redrawn?
The goal is to come up with a nice responsive visual illusion. Have fun
with it. :-)
step III: get the left ruler working
--------
Once you've gotten everything thoroughly debugged in step II, you'll need to
replicate the comparable code on the left ruler. This is essentially a cut
& paste job, where you swap horizontal for vertical dimensions.
abi/src/wp/ap/xp/ap_LeftRuler.cpp
abi/src/wp/ap/xp/ap_LeftRuler.h
However, since there aren't currently any draggable controls on the left
ruler, you'll have to copy a *bunch* of code and adapt for the changed
orientation. For example, you'll probably need to replicate the
platform-specific code which passes mouse events into the XP ruler logic.
This isn't hard, it just takes a little time to get everything copied over
and wired up properly.
extra credit
------------
The goal for this POW is to make sure that the preceding three steps Just
Work and get checked in.
However, along the way you'll be learning a lot about how the ruler code
works, so when you're done, you may also want to think about what it would
take to deal with one or more of the following issues:
1. There are a number of little ruler-specific problems in Bugzilla.
http://www.abisource.com/bugzilla/
Many of these could be solved by adding some reasonable constraints on the
motion of various ruler controls, right? However, figuring out what's
reasonable may take some fiddling and/or reverse engineering.
2. Are the paragraph margin triangles too tall? We want to make it easy to
click on them, but you'll quickly realize that there's not much room in
between them to grab the page-margin control. This could be fixed in one of
two ways: make the entire ruler taller, or make those triangles a pixel
"shorter". Again, the question is -- which "feels" better?
3. Cursor changes would help. As with any direct-manipulation GUI, having
the cursor change when you're over a usable control really helps provide
immediate feedback to users *before* they click. For example, having a
left-right arrow cursor over the page margin control would let you know that
the click will work, instead of adding another tab there.
However, to make this work will require some additional APIs back and forth
between XP and platform code. When you have a proposed API, let us know.
I'm not sure whether the FV_View cursor context mechanisms are a helpful
model or not.
4. Tooltips would be even cooler. This one probably involves even more
platform-specific work, so definitely tackle #3 first before dealing with
this one. Since this feature will involve generating localized text in a
popup window, I'm really not sure where the API line should be drawn.
Leveraging platform-specific tooltip classes might be your best bet, or you
may just want to use XP timers to raise a platform-specific popup window,
then render all the text into it using XP graphics APIs. YMMV.
Enjoy!
Paul
PS: For more background on the whole POW / ZAP / SHAZAM concept, see the
following introduction:
http://www.abisource.com/mailinglists/abiword-dev/99/September/0097.html
This archive was generated by hypermail 2b25 : Wed Mar 01 2000 - 16:25:53 CST