libglade to GtkBuilder transition

As of GNOME 3.0, libglade will be deprecated in favor of GtkBuilder. F-Spot still has quite a few glade dialogs, which need to be converted. Fortunately, this is not a very hard task and you can help out if you want. As always, the F-Spot developers are there to help you when you are stuck (either through bugzilla, the mailing list or IRC).

You can find the list of open GtkBuilder conversion tasks here: GtkBuilder transition bugs. All bugs are marked with [GtkBuilder transition]. Add a comment to the bug you want to work on so we can assign it to you, this avoids duplicate work. Also let us know if you are no longer working on it, then we can assign it to someone else. Please don't go crazy and do everything in one afternoon, this is mostly aimed at inviting new people, so one bug per person please! There are plenty of other F-Spot bugs that need fixing if you are looking for a challenge :-).

Before we start

You will need a fully built F-Spot from git. Information on how to do this is available on this page. Make sure you can build and test it. You will also need to install glade-3.

Step 1: Extract the dialog

Note: Ignore this step if you are working on converting an extension

Each bug contains the name of the dialog. The first thing you need to do is to extract that dialog out of the main f-spot.glade file. Open up your text editor and open f-spot.glade. This is an enormous XML file, so use the search function or your text editor to find the name of your dialog. You will see a line like this one (the line below is for the version_name_dialog widget):

 <widget class="GtkDialog" id="version_name_dialog">

Start copying from that line on (including that line), all the way down to the matching </widget> tag. Look at the indentation to find the matching tag.

Then open up a new file called tmp.glade and paste the blob of XML you just copied in there. Put the following fragment above the pasted code:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE glade-interface SYSTEM "glade-2.0.dtd">

<!--*- mode: xml -*-->
<glade-interface>
  <requires lib="canvas"/>
  <requires lib="gnome"/>

And put the following fragment below it:

 </glade-interface>

Save and close! We have now extracted the widget from f-spot.glade. Now open f-spot.glade using glade-3 f-spot.glade, look for the right widget in the top-right selector and see what it looks like (warning: it may look pretty bad, we will fix that later on). Then open your newly created tmp.glade, it should look the same.

Looks the same? you can now delete the widget from f-spot.glade (again, use your text editor or the whole file will be changed). Let's continue!

Step 2: From .glade to .ui

Open your new tmp.glade using glade-3.

Go to Edit -> Preferences and select toolkit version 2.12. Then click the execute button to verify for versions and deprecations. This should not give problems, if it does: talk to us, we'll probably need to fix some out-dated widgets. Generally, there should not be any problems though. Close preferences.

Go to File -> Save as and save your file into the src/ui/ folder, in GtkBuilder format. Name it with a .ui extension, e.g.: version_name_dialog.ui.

Intermezzo: My widget looks really bad!

Glade seems to have a bug where widgets look really bad: everything is placed on one long row. This is easy to fix: go through the widget tree (top-right) and look for all vboxes (the icon looks like three stacked rectangles). For each of those, change Orientation to Vertical in the properties area (bottom-right). Should look much better now.

Adding it to the build

Open src/Makefile.am and look for the RESOURCES section. Add your .ui file there. Be sure to use a tab at the beginning of a line (not spaces, copy the line above and adjust if you want to be sure), otherwise automake won't work anymore.

Step 3: Converting the code from libglade to GtkBuilder

We also need to migrate the code to use GtkBuilder. First you will need to find the right class to modify. This can be done by a simple grep:

 git grep version_name_dialog

This will lead you to the right class. In this case, it is VersionNameRequest in PhotoVersionCommands.cs.

You will notice that the class you found is a subclass of GladeDialog. Change this to BuilderDialog. If you compile now, there will be a warning that BuilderDialog has no constructor that takes one parameter. You will need to add the name of the .ui file as a parameter. Fix it like this:

 OLD: public VersionNameRequest (...) : base ("version_name_dialog")
 NEW: public VersionNameRequest (...) : base ("version_name_dialog.ui", "version_name_dialog")

Compile again and you might notice warnings such as:

 ./PhotoVersionCommands.cs(59,38): error CS1061: Type `PhotoVersionCommands.VersionNameRequest'
      does not contain a definition for `Dialog' and no extension method `Dialog' of type
      `PhotoVersionCommands.VersionNameRequest' could be found (are you missing a using
      directive or an assembly reference?)

Here we simply need to remove the Dialog. bits (this is a change in behavior between GladeDialog and BuilderDialog).

 OLD: this.Dialog.Title = Catalog.GetString ("Create New Version");
 NEW: this.Title = Catalog.GetString ("Create New Version");

The last step is replacing the [Glade.Widget] attributes by [GtkBeans.Builder.Object].

 OLD: [Glade.Widget] private Button ok_button;
 NEW: [GtkBeans.Builder.Object] private Button ok_button;

Step 4: Test!

All done! Everything should compile now (if not, let me know). Start your freshly built F-Spot and test if everything still works.

Step 5: Submit your work

Time to make a patch. Look at the output of git status:

$ git status
# On branch master
# Changed but not updated:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#	modified:   src/Makefile.am
#	modified:   src/PhotoVersionCommands.cs
#	modified:   src/f-spot.glade
#
# Untracked files:
#   (use "git add <file>..." to include in what will be committed)
#
#	src/tmp.glade
#	src/ui/version_name_dialog.ui
no changes added to commit (use "git add" and/or "git commit -a")

First thing to notice: tmp.glade is still there. Delete it. Then add the new .ui to git:

 git add src/ui/version_name_dialog.ui

Create a new branch for your work:

$ git checkout -b gtkbuilder
M	src/Makefile.am
M	src/PhotoVersionCommands.cs
M	src/f-spot.glade
A	src/ui/version_name_dialog.ui
Switched to a new branch 'gtkbuilder'

Then commit using git commit -a. Write a short one line summary on the first line, leave a blank line and write more information on the lines below, if needed.

Create a patch:

 git format-patch master..

And attach the created .patch file to the bug! It's that simple.

To switch back to the master branch, use git checkout master. Your code is still in your own branch (suppose you need it later to adjust some things), but you can also use git pull --rebase and test master without having to worry about clashes between your work and the work others do.

For more info about git, I recommend Git from the bottom up.

Thanks for your work! You just made F-Spot slightly more awesome and ready for GNOME 3.0!

Stuck?

Stuck? Not sure how to do something? We are there to help, just ask us through the mailing list or IRC.

© F-Spot Contributors - 2005 - 2017