diff options
Diffstat (limited to 'navit/graphics.c')
| -rw-r--r-- | navit/graphics.c | 62 |
1 files changed, 58 insertions, 4 deletions
diff --git a/navit/graphics.c b/navit/graphics.c index 829acd1b8..5c6f9e5b3 100644 --- a/navit/graphics.c +++ b/navit/graphics.c @@ -1074,22 +1074,76 @@ graphics_background_gc(struct graphics *this_, struct graphics_gc *gc) /** * @brief Shows the native on-screen keyboard or other input method * - * This method is just a wrapper which calls the respective method of the graphics plugin. + * This method is a wrapper around the respective method of the graphics plugin. + * + * The caller should populate the {@code kbd} argument with appropriate {@code mode} and {@code lang} + * members so the graphics plugin can determine the best matching layout. + * + * If an input method is shown, the graphics plugin should try to select the configuration which best + * matches the specified {@code mode}. For example, if {@code mode} specifies a numeric layout, the + * graphics plugin should select a numeric keyboard layout (if available), or the equivalent for another + * input method (such as setting stroke recognition to identify strokes as numbers). Likewise, when an + * alphanumeric-uppercase mode is requested, it should switch to uppercase input. + * + * Implementations should, however, consider that Navit's internal keyboard allows the user to switch + * modes at will (the only exception being degree mode) and thus must not "lock" the user into a limited + * layout with no means to switch to a general-purpose one. For example, house number entry in an + * address search dialog may default to numeric mode, but since some house numbers may contain + * non-numeric characters, a pure numeric keyboard is suitable only if the user has the option to switch + * to an alphanumeric layout. + * + * When multiple alphanumeric layouts are available, the graphics plugin should use the {@code lang} + * argument to determine the best layout. + * + * When selecting an input method, preference should always be given to the default or last selected + * input method and configuration if it matches the requested {@code mode} and {@code lang}. + * + * If the native input method is going to obstruct parts of Navit's UI, the graphics plugin should set + * {@code kbd->w} and {@code kbd->h} to the height and width to the appropriate value in pixels. A value + * of -1 indicates that the input method fills the entire available width or height of the space + * available to Navit. On windowed platforms, where the on-screen input method and Navit's window may be + * moved relative to each other as needed and can be displayed alongside each other, the graphics plugin + * should report 0 for both dimensions. + * + * @param this_ The graphics instance + * @param kbd The keyboard instance * * @return 1 if the native keyboard is going to be displayed, 0 if not, -1 if the method is not * supported by the plugin */ int graphics_show_native_keyboard (struct graphics *this_, struct graphics_keyboard *kbd) { + int ret; if (!this_->meth.show_native_keyboard) - return -1; - return this_->meth.show_native_keyboard(kbd); + ret = -1; + else + ret = this_->meth.show_native_keyboard(kbd); + dbg(lvl_debug, "return %d\n", ret); + return ret; } /** * @brief Hides the native on-screen keyboard or other input method * - * This method is just a wrapper which calls the respective method of the graphics plugin. + * This method is a wrapper around the respective method of the graphics plugin. + * + * A call to this function indicates that Navit no longer needs the input method and is about to reclaim + * any screen real estate it may have previously reserved for the input method. + * + * On platforms that don't support overlapping windows this means that the on-screen input method should + * be hidden, as it may otherwise obstruct parts of Navit's UI. + * + * On windowed platforms, where on-screen input methods can be displayed alongside Navit or moved around + * as needed, the graphics driver should instead notify the on-screen method that it is no longer + * expecting user input, allowing the input method to take the appropriate action. + * + * The graphics plugin must free any data it has stored in {@code kbd->gra_priv} and reset the pointer + * to {@code NULL} to indicate it has done so. + * + * The caller may free {@code kbd} after this function returns. + * + * @param this The graphics instance + * @param kbd The keyboard instance * * @return True if the call was successfully passed to the plugin, false if the method is not supported * by the plugin |