Home > Programmer's Guide > More About Programming > Adding Program Functionality
One handed Navigation
Most devices now come with a 5-way navigator that permits to move a focus ring among the controls of a form. This section describes how to access this feature using the HB++ runtime library.
Navigation Modes
Depending on the context, the 5-way keys may trigger different actions. For exemple, the up and down buttons normally move the focus ring, but they can also be used to select an item in a focused list, or they can scroll a text area. There are also devices having a 5-way navigator but that do not support the focus ring feature; in such a case, it is up to the programmer to assign (or not) a function to these keys.
To handle this wide variety of situations, each form has a NavState property that define how 5-way events should be processed, as described below:
| Value | Description |
| hbNavStateApplication | The navigation is disabled. 5-way events are directed to the form, and it is up to the programmer to handle these events if needed to perform some default action, such as scrolling text or moving a selection cursor. This mode is the only one available on devices that do not support the one-handed navigation feature. |
| hbNavStateObject | The navigation is enabled and the 5-way keys are used for navigation. 5-way events are directed to the focused control, not to the form. |
| hbNavStateInteraction | The 5-way keys interact with a particular object rather than move the focus. For example, a List control is in interaction mode when the 5-way keys move a highlight through the list items. 5-way events are directed to the focused control, not to the form, and the programmer must provide a handler to implement how the control should interact with the 5-way keys. |
Appart from special cases, the system never changes the navigation mode of a form by itself. Notably, if you are implementing a user control, you are responsible for switching to interaction mode when required.
Navigation Order
By default, to ensure compatibility with previous devices, navigation is disabled. To enable it, you have to associate a navigation map with each form of your application, that define what UI objects are included in the navigation order, what the tab order is, what the vertical order is, whether the focus is initially on or off, where the focus begins, where the focus can move, and what the bottom-left object is (the bottom-left object information is needed to cycle the focus from the top of the form). Maps are stored in resources whose type is "fnav" in the executable file.
To define a navigation map for a form, simply fill the NavOrder, Above and Below properties for each of its control. Together, these properties define where to move the focus from a given control when the user presses one of the 5-way keys. You'll also have to set the NavState property of the form to hbNavStateObject to switch the focus initially on.
For most forms, defining a navigation map can be easily done by using the "Layout > Navigation Order > Default Order" command. This will automatically compute an horizontal and vertical navigation order based on the controls positions, and fill all the navigation related properties accordingly. However, the algorithm used may not work for some very specific dialog boxes; should the occasion arise, you can alter this automatically generated map so that it suits your needs.
The navigation map can be tested at design time by calling the "Layout > Navigation Order > Test" command. This is just a simulation though, the behavior on an actual device may differ slightly.
Putting All Together
In most cases, you won't have to write a single line of code to add one-handed navigation features to your application. Simply generating a navigation map for each form will be sufficient. Actually, implementing event handlers will only be required in the following situations:
Of course, the various methods described in the links above can be combined if required. In any case, it is a good practice to check how one-handed navigation behaves in built-in applications before implementing your own scheme. An unusual navigation order or a mapping of the 5-way keys that is not consistent accross the various forms of your application may produce bad user experiences.