Bit by Bit: Introducing Rephrase
By Stephen Beaulieu <hippo@be.com>

Our application-building exercise begins with Rephrase,
a BTextView based text-processing application. Over the
next few months, I'll add features in each installment,
and explain the BeOS coding philosophy behind them.

You'll find the first version of Rephrase at

<ftp://ftp.be.com/pub/samples/tutorials/rephrase/rephrase0.1d1.zip>

Rephrase 0.1d1
New Features
Edit text within the window.
Drag and drop for open and save.
About box.

This limited version of Rephrase is essentially an
application wrapped around a standard BTextView. It has
a BApplication and a BWindow for the text view to live in.
There is an About window, with a basic set of menu items in
the main window to bring up the about window, quit the
application, and edit the text.

The application's real functionality (limited as it is)
comes from the BTextView. It lets you cut, copy, paste,
and select the text. It even provides limited file i/o
through inherent drag and drop capabilites: select text
and drag it to the Tracker to save a text clipping, or
drag a file to the view to paste in its contents.

Although it has only 164 lines of code (many of them
blank or comments), the application is surprisingly
functional. With the addition of resizing, scrollbars
and real open and save capabilities, Rephrase could even
be useful.


Programming Concepts

BeOS uses a system of messaging to manage most aspects
of communication and event handling. BLoopers run an
event loop in a thread that receives incoming messages
and dispatches them to associated BHandlers to be acted
on.

BApplication provides a connection to the Application
Server, which enables the messaging system for the app.
It also serves as the main looper for interapplication
communication and application global services, such as
displaying an About window. A global pointer to the
BApplication object (be_app), is available throughout
the application.

BWindows and BViews are the specialized loopers and
handlers for managing the graphical user interface. When
visible, a BWindow represents an area on screen. A
BWindow maintains a hierarchy of BViews that draw in
and handle messages for sections of that area. User
interaction generates messages that are delivered to
the window, which passes them to the BViews to handle
as appropriate.

For example, when you select a menu item in Rephrase, a
message is sent to the BMenuItem's target. The menu
item's window is the default target. However, the menu
item can be told to send its message elsewhere. For
instance, when "About Rephrase" is selected from the
File menu, a message is sent to the BApplication. All
the menu items in the Edit menu send their messages to
the BTextView.


Implementation Details

1. In main(), create the application on the stack, call
   Run() and return after run completes.

2. Don't hard-code your interface details. Some views
   resize themselves to match their contents. Menus, for
   example, resize to match the size of the characters in
   their font. After you create and add the menu, determine
   its size and use that information to place the rest of
   your views. Change the size of your font in the Menu
   preferences panel, run Rephrase and see.

3. Do not delete a BLooper. Send it a B_QUIT_REQUESTED
   message instead. This calls its QuitRequested() hook
   function, and if that returns true, will call the
   Quit() function which tears down the looper.

4. Windows own their child views and will properly delete
   them when destroyed. Only delete a view if you have
   already called RemoveChild() to remove it from its
   parent.

5. Invokers own their model messages and will properly
   delete them when destroyed.

6. When an app's last window is asked to quit, it should
   request the app to quit as well. If not, the application
   may hang around in the Deskbar with no windows.

Next week: Opening a file.
