From Guichan

Focus

Focus is in Guichan applied synchronously. That means that whenever a focus change is requested it will either by rejected immediately or applied immediately. A widget is automatically focused if pressed with the mouse. The widget with focus is the widget that receives user keyboard input (along with the widget's parents, see Events). A widget can request focus with the Widget::requestFocus function.

Widget* widget;

void foo()
{
    widget->setFocusable(true);
}

void bar()
{
    widget->requestFocus();
}

Focus will only be granted to a widget if it is focusable and if no other widget has modal focus. A non focusable widget can never receive focus. If focus is granted to a widget, the widget will be focused when the Widget::requestFocus function returns. To focus no widget in the Gui the Gui::focusNone is used:

gui->focusNone();

Modal focus

If a widget has modal focus, no other widgets will receive focus or events. A widget can request modal focus with the Widget::requestModalFocus function.

Widget* widget;

void foo()
{
    widget->setFocusable(true);
}

void bar()
{
    widget->requestModalFocus();
}

Modal focus will only be granted to a widget if it is focusable and if no other widget has modal focus. If a container has modal focus, the children widgets of the container will still be able to receive focus and events. Only the widget with modal focus can release modal focus. A widget releases modal focus with the Widget::releaseModalFocus function.

gcn::Widget* widget;

void foo()
{
    widget->releaseModalFocus();
}

Tabbing

In Guichan tabbing is enabled by default. It let's the user change focus to the next added widget to the GUI by using the tab button. To change focus in the opposite direction shift and tab can be used. Tabbing can be disabled with the Gui::setTabbingEnabled function.

gcn::Gui* gui;

void foo()
{
    gui->setTabbingEnabled(false);
}

A widget can control if tabbing to the widget is enabled or if tabbing out of the widget is enabled with the Widget::setTabEnabled and Widget::setTabOutEnabled functions. A typical example of a widget where tabbing out is not enabled is a text area widget where the tab should print a tab character in the text area and not focus the next widget.

 
gcn::Widget* widget;

void foo()
{
    widget->setTabOutEnabled(false);
}

FocusHandler

Focus in Guichan is handled by a FocusHandler object. Each Gui object has it's own FocusHandler. When a widget is added to the Gui objec,t the Gui object's FocusHandler is passed to the widget. When a widget is added using the Gui::setTop method, Gui is responsible for passing the FocusHandler to the widget, when a widget is added using a container functions - such as Container::add - the container is responsible for passing the FocusHandler to the widget. End users normally don't have to bother with the FocusHandler as it's used by the classes Gui and Widget.