callbacks.md

Callbacks Handlers

• Signal connections should be done using GtkBuilder/Glade where possible. If you're moving any manual GUI building code to the GtkBuilder file, you should ensure to move the signal connections there where possible (ex. where you don't need special user_data that cannot be set through Glade).

• If you're making a callback handler for any non-GtkBuilder-related signals place the handler nearby (ex. directly above) the function that uses it. For signal handlers connected using GtkBuilder that don't relate specifically to any existing code, place the handler functions in callbacks.c. If they are remotely related to the code in some file, but no particular function(s), place them together in a section of the relevant source file.

• Callback handlers should not contain complex logic or lots of code at all. Generally a callback handler will contain no more than a single function call to the actual function that performs the needed actions.

• Never call a callback handler explicitly in code. If you need this same functionality in other parts of the code, it's a clear indication that the handler contains too much code. Factor the common code out into a separate function and call it from the handler and wherever else needs to.

• Never add "public" declarations to any headers for callback handlers, this should never be needed if the other guidelines are followed, although there exists many such declarations in callbacks.h due to legacy use of Glade2.

• Callback handlers should be named like this:

    on_ [widget name] _ [signal_name]
  

  Regardless if their related to GtkBuilder at all, just for consistency and to make it easier to find/navigate the functions. Some examples are:

    Widget Name    Signal Name          Handler Name
    ===========    ===========          ============
    menuitem1      activate             on_menuitem1_activate
    BlahBlah       clicked              on_BlahBlah_clicked
    some-other     destroy              on_some_other_destroy
  

  This makes it easy to find handlers in the code based on widget names and also makes it very clear which signal is being handled by just looking at the function name.

• If a signal is connected using GtkBuilder/Glade, make sure the signal handler function contains a "G_MODULE_EXPORT" to ensure that the symbol will be exported and visible when GtkBuilder scans the module for symbols to connect to. Forgetting this will almost surely cause the signal handler not to be found/work on Windows.

• Don't use G_MODULE_EXPORT on any signal handlers that aren't connected using GtkBuilder as this needlessly exports private symbols on some platforms. All callback handlers that are connected directly in code should be static functions, local the relevant source file.

I don't mean to don't use the handler (ie. connect to it) many times, I mean don't call it directly. I just search in Geany for "on_motion_event" and this function is connected to many times, but it's never called explicitly, and it's contents are completely trivial. For an example of what I mean (and that breaks most of the guidelines above), see "on_exit_clicked".

I was referring to this point:

• Never add "public" declarations to any headers for callback handlers, this should never be needed if the other guidelines are followed, although there exists many such declarations in callbacks.h due to legacy use of Glade2.

Ah, my bad, I was thinking mostly of connections by Glade in the original wording of that...which still sort of applies here because in all uses of on_motion_event except maybe in vte.c, the manual GUI building code should probably be moved into GtkBuilder file along with signal connections :) but yeah, in such cases of manual C code that hasn't yet been or won't be ported to Glade, it'd be useful to add a declaration to a header.

P.S. I'll never use Gist again for this, it sucks :)

make a Github issue :)