GNOME Bugzilla – Bug 767702
The highlight-updated signal is confusing
Last modified: 2016-10-20 13:29:08 UTC
The GtkSourceBuffer::highlight-updated signal has a bad name. It would be nice to meditate about it to find a better name, or have several more specialized signals (maybe some private). See commit 2c56dc3f2e68f8aed6a02c3bd5e6485e082a22c2 for one reason why this signal has a bad name. Also, applications or higher-level libraries are using the signal for the update wrt the context classes, not the syntax highlighting. So it looks like a grab-bag signal. A good time to fix this bug is for GtkSourceView 4, but it is also possible to create new signals and deprecate ::highlight-updated. To create a private signal, a GtkSourceBufferExtension private class could be created, to extend GtkSourceBuffer without subclassing it, the same way as GspellTextBuffer: https://git.gnome.org/browse/gspell/tree/gspell/gspell-text-buffer.c?h=1.0.0#n154
To create a private GtkSourceBuffer signal, there is now the GtkSourceBufferInternal class, see bug #742550 where the search-start signal has been added for the GtkSourceSearchContext.
After more reflections, I think it's ok to keep the signal as is. The signal is emitted when the syntax highlighting engine has updated a region of the buffer. And the syntax highlighting engine includes context classes, it is already documented in the GtkSourceBuffer class description. So API-wise, I think it's good enough. I'm not sure that the signal is useful for the *syntax*, I think external code needs to be notified only about context class changes. But the two come together (currently). As said above, in the future another signal can be added and highlight-updated can be deprecated, it doesn't need an API break normally. And I currently don't know well the internals of GtkSourceContextEngine. For GtkSourceView 5 maybe. -> close the bug.