Gtk.stock is deprecated, what's the alternative?

Question

I've been learning to develop to Gtk and most of the examples online suggests the use of Gtk.stock icons. However, its use produces warnings that it has been deprecated and I can't find the alternative to these icons.

Code examples are:

    open_button:Gtk.ToolButton = new ToolButton.from_stock(Stock.OPEN)
    open_button.clicked.connect (openfile)

    new_button:Gtk.ToolButton = new ToolButton.from_stock(Stock.NEW)
    new_button.clicked.connect (createNew)

    save_button:Gtk.ToolButton = new ToolButton.from_stock(Stock.SAVE)
    save_button.clicked.connect (saveFile)

That generates error as:

   /tmp/text_editor-exercise_7_1.vala.c:258:2: warning: 'GtkStock' is deprecated [-Wdeprecated-declarations]
     _tmp1_ = (GtkToolButton*) gtk_tool_button_new_from_stock (GTK_STOCK_OPEN);

Which is the alternative and how it would look in the code above?

Answer 1

GTK+3 has moved over to the freedesktop.org Icon Naming Specification and internationalised labels. Taking Gtk.Stock.OPEN as an example. The GNOME Developer documentation for GTK_STOCK_OPEN gives two replacements:

GTK_STOCK_OPEN has been deprecated since version 3.10 and should not be used in newly-written code. Use named icon "document-open" or the label "_Open".

The Named Icon Method

The named icon method would be something like:

var open_icon = new Gtk.Image.from_icon_name( "document-open",
                                              IconSize.SMALL_TOOLBAR
                                              )
var open_button = new Gtk.ToolButton( open_icon, null )

The Label Method

The label method makes use of gettext to translate the label in to the current runtime language of the program. This is indicated by the underscore before the label. The line in your program would be:

var open_button = new Gtk.ToolButton( null, dgettext( "gtk30", "_Open") )

gettext uses domains, which are files containing the translations. The Gtk+3 domain is gtk30. You will also need to add a line at the beginning of your program to change the default locale for the C language, which is US English ASCII, to the locale of the run time environment:

init
    Intl.setlocale()

To compile the Genie program you will need to set the default domain for gettext. This is usually set to nothing:

valac -X -DGETTEXT_PACKAGE --pkg gtk+-3.0 my_program.gs

When you run your program you will get the "_Open" translated to your locale. You can also change the locale. If you have the French locale installed then running the program with:

LC_ALL=fr ./my_program

will have the "_Open" label appear in French.

You may see in examples _( "_OPEN" ). The _() is a function like dgettext but uses a default domain. You may want to keep the default domain to the translation file for your own program. Using _( "_translate me" ) is a bit less typing that dgettext( "mydomain", "_translate me" ). To set the default domain in Genie add a line before init:

const GETTEXT_PACKAGE:string = "mydomain"

init
    Intl.setlocale()