ApplicationMenu

Application Menu

In the 10.10 cycle we are working to bring support to the Ubuntu Netbook Edition for application menus in the panel. We feel that the interaction design benefits for this work are significant and Canonical are investing in producing support for this throughout the 10.10 cycle. For more on the design rationale, see the announcement for details.

We have produced an implementation that supports GTK and Qt menus and this implementation is known as indicator-appmenu. Essentially the project re-routes menus over dbusmenu so that they appear in the panel.

To ensure that this feature is high-quality and well tested, the code has been released right at the beginning of the Maverick cycle and we are keen to work with the community to (a) test applications and (b) fix indicator-appmenu and applications that experience problems.

This page is where you can learn how to participate in this work and where we can track progress.

Goals

We need to test the global menu on as many applications as possible. We will put the application menu in the Unity (Lucid) PPA so that upstream developers and enthusiasts can test it without committing to Maverick.

  • XUL applications (such as Firefox and Thunderbird) and OpenOffice are NOT targets for Maverick, as they will require more work.

  • We need testing on GTK and Qt applications.
  • Work on supporting other the application menu on other toolkits would be welcome, but not a priority for the DX team, help wanted.

Schedule

  • Alpha 1 - Enable the application menu in Lucid PPA.
  • Alpha 2 - Turn off double menu feature, upload to Maverick.
  • Alpha 3 - Testing.
  • Beta/RC - Done
  • Releases: The DX team will make a release every week on Thursday, Ken will then upload these to the PPA and Maverick on either Thursday or Friday depending on workload.

You can track the status of the menu as it gets released and upgraded into Maverick here.

Installation

Ubuntu Netbook Installation

  1. If you are on Lucid, load a terminal and run sudo add-apt-repository ppa:canonical-dx-team/une and sudo apt-get update.

Note: The Unity PPA brings in some lower level components that we need like a new GTK and some new libraries. You should be comfortable with being able to downgrade multiple packages if you want to go back to a stable Lucid, otherwise we recommend a virtualization tool like testdrive to test Unity.

  1. Run sudo apt-get install unity ubuntu-netbook-unity-default-settings.

  2. Log out and log in back into the Unity session.

Ubuntu Desktop Installation

For development purposes, a gnome-panel compatible version is also available.

  1. If you are on Lucid, load a terminal and run sudo add-apt-repository ppa:canonical-dx-team/une and sudo apt-get update.

    • Don't add the PPA if you're on Maverick, skip right to step 2!
  2. Install packages:  apt-get install appmenu-gtk libqtgui4 indicator-applet-appmenu indicator-appmenu

  3. Right click on the panel, and add the "Indicator Applet Appmenu" applet. Note: you won't see any change on the panel yet, but if you add the applet a second time it will exit so you can remove it (choose: delete & don't reload)

  4. Run an application like gedit.
  5. It should now look like this:

globalmenu.png

Note: if you already have other gnome-terminal's open, make sure you close them all before you issue the command above

Note: When testing we purposely enable the Global Menu AND keep the old menu in place. That way it is obvious to you if anything is broken. Unity will also pull in indicator-datetime, so you will end up with two clocks too. Please don't file bugs on double menus and clocks, it's like that on purpose! See below.

Kubuntu Desktop Installation

  1. If you're on Lucid, register the Unity PPA in your sources.list.

    • If you're on Maverick, don't add the PPA, the packages will be in the distribution.
  2. Install packages:  apt-get install libqtgui4 plasma-widget-menubar

  3. Add the "Window Menubar" applet to your panel.
  4. Start any Qt/KDE application, the menu should be embedded in the panel. You can enable double menus by setting the APPMENU_DISPLAY_BOTH environment variable: APPMENU_DISPLAY_BOTH=1 dolphin

  5. To disable menu embedding for a particular app, set the QT_X11_NO_NATIVE_MENUBAR environment variable: QT_X11_NO_NATIVE_MENUBAR=1 dolphin

Test Plan

Testing the rendering of the menus

The appmenu indicator presents menus on the panel but there are particular cases where this may not work, like with:

  • applications that have non-standard GTK or Qt menu items, or specific widgets like the Firefox throbber
  • applications that have multiple menubars
  • applications that have a fullscreen mode

The goal is to identify all the applications that may not be working properly in those particular cases.

Note: this only works with Qt or GTK based applications. Namely, OpenOffice, Mozilla or Java AWT applications are not supported.

  1. Test the Application
    • Check every menu item, every sub menu, and every submenu item.
    • Check for state changes, things that cause the menus to become insensitive or reorder.
    • Check to make sure icons, translations, and text are correct.
    • If something is acting wrong check to see if the normal menu in the application window exhibits the same behavior.
    • Fill in the status of the application in the grid below.
  2. Filing bugs:
    • For applications that have a bug with the application menu, file a bug on launchpad and tag it with "app-menu". If possible, attach a dump of the menu (See "Dumping Menus" below).
    • File a wishlist bug in the upstream bug tracker and ask them if they would consider supporting the application menu. Provide links to this page and to the documentation so that it's easy for application authors to find what they need.
    • Make sure you link the launchpad bug to the upstream bug (Instructions) so that we can follow the bug and see if any developers need help adapting their application.

    • You can install "gtk-recordmydesktop" if you want to attach a video of the menu to the bug report (this is very helpful!)

Dumping menus

The new way: dbusmenu-dumper

The libdbusmenu-tools package provides a tool named dbusmenu-dumper. This tool can dump a JSON representation of a window menu, as seen by the applet. To use the tool, open a terminal and type this:

$ /usr/lib/libdbusmenu/dbusmenu-dumper > myapp.json

The mouse cursor should change to a crosshair: click on the window you want to dump.

The old way: current-menu-dump

If for some reason you can't use dbusmenu-dumper, then you can resort to the tools from the indicator-appmenu-tools package. They're installed in /usr/lib/indicator-appmenu.

  • current-menu -- gives the DBus name, object and XWindow ID of the currently displayed menu.

  • current-menu-dump -- uses the output of current-menu to find the current menu and then dumps the DBus representation of that menu in a JSON format.

The best way for debugging is to use this similar to a screenshot utility so something like this:

$ sleep 5 ; /usr/lib/indicator-appmenu/current-menu-dump > myapp.json

Which will wait for five seconds while you switch windows and then dump the menu.

Testing the appmenu module

The panel need to present the menubar of the currently active application. This part of the test plan ensures that this behavior is properly implemented.

Main use cases to support (User level)

  • Using the (default) desktop menu - when the user is using the desktop (ie no other application is the active application), the system needs to display the default desktop menu

  • Opening an application - when the user opens an application, the System needs to switch the panel menu to display the menu of that application

  • Switching to another application - when the user switches to another application (ie another application becomes the 'active' one), the System needs to switch the panel menu similarly

  • Quitting an application - when the user quits an application, the System will have to determine which other application becomes the active one, and display the corresponding menu; if no application is active, a default menu should be displayed

Other use cases (System level)

  • Managing transient windows - when transient windows take the focus, the System needs to present the right panel menu to the user

  • Managing unresponsive applications - the System needs to manage applications that either block or crash

  • Managing unsupported applications - the System needs to display a minimal menu corresponding to an active application that does not support our menu system

Filing bugs

Getting Help

If you're an upstream app developer and your application doesn't work we have a few options for you:

  1. Upstream Application Developers - If you use GTK or Qt menus without any custom widgets it should Just Work. In some cases removing the custom menu bits should make it all work.
  2. Ted Gould (tedg) and Cody Russell (bratsche) are available on #ayatana on Freenode IRC if you have a special case and need help.
  3. The Ayatana Mailing List is the right mailing list to post technical questions and queries.

  4. If you still can't find help mail JorgeCastro and he'll hunt someone down for you.

Troubleshooting

To disable appmenu support on a per application basis, set the UBUNTU_MENUPROXY variable to null, with:

  env UBUNTU_MENUPROXY= APPNAME

where APPNAME is the name of the program executable in question. The env keyword is useful if you're trying to launch the application with the ALT-F2 shortcut.

Other Information

The global menu guys have provided us a list of bugs from their bug tracker and other upstreams that have had problems in the past (thanks guys!). We will document these here for reference:

DesktopExperienceTeam/ApplicationMenu (last edited 2012-09-06 23:39:38 by rick-ucker)