-- What it might look like
A Go To dialog is one of the simpler dialog layouts in a word processor
program. The Go To dialog, as Microsoft Word implements it, consists
of a list of types of "targets", an editable text field, and a set of
dynamically changing buttons. A screenshot of Microsoft Word 97's dialog
can be found at http://www.abisource.com/~sterwill/goto.png
Microsoft Word 97 implements its Go To feature through a 3-tabbed
dialog (it also handles find and replace). We just need a single
dialog for Go To. A dialog exists to do Find and Replace.
The buttons on the right-hand-side of this dialog change depending
on the context of the selection in the list of "targets" (labeled
"Go to what" in the screen shot). The button on the bottom is always
labeled "Close". However, if the editable text field is empty (contains
no text), the top two buttons function as "Next" and "Previous", moving
to the next or previous occurance of the target as found from the current
cursor position. If there is text in the text field, the top button
is labeled "Go to", and the "Previous" button is disabled.
-- Walking through documents
Although the Go To dialog is the most visible part of the procedure,
the most thinking will probably go into document navigation. When
the user chooses (for example) to go to Section 5 of the document,
the implementation has to know how to start at the beginning of the
current document and walk forward 5 sections, before placing the
cursor there and completing. The document might not have five complete
sections; word handles this by doing absolutely nothing. I'm not
sure if this is the best way to handle this situation. AbiWord also
has to know where its current editing position is, so it can handle
requests for "Next" and "Previous" targets.
Programmatically navigating the in-memory document is all about
walking through the classes in abi/src/text/fmt/xp. These classes
present the logical layout of a document through the FL_DocLayout
class. You can get a pointer to an instance of this class through
the frame's current view, for your actual navigation. There are
structural notes at the top of abi/src/text/fmt/xp/fl_DocLayout.h;
read them. If you need to move through the document, look at the
classes in abi/src/text/fmt/xp.
A document has sections; a section has blocks (paragraphs); a block has
runs of text within it. Documents, sections, blocks and runs may have
other types of things within them; look through the layout code and you'll
see what I mean.
-- Getting started
I would recommend you start by creating a dialog (for your platform)
which lets you start testing your document navigation code. Such framework
for Go To doesn't have to support all the targets Word supports, since
we don't yet support all of them in our documents (see the end of this
message for a list of the targets Word 97 supports). Creating a new dialog
for use by all platforms in AbiWord is documented in the AbiSource tree
at abi/docs/AbiSource_DialogFramework.abw. The basics are as follows:
o Decide if this is an XAP (cross-application) or AP (just word processor)
feature. Start building in abi/src/af/xap if the former,
abi/src/wp/ap if the latter.
o Create an xp (cross platform) implementation of your dialog at
the correct location (abi/src/wp/ap for Go To). This implementation
should handle all the guts of the job. See other dialogs for
examples (Insert Break dialog is a good one). This class will
do the actual document walking/searching.
o Implement a class for your platform (in abi/src/wp/ap/unix,
abi/src/wp/ap/beos, etc.), deriving from the xp class you just
wrote, but implementing actual interaction with your windowing
system.
o Start on implementing the hooks for document navigation that
you'll need to do your job. abi/src/af/text/fmt/xp/fv_View.h
is a great place to look for generic document facilities already
done for you.
See the in-tree docs about updating our dialog factory constants and
other little details.
A tip: when you're doing the navigation of the document, you might be
better off handling the walking in the view code itself (FV_View class,
fv_View.cpp file), and with a set of well-defined public methods
for your xp dialog to call. Doing so keeps the view code inside
the view, where it could be reused later, but also saves you from the
headaches of trying to do fine-level document automation from a
high-level view of it. Getting into the view class makes this easier.
If you've got a working design for how the dialog should talk to the
view, send it on by the dev list (abiword-dev@abisource.com). We'd
like to see how you might have things planned, and we're always here
to help in case you get stuck on something.
-- Little details
Go To targets Word 97 supports:
page section line bookmark comment footnote endnote
field table graphic equation object heading
... obviously we won't need support for all of them, since we don't
support all of these elements of a document yet. We will definitely
want page, section and line.
Prehistoric work in the tree:
A long time ago, I started a Unix implementation of the Go To dialog;
this work is not currently compiled into the executable, and is just
the files abi/src/wp/ap/unix/ap_UnixDialog_Goto.[h,cpp]. The first
progress towards a Go To dialog was minimal, the
implementation incomplete, and the Blessed Method of dialog event
handling has changed somewhat. Look for other dialogs as examples.
There are also a few enumerated constants at the top of fv_View.h.
Please replace these with new, better constants, or remove them in
favor of enumeration of these types in a different place. I would
recommend you use some sort of pseudo-type to denote which operation
is taking place, since doing so keeps a clean separation between our
code and the localizable user interface.
I never did a real cross-platform implementation of Go To. This is
your job.
Have fun!
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
-- Shaw Terwilliger
