"Fossies" - the Fresh Open Source Software Archive

Member "gimp-2.10.28/devel-docs/gtkbuilder-porting-guide.txt" (14 Sep 2021, 3890 Bytes) of package /linux/misc/gimp-2.10.28.tar.bz2:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 gtkbuilder-porting-guide.txt
    2 ============================
    3 
    4 This document describes some tips and rules for porting UI code
    5 written with GTK+ and C to GtkBuilder + Glade.
    6 
    7 
    8 
    9 Overview
   10 --------
   11 
   12 1. Locate code to port
   13 2. Start a new UI file with Glade
   14 3. Systematically convert the code to Glade
   15 4. Construct UI with GtkBuilder and do setup of widgets
   16 5. Add .ui file to build system
   17 6. Test
   18 7. Enjoy less UI C code
   19 8. Troubleshooting
   20 
   21 
   22 
   23 Locate code to port
   24 -------------------
   25 
   26 Look for code that looks like this:
   27 
   28   // Create a widget and add to hierarchy
   29   widget = gtk_some_widget_new (some_params);
   30   gtk_some_container_add (container, widget)
   31   gtk_widget_show (widget);
   32 
   33   // Repeat...
   34 
   35 
   36 
   37 Start a new UI file with Glade
   38 ------------------------------
   39 
   40 Start glade-3. Pick project file format 'GtkBuilder' (not
   41 'Libglade'). For maximum compatibility, use the minimal gtk+ catalog
   42 possible. The file extension shall be .ui. Look where other files are
   43 put and how they are named.
   44 
   45 
   46 
   47 Systematically convert the code to Glade
   48 ----------------------------------------
   49 
   50 Go through the code that you want to convert line by line and add
   51 widgets in Glade as you remove lines. For example:
   52 
   53   main_vbox = gtk_vbox_new (FALSE, 12);
   54   gtk_container_set_border_width (GTK_CONTAINER (main_vbox), 12);
   55   gtk_container_add (GTK_CONTAINER (dialog_vbox),
   56                      main_vbox);
   57   gtk_widget_show (main_vbox);
   58 
   59 is replaced by
   60 
   61   <object class="GtkVBox" id="main-vbox">
   62     <property name="visible">True</property>
   63     <property name="border_width">12</property>
   64     <property name="orientation">vertical</property>
   65     <property name="spacing">12</property>
   66     <child>
   67       <!-- ... -->
   68     </child>
   69   </object>
   70 
   71 in the UI declaration produced by Glade.
   72 
   73 
   74 
   75 Construct UI with GtkBuilder and do setup of widgets
   76 ----------------------------------------------------
   77 
   78 The code to construct the UI will look something like this:
   79 
   80   builder = gtk_builder_new ();
   81   ui_file = g_build_filename (gimp_data_directory (),
   82                               "ui/plug-ins/plug-in-file-gif-save.ui",
   83                               NULL);
   84   if (! gtk_builder_add_from_file (builder, ui_file, &error))
   85     g_printerr (_("Error loading UI file '%s':\n%s"),
   86                 ui_file, error ? error->message : "???");
   87   g_free (ui_file);
   88 
   89 and then you do setup of widgets using:
   90 
   91   widget = GTK_WIDGET (gtk_builder_get_object (builder, "widget-name"));
   92   gtk_widget_whatever (widget, params);
   93 
   94 Look in plug-ins/common/file-gif-save.c for helper function you can
   95 use for some tricky widgets.
   96 
   97 
   98 
   99 Add .ui file to build system
  100 ----------------------------
  101 
  102 The UI declarations are installed as data files, see
  103 plug-ins/ui/Makefile.am for example, and it needs to be added to
  104 POTFILES.in for translations.
  105 
  106 
  107 
  108 Test
  109 ----
  110 
  111 When you're done, make sure
  112 
  113 1. that translations still work. If they don't, maybe you forgot to
  114 add the UI file to the relevant POTFILES.in or maybe you changed
  115 strings, for example by adding markup. In the latter case, use pango
  116 text styles instead of markup (use GKT+ 2.16 UI files).
  117 
  118 2. that mnemonics still work, in particular when the mnemonic is not
  119 on the widget to be activated. For e.g. labels you need to explicitly
  120 assign a widget that will be actiated when the label mnemonic is
  121 pressed.
  122 
  123 3. that the spacing and other layout detals are still correct.
  124 
  125 
  126 
  127 Enjoy less UI C code
  128 --------------------
  129 
  130 Enjoy!
  131 
  132 
  133 
  134 Troubleshooting
  135 ---------------
  136 
  137 If your GtkComboBox doesn't draw any items it's probably because it
  138 doesn't have a cell renderer. Apparently there is no UI to add one in
  139 GLade-3, so add it manually in the UI file, see the GTK+ doc for
  140 GtkCellLayout; this is what you need to add:
  141 
  142 <object class="GtkComboBox" name="some-id">
  143   ...
  144   <child>
  145     <object class="GtkCellRendererText"/>
  146     <attributes>
  147       <attribute name="text">0</attribute>
  148     </attributes>
  149   </child>
  150 </object>