This function should be called whenever keyboard navigation within a single widget hits a boundary. The function emits the keynav-failed signal on the widget and its return value should be interpreted in a way similar to the return value of Widget.childFocus:
When TRUE is returned, stay in the widget, the failed keyboard navigation is OK and/or there is nowhere we can/should move the focus to.
When FALSE is returned, the caller should continue with keyboard navigation outside the widget, e.g. by calling Widget.childFocus on the widget’s toplevel.
The default ::keynav-failed handler returns FALSE for GTK_DIR_TAB_FORWARD and GTK_DIR_TAB_BACKWARD. For the other values of GtkDirectionType it returns TRUE.
Whenever the default handler returns TRUE, it also calls Widget.errorBell to notify the user of the failed keyboard navigation.
A use case for providing an own implementation of ::keynav-failed (either by connecting to it or by overriding it) would be a row of gtk.Entry widgets where the user should be able to navigate the entire row with the cursor keys, as e.g. known from user interfaces that require entering license keys.