File: //usr/share/gtk-doc/html/gtk/gtk-migrating-checklist.html
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Migration Checklist</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.69.1">
<link rel="start" href="index.html" title="GTK+ Reference Manual">
<link rel="up" href="migrating.html" title="Part IV. Migrating from Previous Versions of GTK+">
<link rel="prev" href="migrating.html" title="Part IV. Migrating from Previous Versions of GTK+">
<link rel="next" href="checklist-gdkeventexpose-region.html" title="Use GdkEventExpose.region">
<meta name="generator" content="GTK-Doc V1.6 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
<link rel="part" href="gtk.html" title="Part I. GTK+ Overview">
<link rel="part" href="gtkbase.html" title="Part II. GTK+ Core Reference">
<link rel="part" href="gtkobjects.html" title="Part III. GTK+ Widgets and Objects">
<link rel="chapter" href="ch01.html" title="Object Hierarchy">
<link rel="chapter" href="ch02.html" title="Widget Gallery">
<link rel="chapter" href="WindowWidgets.html" title="Windows">
<link rel="chapter" href="DisplayWidgets.html" title="Display Widgets">
<link rel="chapter" href="ButtonWidgets.html" title="Buttons and Toggles">
<link rel="chapter" href="NumericEntry.html" title="Numeric/Text Data Entry">
<link rel="chapter" href="TextWidgetObjects.html" title="Multiline Text Editor">
<link rel="chapter" href="TreeWidgetObjects.html" title="Tree, List and Icon Grid Widgets">
<link rel="chapter" href="MenusAndCombos.html" title="Menus, Combo Box, Toolbar">
<link rel="chapter" href="Actions.html" title="Action-based menus and toolbars">
<link rel="chapter" href="SelectorWidgets.html" title="Selectors (File/Font/Color/Input Devices)">
<link rel="chapter" href="LayoutContainers.html" title="Layout Containers">
<link rel="chapter" href="Ornaments.html" title="Ornaments">
<link rel="chapter" href="ScrollingWidgets.html" title="Scrolling">
<link rel="chapter" href="Printing.html" title="Printing">
<link rel="chapter" href="MiscObjects.html" title="Miscellaneous">
<link rel="chapter" href="AbstractObjects.html" title="Abstract Base Classes">
<link rel="chapter" href="PlugSocket.html" title="Cross-process Embedding">
<link rel="chapter" href="SpecialObjects.html" title="Special-purpose features">
<link rel="chapter" href="RecentDocuments.html" title="Recently Used Documents">
<link rel="chapter" href="DeprecatedObjects.html" title="Deprecated">
<link rel="part" href="migrating.html" title="Part IV. Migrating from Previous Versions of GTK+">
<link rel="chapter" href="gtk-migrating-checklist.html" title="Migration Checklist">
<link rel="chapter" href="gtk-migrating-GtkFileChooser.html" title="Migrating from GtkFileSelection to GtkFileChooser">
<link rel="chapter" href="gtk-migrating-GtkAction.html" title="Migrating from old menu and toolbar systems to GtkAction">
<link rel="chapter" href="gtk-migrating-GtkComboBox.html" title="Migrating from GtkOptionMenu and GtkCombo to GtkComboBox and
GtkComboBoxEntry">
<link rel="chapter" href="gtk-migrating-GtkIconView.html" title="Migrating from GnomeIconList to GtkIconView">
<link rel="chapter" href="gtk-migrating-GtkAboutDialog.html" title="Migrating from GnomeAbout to GtkAboutDialog">
<link rel="chapter" href="gtk-migrating-GtkColorButton.html" title="Migrating from GnomeColorPicker to GtkColorButton">
<link rel="chapter" href="gtk-migrating-GtkAssistant.html" title="Migrating from GnomeDruid to GtkAssistant">
<link rel="chapter" href="gtk-migrating-GtkRecentChooser.html" title="Migrating from EggRecent to GtkRecentChooser">
<link rel="chapter" href="gtk-migrating-GtkLinkButton.html" title="Migrating from GnomeHRef to GtkLinkButton">
<link rel="part" href="pt05.html" title="Part V. GTK+ Tools">
<link rel="glossary" href="glossary.html" title="Glossary">
<link rel="index" href="ix01.html" title="Index">
<link rel="index" href="ix02.html" title="Index of deprecated symbols">
<link rel="index" href="ix03.html" title="Index of new symbols in 2.2">
<link rel="index" href="ix04.html" title="Index of new symbols in 2.4">
<link rel="index" href="ix05.html" title="Index of new symbols in 2.6">
<link rel="index" href="ix06.html" title="Index of new symbols in 2.8">
<link rel="index" href="ix07.html" title="Index of new symbols in 2.10">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
<td><a accesskey="p" href="migrating.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="migrating.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">GTK+ Reference Manual</th>
<td><a accesskey="n" href="checklist-gdkeventexpose-region.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr></table>
<div class="chapter" lang="en">
<div class="titlepage"><div><div><h2 class="title">
<a name="gtk-migrating-checklist"></a>Migration Checklist</h2></div></div></div>
<div class="toc"><dl>
<dt><span class="section"><a href="gtk-migrating-checklist.html#checklist-popup-menu">Implement GtkWidget::popup_menu</a></span></dt>
<dt><span class="section"><a href="checklist-gdkeventexpose-region.html">Use GdkEventExpose.region</a></span></dt>
<dt><span class="section"><a href="checklist-modifiers.html">Test for modifier keys correctly</a></span></dt>
<dt><span class="section"><a href="checklist-named-icons.html">Use named icons</a></span></dt>
</dl></div>
<p>
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.
</p>
<div class="section" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="checklist-popup-menu"></a>Implement GtkWidget::popup_menu</h2></div></div></div>
<p><b>Why. </b>
By handling this signal, you let widgets have
context-sensitive menus that can be invoked with the standard
key bindings.
</p>
<p>
The <a href="GtkWidget.html#GtkWidget-popup-menu">GtkWidget::popup_menu</a>
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
<span><strong class="keycap">Shift</strong></span>-<span><strong class="keycap">F10</strong></span>
or <span><strong class="keycap">Menu</strong></span> 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:
</p>
<div class="orderedlist"><ol type="1">
<li>
<p>
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 <a href="GtkMenu.html#gtk-menu-popup"><code class="function">gtk_menu_popup()</code></a>. You can implement
such a function like this:
</p>
<a name="do_popup_menu"></a><pre class="programlisting">
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 (menu), my_widget, NULL);
gtk_menu_popup (GTK_MENU (menu), NULL, NULL, NULL, NULL,
button, event_time);
}
</pre>
</li>
<li>
<p>
In your button_press handler, call this function when you
need to pop up a menu:
</p>
<pre class="programlisting">
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;
}
</pre>
</li>
<li>
<p>
Implement a handler for the popup_menu signal:
</p>
<pre class="programlisting">
static gboolean
my_widget_popup_menu_handler (GtkWidget *widget)
{
do_popup_menu (widget, NULL);
return TRUE;
}
</pre>
</li>
</ol></div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>
If you do not pass a positioning function to <a href="GtkMenu.html#gtk-menu-popup"><code class="function">gtk_menu_popup()</code></a>,
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
<span><strong class="keycap">Shift</strong></span>-<span><strong class="keycap">F10</strong></span>
or <span><strong class="keycap">Menu</strong></span> keys while the widget is focused, the
mouse cursor may not be near the widget at all. In the <a href="gtk-migrating-checklist.html#do_popup_menu">example above</a>, you may want to
provide your own <a href="GtkMenu.html#GtkMenuPositionFunc">menu-positioning function</a>
in the case where the <em class="parameter"><code>event</code></em> is
<code class="constant">NULL</code>. This function should compute the
desired position for a menu when it is invoked through the
keyboard. For example, <a href="GtkEntry.html" title="GtkEntry"><span class="type">GtkEntry</span></a> aligns the
top edge of its popup menu with the bottom edge of the entry.
</p>
</div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>
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 <a href="GtkWidget.html#GTK-CAN-FOCUS:CAPS"><code class="literal">GTK_CAN_FOCUS</code></a> flag.
</p>
</div>
</div>
</div>
</body>
</html>