Using application menus (or not) cross-platform

I’m working on a new Gtk3-based application which should be cross-platform. I’d like this to work and look properly on various window managers and OS’es. So I spent some time comparing GtkMenu vs GMenu and found that application menus are on their way out and I should use ‘primary’ and ‘secondary’ menus.

Unfortunately I can’t find any documentation on this way of working with menus, and I suspect this new approach is Gnome-specific, which wouldn’t help me.

So, my question is two-fold: where is the documentation on using this ‘new’ approach, and does it make sense for non-Gnome applications?

1 Like

Does it make sense for non-Gnome applications?

I strongest beleave that a lot of things in Gtk, have not sense currently from outside Gnome because that concepts are don’t used outside GNOME at all and in my personal opinion this will make your application fully out of place in other platforms.

I think that the intention of all new design patterns of Gtk is make it as an standard also outside GNOME, but in practice i think this is impossible. You also will need to take in account that more new design patterns can come later to Gtk, so you will have more things to worried about than just Menus if you select Gtk as a toolkit to your app, please see: GTK support for GNOME design patterns

If you have a plan of migrate your application from Gtk3 to Gtk4 in the future is another thing to worried about. Please also see that they have the idea of discontinue the usage of GtkMenus in the future and then force you to select the new GMenuModel. With other features I can not ensure that will be different.

To complicate even more the things there are currently no official way to modify the look and feel of a Gtk4 application outside GNOME as was occurred with Gtk3 in Unity desktop, for example. See the related issue here.

So, a Gtk application will look like more and more out of the place in other desktop environments and that means to me that the GNOME pattern of Gtk is a wrong selection if you want to have an application that:

work and look properly on various window managers and OS’es

(I don’t seem to be able to quote the previous post, but here we go)

Thanks for your answer. Unfortunately it seems you didn’t understand my question, or perhaps you assumed I want my portable application to look and behave exactly like a Gnome application, which isn’t the case.

I’m aware of the various bugs/weirdness of running Gtk3 on Windows (or MacOs), I’ve become the de-facto Windows maintainer for a project using Gtk3 while I know very little about Windows.
We chose Gtk3 since it’s widely portable and accessible via C (and it looks good).

So my question stands, do I use GtkApplication/GtkMenu etc, or do I use this new primary/secondary menu interface, and if so, where can find docs about that?

One of the reasons we retired application menus was to make things easier for cross-platform applications, since they were a GNOME-specific convention. So the situation today is hopefully better for you than it was 6 months ago.

The recommendation for GNOME applications is to move any menu items they had in their application menu to their primary menu (which apps generally had anyway). However, if you are using a menu bar then you would move the items there and wouldn’t be expected to have a primary menu.

Primary and secondary menus certainly do appear outside of GNOME: both Firefox and Chrome have them on Windows, for example.

The main guidelines for primary and secondary menus are in the HIG, although I’m afraid that’s slightly out of date (we have updates in the pipeline). In the meantime the design advice for GNOME applications can be found here.

I’ve read the docs you link to, and those make sense.

The problem seems to be the absence of code examples of actually creating these primary and secondary menus and somehow making an application use them.

In other words: how the hell do I set up a GtkApplication with these menus? :slight_smile:

So my question stands, do I use GtkApplication/GtkMenu etc, or do I use this new primary/secondary menu interface, and if so, where can find docs about that?

I will split my comment because i only can post 2 links per comment (edit: now i can post more links).

It’s more complex than just that. I answered that original question and the answer was that this will depend of your intention, but eventually you will be force to migrate your application from a conventional GtkMenu to a GMenuModel (with is in some cases that primary and secondary menu). Do you notice that a design-pattern is just that a pattern and is you who can follow it or not? There are not a clear methodology to follow a design-pattern in a general application (because all applications are strictly different). In this new Gtk, It’s you making the application that look like similar to other application of the platform or no. If you decide follow one designing-patter your app will look like in one way and if you decide follow other, the application will look like different. My focus was about that this could not be maintained in the future, because designers are creating more and more different design patters and trying to force that the toolkit follow that patters. In my opinion this is invasive and can cause that you can not follow some conventional design in a future, because not all this can be supported, because that would be inhuman.

The primary difference between a GtkMenu and a GMenuModel is that the first is a widget only and the second is a model, but that model can be instantiate as a Gtk widget when you want and in whatever place you want. In Gtk, there are different concepts for menus that you need to know first. You can differentiate the menus by the origin of his actions. There are actions that are at the level of an application and actions that are at the level of a window of your application. You can formed a GtkMenu with a mix of that type of actions or only with one type. A classical menubar have a mix of different type of actions and for example an appmenu have just actions that belong to the scope of the application (please note that appmenu and menubar are Gtk concepts). This become in something even more complicated recently, when was added the concept of primary and secondary menus and was retired the appmenu from the shell, but in practice it was not in that way, because that possibility always was there, just was not used by any GNOME apps. Please see that this changes don’t come into the Gtk3 and you can continues using the appmenu in Gtk3, just it will not be displayed inside the gnome-shell panel and by contrary it will be displayed inside the application. This is possible because the appmenu is a model and can be exported and receive also in a different application.

So, now you can have all that combinations for the main menu of your application:

1- A menubar (with a GtkMenu).
2- A menubar (with a GMenuModel).
3- An appmenu (with a GMenuModel).
4- A primary and secondary menu (both with a GMenuModel).
5- But you can have more and more representations like you want.

An example to the first option is there. You will need to create a menuBar = gtk_menu_bar_new (); and then you need to append it to your window.

But as apparently you want to use a GMenuModel and not directly the old GtkMenu you will probably want to associate your real menu to your model.

This is the second part:

As you also want to use the primary and secondary menus, you need to read how to create your GMenu Model and also the buttons where you want to set your menu. It will be in a GtkMenuButton, if you want to have something like the primary or secondary buttons.

Also i think you need to know what are some related concepts, like the difference between a client-side decoration window to a server-side decoration, also the difference between headerbar (see the GtkHeaderBar) and menubar (see the GtkMenuBar), to really know what you are doing with your app.

One link that can help you to understand the problematic and the decision of Microsoft about your own question, can be found here. Please read it fully

Here you have also more information from the KDE side.

I hope that this will help you instead of creating more problem to you. I think that in my first comment i was a gentleman trying to get you away from a demon, but if you want the devil, you’re going to have to learn to use the sword. There are not other way…

So I’ll just play devil’s advocate and say that having an application that looks different isn’t terrible unless it flat out looks bad.

As to your actual question: maybe do some research into GtkHeaderBar. Once you do, note that the “primary” and “secondary” menus are just menu buttons that go on the header bar, like Chrome’s hamburger menu. Nothing fancier than that.

In most cases you’ll only need one, in which case it would simply create a menu and place it at the end of your header bar. I’d personally recommend you try out some modern GNOME applications (like Fractal) if you want to concretely see how it appears in practice. You can also use the GTK inspector to see the actual widgets being used live by setting GTK_DEBUG=interactive when you run the application.

If you want to add a primary/secondary menu—i.e. an “hamburger” menu—you define your menus using GMenu and GAction and then use GtkMenuButton inside your header bar.

If you want to use a more classic application menu bar that is also portable on macOS and Unity (for those still rocking the older Ubuntu versions)—i.e. it’ll end up as the global menu bar outside your window—then you can use GMenu, GAction, and GtkApplication’s gtk_application_set_menubar() method.

You can also build your own GtkMenu out of a GMenuModel instance or with GtkMenuItem widgets, like you used to in GTK 2, but the menu will stay attached to the window.

For GTK 4, the plan is to only allow descriptions of menus using the GMenu API, instead of letting you build widgets out of them, so that we can make GTK fit in with other platforms.

As a side note: it’s entirely fine to have different UIs depending on the platform, to conform to the platform’s interface guidelines. It’s also entirely fine if you want to maintain your own UI style across different platforms. What GTK cannot do is to choose a style for you, because UI layout and hierarchy is not something that a toolkit can modify underneath you; this means you’re in control when it comes to structuring your UI.


So I’ll just play devil’s advocate and say that having an application that looks different isn’t terrible unless it flat out looks bad .

You are a devil’s advocate? In fact what you mention is the real problem CSD looks bad outside GNOME. If I were the devil I would prefer to defend by my own :slight_smile:.

Some other reading that i consider interesting to you (Edit: Please note that Nathaniel Graham (Nate) is a KDE developer and those are articles of his personal blog and then non of that information is my personal criteria or something similar like that):

Please, stop. We understood: you don’t like CSD. Don’t use them. Afford other people the courtesy of deciding of using them.


Please, stop. We understood: you don’t like CSD. Don’t use them. Afford other people the courtesy of deciding of using them.

Please can you stay on topic? I think no one here want to know if you understand or not something that I’m saying. Please don’t make it personal because is not and this is not about you or me at all. In fact, i don’t wrote anything specifically directly to you. All my comments have a reference and most references are to a technical information on the GNOME side or also can be a directly reference to a technically contents in the developers blog of another different platform of GNOME or finally to another developer site of another company or platform. So, this is not just my personal criteria. If you want to deny something of what I say, please do it with arguments, because you have a lot of that, you are an excellent developer.

This is a cross-platform question (please see the title) and nobody until now (other than me) has provided technical information that come from outside the GNOME platform. I think that this is not natural in first place and does not contribute anything to the discussion.

This appears to be drifting a bit from our Community norms, and I think the original question has been answered. Let’s temporary close this to calm things down a little.
As a reminder, the flag icon is there for a reason.

1 Like

This topic was automatically opened after 44 hours.

@ebassi, I also found this question confusing for myself. After your comment, it is a little bit clear. May be this question wasn’t covered well enough in the documentation. It may be a good idea to emphasize the recommended way to create menus and describe other options and cases where those options can be used. If I understand correctly, GtkMenu will be obsolete and GMenu will be the only way to go. Also, GTK team is moving away from the application menu and all menu should be added via primary and secondary menus as described elsewhere. I interpret this a transition point where we have two approaches and this fact itself rises the confusion. I assume, after the official release of GTK4 the documentation will point this out. Thanks.

Also I think that this is the point that still is not clear.

In my opinion (and this is only my opinion now, please clarify me if not) there are not a transition point between the application menu and the primary and secondary menus in GTK. Is in the GNOME enviroment as a whole where the transition is occurring (but just when is possible make it). By contrary, will be the transition in Gtk from the GtkMenu to the GMenuModel between Gtk3 and Gtk4 that is proposed…

Also i think that if Gtk and GNOME are the same thing there are not way to speak about cross-platform on GTK as GNOME is a platform and then the current question will have not sense. In my opinion Gtk and GNOME are not the same thing, but please correct me if i’m wrong and correct also the user who ask here about the cross-platform thing.

To me cross-platform is why Gtk still is a general and wonderful toolkit, that can be used also when there are not intention to make an app that will run in GNOME. Because of that it support both types of menus representations and I think it will support that for a long-long time, because outside GNOME in some environments the menubar is still the default way to use menus.

I agree also with that. Without a clear documentation a programmer is at the mercy of the personal taste of designers, and I think this is not the idea. The idea can not be just make something and then discover that this can not be used in an specific platform. There are not such thing like a table of Gtk features (or also design patterns) and where that features are supported and where not. Also if the support in an specific platform is full or incomplete and the cause. That missing documentation is creating that type of discussions…

There is no point in discussing whether something that can not work well on the X platform is the best or the worst that we can use on the same platform. The answer here is clear: If it can not work well on the X platform, please do not use it on the X platform!

This is not about personal tastes then, is not about my personal tastes, but is also not about the GNOME design guidelines, is only about Gtk and nothing else.

Now that this thread is opened again, I can report that for me the GtkHeaderBar was the “missing link”. Once I read up on that widget and started using it, things fell into place.

I’m using GtkBuilder to create a GMenuModel, which is a little different from my usual approach of using purely code to generate menus, but it’s working pretty well.


I linked to all the relevant places in the available documentation for this reason. The recommended approach for creating menus in GNOME is documented; maybe it’s not immediately accessible, but that’s not really related. We do have a page that says “how do I define menus”, so we can’t really add another page that says “here’s how we define menus” because it would be the same page.

The GNOME human interface guidelines are moving away from application menus: GTK has nothing to do with that.

GTK 3 still supports GtkMenu in parallel with GMenu.

We’re discussing making GtkMenu private and only allowing declarative menu descriptions using GMenu for GTK 4, though it’s still in the planning phase.

Yes: should we only support menus described using GMenu in GTK 4, it will be part of the porting guide, as well as part of the API reference.

1 Like