Why isn't my toolitem's proxy menu item being used?

Question

I want to show a custom menu item for a ToolItem when it is in the toolbar's overflow menu. This seems to be the purpose of the set_proxy_menu_item method. However, when I set the proxy menu item via using this method, it has no effect on the overflow menu. It still uses the default menu item (with the ToolItem's name as the label).

Here is a simple project (in Vala) that reproduces the problem. It creates a tiny window containing a toolbar with 3 buttons. The window should be small enough that all but one of these buttons is in the overflow menu.

When I view the overflow menu, I should see "proxy" for as the menu item for edit_button. Instead, I see "edit".

What am I doing wrong?

void main(string[] args) {
    Gtk.init(ref args);
    MainWindow main_window = new MainWindow();
    main_window.show_all();
    Gtk.main();
}

public class MainWindow : Gtk.Window {
    public MainWindow() {
        destroy.connect(Gtk.main_quit);
        title = "Main Window";

        Gtk.Box main_box = new Gtk.Box(Gtk.Orientation.VERTICAL, 6);
        add(main_box);

        Gtk.Toolbar toolbar = new Gtk.Toolbar();
        main_box.pack_start(toolbar, false, false);

        Gtk.ToolButton new_button = new Gtk.ToolButton.from_stock(Gtk.Stock.NEW);
        Gtk.ToolButton edit_button = new Gtk.ToolButton.from_stock(Gtk.Stock.EDIT);
        Gtk.ToolButton delete_button = new Gtk.ToolButton.from_stock(Gtk.Stock.DELETE);

        Gtk.MenuItem proxy = new Gtk.MenuItem.with_label("proxy");
        proxy.show_all();
        edit_button.set_proxy_menu_item("proxy_menuitem", proxy);

        toolbar.add(new_button);
        toolbar.add(edit_button);
        toolbar.add(delete_button);

        Gtk.Label content_label = new Gtk.Label("Placeholder");
        main_box.pack_start(content_label, false, false);
    }
}

Answer 1

It turns out that set_proxy_menu_item is temporary, and should be used in a response to the create-menu-proxy signal. I can't find this documented anywhere on the web, but here it is from the Gtk+ source code:

/**
 * GtkToolItem::create-menu-proxy:
 * @tool_item: the object the signal was emitted on
 *
 * This signal is emitted when the toolbar needs information from @tool_item
 * about whether the item should appear in the toolbar overflow menu. In
 * response the tool item should either
 * <itemizedlist>
 * <listitem>call gtk_tool_item_set_proxy_menu_item() with a %NULL
 * pointer and return %TRUE to indicate that the item should not appear
 * in the overflow menu
 * </listitem>
 * <listitem> call gtk_tool_item_set_proxy_menu_item() with a new menu
 * item and return %TRUE, or 
 * </listitem>
 * <listitem> return %FALSE to indicate that the signal was not
 * handled by the item. This means that
 * the item will not appear in the overflow menu unless a later handler
 * installs a menu item.
 * </listitem>
 * </itemizedlist>
 *
 * The toolbar may cache the result of this signal. When the tool item changes
 * how it will respond to this signal it must call gtk_tool_item_rebuild_menu()
 * to invalidate the cache and ensure that the toolbar rebuilds its overflow
 * menu.
 *
 * Return value: %TRUE if the signal was handled, %FALSE if not
 **/

So the right way to solve this would be something like:

edit_button.create_menu_proxy.connect(on_create_menu_proxy);

...

private bool on_create_menu_proxy(Gtk.ToolItem tool_item) {
    Gtk.MenuItem proxy = new Gtk.MenuItem.with_label("proxy");
    tool_item.set_proxy_menu_item("proxy_menuitem", proxy);
    return true;
}

You may not actually want to create a new proxy every time the signal is fired, but that should be enough to help anyone reading this get started.