GtkMenu::popup

The popup() method looks fairly intimidating at the outset, but is actually quite straightforward to use.

The first thing to be aware of is that the parent_menu_shell and parent_menu_item parameters would generally only be used internally, to associate the popped-up menu with a given GtkMenuShell descendant, or GtkMenuItem, or both. In a freestanding popup menu, both parameters should be passed as null.

The third parameter concerns the positioning of the popup menu, and has as its default the position of the mouse pointer. In order to set a different position, you will need to set up a function that will return an array of the co-ordinates, and call it from the pos_function parameter.

<?php
function position() {
    $position = array(300, 200);
    return $position;
}

$filemenu->popup(null, null, 'position', $event->button, $event->time);
?>

      

The fourth parameter refers to the mouse button emitting the "button-release-event" that will be compared with the button emitting the "button-press-event" in order to set the timer in the final parameter. This only works if you happen to be triggering the popup function with a button press, and the button pressed and button released are the same - in all other situations, the time element is ignored. However, setting the button parameter to 1 or 3 will speed up the deactivation when the left or right mouse button is released respectively, regardless of the callback event.

The final parameter, activate_time, sets the time conditions for the menu's deactivation. If you have used a button press event and ensured that the initial press and later release have the same valid integer value, then setting the timer to 0 will make the menu disappear as soon as the user releases the mouse-button that triggered it. The safest setting for this parameter is $event->time - this being a setting that all GdkEvent structures share; it causes the popup menu to react as you'd expect it to, and won't spring any surprises if you duplicate or otherwise adapt the original callback event.

<?php
//Popup menu example:
// An empty window in which you can right-click
// to show a popup menu

//Setup this menu: Add two items that echo something
// to the console when clicked
$menu = new GtkMenu();

$echo1 = new GtkMenuItem('Echo 1');
$echo1->connect_simple('activate', 'doEcho', 'echo1');
$menu->append($echo1);

$echo2 = new GtkMenuItem('Echo 2');
$echo2->connect_simple('activate', 'doEcho', 'echo2');
$menu->append($echo2);

//The menu is not shown, but this here is necessary
// to let it show when using popup()
$menu->show_all();


//This funciton is used as a callback and just echoes the parameter
function doEcho($message) {
    echo $message . "\r\n";
}

//The function used as callback for the popup
function doPopup($window, $event, $menu)
{
    //Check if it was the right mouse button (button 3)
    if ($event->button == 3) {
        //popup the menu
        $menu->popup();
    }
}

//Create a normal window
$wnd = new GtkWindow();

//Normally, the window doesn't receive the button press events.
// As we need them here, we force the window to accept and
// distribute them to our callbacks
$wnd->set_events($wnd->get_events() | Gdk::BUTTON_PRESS_MASK);
//Connect a callback to the butt press event
$wnd->connect('button-press-event', 'doPopup', $menu);

//Standard stuff
$wnd->connect_simple('destroy', array('Gtk', 'main_quit'));
$wnd->show_all();
Gtk::main();
?>