Creating a custom widget

For creating its graphical user interface, Synfig Studio uses gtkmm, the official C++ binding for the Gtk. This toolkit provides a lot of widgets, but sometimes they don’t exactly fulfill our needs. In those situations, we have/opt to create our custom widgets, and that’s what this page is about.

For creating custom gtkmm widgets, first be sure you properly understand gtkmm. You can study it by reading its official documentation. They do explain how to create custom widgets and custom signals. Of course, they have their API reference, split in the Gtk modules. Sometimes, however, it may be somehow… lacking. You can always check the Gtk docs, instead of gtkmm’s, to check some confusing info. Both API reference are also available on Linux via devhelp app.


  • the class should be named Widget_* Examples: Widget_Link, Widget_Timetrack.

  • its files should be placed in synfig-studio/gui/widgets folder

  • if a file contains translatable text, it should be mentioned in synfig-studio/po/

  • signal slots (event callbacks) should be named like on_[signal_name] or on_[child_widget_name]_[signal_name]

  • the user-interaction callbacks, like on_key_press_event() and on_draw(), if used, should catch all exceptions, specially if there is any of synfig:: or synfigapp:: API call in the method implementation, even indirectly. It should be done by macros SYNFIG_EXCEPTION_GUARD_*

  • it should support Gtk::Builder and be available for Glade

  • it should have properties defined via Glib::Property (for better support for Glade editor)

  • if it’s a widget that uses time as horizontal axis, like for Widget_SoundWave, Widget_Timetrack and Widget_Curves, it could use Widget_TimeGraphBase as a parent class, for useful methods.

  • please document it :P