This function is used by custom widget implementations; if you're writing an app, you’d use Widget.grabFocus to move the focus to a particular widget, and Container.setFocusChain to change the focus tab order. So you may want to investigate those functions instead.
Widget.childFocus is called by containers as the user moves around the window using keyboard shortcuts. direction indicates what kind of motion is taking place (up, down, left, right, tab forward, tab backward). Widget.childFocus emits the focus signal; widgets override the default handler for this signal in order to implement appropriate focus behavior.
The default ::focus handler for a widget should return TRUE if moving in direction left the focus on a focusable location inside that widget, and FALSE if moving in direction moved the focus outside the widget. If returning TRUE, widgets normally call Widget.grabFocus to place the focus accordingly; if returning FALSE, they don’t modify the current focus location.