Missing migration-critical docs for GtkWidget "focus" signal
I have an application which has been calling
gtk_container_set_focus_chain. It was reported to me yesterday that this now generates a deprecation warning in GTK 3.24.
So I looked up
gtk_container_set_focus_chain in the manual, and indeed, I found a deprecation notice that says
For overriding focus behavior, use the GtkWidgetClass::focus signal.
That's not obvious by itself, of course – if I was previously calling a function, and now I have to handle a signal, clearly I need some further explanation. So I go to the
GtkWidget docs page and look up the
"focus" signal (by hand, because that deprecation notice didn't have a hyperlink).
The docs for the
"focus" signal, in full, say this:
gboolean user_function (GtkWidget *widget, GtkDirectionType direction, gpointer user_data)
widget: the object which received the signal.
user_data: user data set when the signal handler was connected.
TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.
Flags: Run Last
Not a hint there of what the signal is for. Under what circumstances is it generated? What might an application be expected to do about it? The only clue at all is the
GtkDirectionType parameter, and that's not even listed in the Parameters section of this description. How does this help me at all to figure out how I should be using this signal to replace what I was previously doing with
Eventually I source-dived in the GTK library code. After a few false starts I discovered that
GtkContainer's implementation of that signal first does some thinking and then calls
gtk_widget_child_focus. So I went back to the docs and looked up that function, and there I find all the information I wanted – except that the docs for
gtk_widget_child_focus also seem not to have got the memo about
gtk_container_set_focus_chain being deprecated: (my emphasis)
if you're writing an app, you’d use
gtk_widget_grab_focus()to move the focus to a particular widget, and
gtk_container_set_focus_chain()to change the focus tab order. So you may want to investigate those functions instead.
So even there things are a bit confused, but at least I think I've more or less got the general idea now. But I should not have had to go and read the library source code to fill in that missing link! (Insert obligatory Douglas Adams quotation. "That's the display department.")
"focus" signal is where people will be directed by the deprecation request for
gtk_container_set_focus_chain, then it ought to have some actual text in there. At the very least, it could cross-reference to
gtk_widget_child_focus where the useful information will actually be found.
I think that at minimum the
"focus" signal's docs ought to say
- that the signal is generated in response to keyboard shortcuts that the user will expect to move the focus in a particular direction
- that the expected response to the signal is to call
gtk_widget_child_focus, or possibly
gtk_widget_grab_focus(and when to use which? Does it depend on whether you're the custom widget implementation or a user overriding the signal for a particular instance of the widget?)
- that a
TRUEreturn value means that you've successfully moved the focus to a focusable location inside your widget, and
FALSEif you think this UI action should leave the focus somewhere outside your widget. (That should surely replace the generic and unclear description of those return values in the current
- include a cross-reference to
gtk_widget_child_focuswhere the rest of the information is found.
This ought to be a general principle: if a function is marked as deprecated, then it should be possible to follow links from the deprecation notice in the documentation to find out everything you need to know about what you should be doing instead of calling that function. This isn't actually the first time I've found myself source-diving in GTK to figure out how to cope with a deprecation, but it's the most egregious so far.