migration checklist

implement gtkwidget::popup_menu
use gdkeventexpose.region
test for modifier keys correctly
use named icons

this chapter includes a checklist of things you need to do to ensure that your programs are good citizens in the gtk+ world. by paying attention to the points in the checklist, you ensure that many automatic features of gtk+ will work correctly in your program.

implement gtkwidget::popup_menu

why. by handling this signal, you let widgets have context-sensitive menus that can be invoked with the standard key bindings.

the gtkwidget::popup_menu signal instructs the widget for which it is emitted to create a context-sensitive popup menu. by default, the key binding mechanism is set to emit this signal when the shift-f10 or menu keys are pressed while a widget has the focus. if a widget in your application shows a popup menu when you press a mouse button, you can make it work as well through the normal key binding mechanism in the following fahion:

write a function to create and show a popup menu. this function needs to know the button number and the event's time to pass them to gtk_menu_popup(). you can implement such a function like this:

static void
do_popup_menu (gtkwidget *my_widget, gdkeventbutton *event)
{
  gtkwidget *menu;
  int button, event_time;

  menu = gtk_menu_new ();
  g_signal_connect (menu, "deactivate", 
                    g_callback (gtk_widget_destroy), null);

  /* ... add menu items ... */

  if (event)
    {
      button = event->button;
      event_time = event->time;
    }
  else
    {
      button = 0;
      event_time = gtk_get_current_event_time ();
    }

  gtk_menu_attach_to_widget (gtk_menu (popup), my_widget, null);
  gtk_menu_popup (gtk_menu (popup), null, null, null, null, 
                  button, event_time);
}

in your button_press handler, call this function when you need to pop up a menu:

static gboolean
my_widget_button_press_event_handler (gtkwidget *widget, gdkeventbutton *event)
{
  /* ignore double-clicks and triple-clicks */
  if (event->button == 3 && event->type == gdk_button_press)
    {
      do_popup_menu (widget, event);
      return true;
    }

  return false;
}

implement a handler for the popup_menu signal:

static gboolean
my_widget_popup_menu_handler (gtkwidget *widget)
{
  do_popup_menu (widget, null);
  return true;
}

note

if you do not pass a positioning function to gtk_menu_popup(), it will show the menu at the mouse position by default. this is what you usually want when the menu is shown as a result of pressing a mouse button. however, if you press the shift-f10 or menu keys while the widget is focused, the mouse cursor may not be near the widget at all. in the example above, you may want to provide your own menu-positioning function in the case where the event is null. this function should compute the desired position for a menu when it is invoked through the keyboard. for example, gtkentry aligns the top edge of its popup menu with the bottom edge of the entry.

note

for the standard key bindings to work, your widget must be able to take the keyboard focus. in general, widgets should be fully usable through the keyboard and not just the mouse. the very first step of this is to ensure that your widget turns on the gtk_can_focus flag.