The view that's responsible for handling keyboard events is called as the focus view. The focus view is the view within the active window that's displaying the current selection, or the control that's marked to show that it can be operated from the keyboard. Only one view in the window can be in focus at a time.

You promote a view to focus by calling BView::MakeFocus(), and you ask for the current focus through BWindow::CurrentFocus().

The table below maps a keyboard action to the hook function it invokes or the message it sends. In each of these cases, the function or message is sent to the current focus view (which may change between a key down and a key up)

The focus view needn't respond to all of these functions and commands, but a BView that doesn't respond to any of them should never promote itself to focus.

There are four other built-in keyboard commands:

B_KEY_UP events are always assigned to the view that's in focus when the user releases the key—even if the previous B_KEY_DOWN message performed a shortcut, forced keyboard navigation, or was assigned to the default button.

The event messages that the Application Server sends to a BWindow usually have more information in them than is passed to the corresponding hook function. For example, while a B_MOUSE_DOWN message knows where, when, and which mouse button was pressed (among other things), only the "where" information is passed to the MouseDown() function.

You can retrieve the message that initiated a hook function from within the hook function itself by calling BLooper::CurrentMessage() function:

void MyView::MouseDown(BPoint where)
{
   BMessage *msg = Window()->CurrentMessage();
   ...

Keyboard navigation is a mechanism for allowing users to manipulate views—especially buttons, check boxes, and other control devices—from the keyboard. It gives users the ability to:

• Move the focus of keyboard actions from view to view within a window by pressing the Tab key.

• Operate the view that's currently in focus by pressing spacebar and Enter (to invoke it) or the arrow keys (to move around inside it).

The first ability—navigation between views—is implemented by the Interface Kit. The second—navigation within a view—is up to individual applications (although the BControl class helps a little), as are most view-specific aspects of the user interface. The only trick, and it's not a difficult one, is to make the two kinds of navigation work together.

To participate in the navigation mechanism, a class derived from BView needs to coordinate three aspects of its code—setting navigation flags, drawing an indication that the BView is in focus, and responding to keyboard events. The following sections discuss each of these elements.

The B_NAVIGABLE flag marks a BView as an eligible target for keyboard navigation. It's one flag in a mask that the BView constructor sets, along with other view attributes. For example:

MyView::MyView(BRect frame, const char *name,
                        uint32 resizingMode, uint32 flags)
   : BView(frame, name, resizingMode, flags|B_NAVIGIBLE|B_WILL_DRAW)
{
   . . .
}

When the user presses the Tab key, the focus moves from one B_NAVIGIBLE target to the next, working first down and then across the view hierarchy. That is, if a BView has both B_NAVIGIBLE children and B_NAVIGIBLE siblings, the children will be targeted before the siblings.

The flag should be removed from the mask when the view is disabled or cannot become the focus view for any reason, and included again when it's re-enabled. The mask can be altered with the SetFlags() function:

if ( /* cannot become the focus view */ )
   SetFlags(Flags() & ~B_NAVIGIBLE);
else
   SetFlags(Flags() | B_NAVIGIBLE);

Most navigible BViews are control devices and derive from the BControl class. All BControl are navigible by default and BControl has a SetEnabled() function that turns the B_NAVIGIBLE flag on and off, so this work is already done for objects that inherit from BControl.

You may also want to set a view's B_NAVIGIBLE_JUMP flag to permit larger jumps between navigible views. Control+Tab moves the focus from one group of views to another, where the groups are (hopefully) obvious to the user from their arrangement in the window.

B_NAVIGIBLE_JUMP marks positions in the view hierarchy for these larger jumps. When the user presses Control+Tab, focus jumps to the next B_NAVIGIBLE_JUMP view. If a B_NAVIGABLE_JUMP view isn't also B_NAVIGABLE, focus moves to the next available B_NAVIGABLE view. For example, if a B_NAVIGABLE_JUMP parent view is not navigible itself but has navigible children, Control+Tab focusses on the first B_NAVIGABLE child.

When the user navigates to a view, the BView needs to draw some sort of visual indication that it's the current focus for keyboard actions. Be-defined views underline text (for example, a button label) when the view is in focus, or draw a rectangular outline of the view. The underline and outline are drawn in the color returned by keyboard_navigation_color(). Using this color lends consistency to the user interface.

A BView learns that the focus has changed when its MakeFocus() hook function is called. It's up to MakeFocus() to ensure that the focus indicator is drawn or erased, depending on the BView's new status. It's usually simplest for MakeFocus() to call Draw() and have it do the work. For example:

void MyView::MakeFocus(bool focused)
{
   if ( focused != IsFocus() ) {
      baseClass::MakeFocus(focused);
      Draw(Bounds());
      Flush();
      . . .
   }
}

The BControl class has a MakeFocus() function that calls Draw(), so if your class derives from BControl, all you need to do is implement Draw(). Draw() can call IsFocus() to test the BView's current status. Here's a rough example:

void MyView::Draw(BRect updateRect)
{
   rgb_color navigationColor = keyboard_navigation_color();
   BRect r = Bounds()
   r.InsetBy(2.0, 2.0)
   . . .
   rgb_color c = HighColor();
   if ( IsFocus() ) {
      /* draw the indicator */
      SetHighColor(navigationColor);
      StrokeRect(r);
      SetHighColor(c);
   }
   else {
      /* erase the indicator */
      SetHighColor(ViewColor());
      StrokeRect(r);
      SetHighColor(c);
   }
   . . .
}

Finally, your BView may need to override KeyDown() to handle the keystrokes that are used to operate the view (for view-internal navigation). Always incorporate the inherited version of KeyDown() so that it can take care of navigation between views. For example:

void MyView::KeyDown(const char *bytes, int32 numBytes)
{
   switch ( bytes[0] ) {
      case B_ENTER:
      case B_SPACE:
            /* take action */
            break;
      case B_UP_ARROW:
      case B_DOWN_ARROW:
      case B_RIGHT_ARROW:
      case B_LEFT_ARROW:
            /* move within the view */
            break;
      default:
            baseClass::KeyDown(bytes, numBytes);
            break;
   }
}

Again, the BControl class implements a KeyDown() function that invokes the control device when the user presses the space bar or Enter key. If your class derives from BControl and it doesn't have to do any other view-internal navigation, the BControl function may be adequate for your needs.

The BView class supports a drag-and-drop user interface. The user can transfer a parcel of information from one place to another by dragging an image from a source view and dropping it on a destination view—perhaps a view in a different window in a different application.

A source BView initiates dragging by calling DragMessage() from within its MouseDown() function. The BView bundles all information relevant to the dragging session into a BMessage object and passes it to DragMessage(). It also passes an image or a rectangle to represent the data package on-screen. For example:

void MyView::MouseDown(BPoint point)
{
   . . .
   if ( aRect.Contains(point) ) {
      BMessage message(SOME_WORDS_OF_ENCOURAGEMENT);
      message.AddString("words", theEncouragingWords);
      DragMessage(&message, aRect);
   }
   . . .
}

The Application Server then takes charge of the BMessage object and animates the image as the user drags it on-screen. As the image moves across the screen, the views it passes over are informed with MouseMoved() function calls. These notifications give views a chance to show the user whether or not they're willing to accept the message being dragged. When the user releases the mouse button, dropping the dragged message, the message is delivered to the BWindow and targeted to the destination BView.

A BView is notified that a message has arrived by a MessageReceived() function call. This is the same function that announces the arrival of other messages. By calling WasDropped(), you can ask the message whether it was dropped on the view or delivered in some other way. If it was dropped, you can find out where by calling DropPoint(). For example:

void AnotherView::MessageReceived(BMessage *message)
{
   switch ( message->what ) {
      . . .
      case SOME_WORDS_OF_ENCOURAGEMENT:
      {
            char *words;
            if ( message->FindString("words", &words) != B_OK )
               return;
            if ( message->WasDropped() ) {
               BPoint where = DropPoint();
               ConvertFromScreen(&where);
               PleaseInsertTheseWords(words, where);
            }
            break;
      }
      . . .
      default:
            baseClass::MessageReceived(message);
   }
}

Aside from creating a BMessage object and passing it to DragMessage(), or implementing MouseMoved() and MessageReceived() functions to handle any messages that come its way, there's nothing an application needs to do to support a drag-and-drop user interface. The bulk of the work is done by the Application Server and Interface Kit.