How does KDE associate application categories with menus and submenus? And how can I add or edit these menus so that applications will be placed differently?

I wondered this myself, and Googling about had taught me just enough to know what I needed to know. So I came here and asked that question. Wouldn't you know it, within the hour, some more reading and judicious use of the find command had given me the answer I sought. So now I'm turning this "asking" post into an "answering" post.

In case you haven't guessed, I am not an expert. I'm just some guy who knows how to tinker with text files, had a question, and found an answer that he thought he'd share. Please, if I get something wrong, correct me. That's why this is here...

0. Target Audience

Let's suppose that you, like me, want to customise your Kickoff menu; maybe even change the system-wide settings for the Kickoff menu on your computer. Let's use Games as an example; maybe you think KNetWalk should be listed as a Logic Game, not Tactics and Strategy. Perhaps you agree that Kiriki is not a Board Game. And maybe like me, you've noticed that KBlackBox even says "Logic Game" in its description! And further suppose that you, like me, want games like Armagetron Advanced and BZFlag to stop showing up in the root of the Games section.

And you want to do all of this in such a way that it's part of KDE's own process for laying out the menus. You could use the Kickoff Menu Editor, if you don't want to make system-wide changes -- but let's assume that you want to do it right at the source, maybe even contribute your changes as an improvement to the maintainers of the apps that you're reclassifying.

Let me be clear here: as far as I can tell, the only things that the Kickoff Menu Editor can't do for you are:

• Change system-wide settings
• Change the settings by which menus automatically display a certain category of applications (my original goal)

Anyway. From here on out, I'll assume that you're comfortable with editing text files that handle system configuration. So you know that you need to open them in your preferred text editor using sudo, and that you should always, always keep a backup copy. Right? Right.

Everything here is tested only on my system. I'm running KDE SC 4.4, which is current at the time of writing, on Kubuntu 10.04 (Lucid). Some parts might possibly vary depending on what operating system or distribution is underlying your KDE installation.

1. Stuff You Need To Know

The first thing you should get familiar with is the FreeDesktop.org specifications for how menu setups should work. You don't have to read the whole thing; the important parts are the Format of Menu Files and the Registered Categories.

Secondly, you need to know where the files go. The FreeDesktop.org specs define this too, but they use placeholders like $XDG_CONFIG_DIRS. These look like environment variables, and your environment may specify values for some of them, but those that aren't specified should have these default values.

• $XDG_CONFIG_DIRS (/etc/xdg) holds system-wide definitions for how the menu should be structured: which submenus go where, which applications they hold, etc.
• $XDG_CONFIG_HOME (~/.config) holds user-specific versions of the above.
• $XDG_DATA_DIRS (/usr/share and /usr/local/share) holds system-wide definitions for each submenu and application: their names, icons, and so on. Ideally, you would leave the default files alone and put your replacements in the */local/* directory.
• $XDG_DATA_HOME (~/.local/share) holds user-specific versions of the above.

Within the CONFIG directories, you want to find "menus" (i.e. /etc/xdg/menus/ and ~/.config/menus/). In the former, there are two files of interest, kde-applications.menu and kde4-applications.menu, and I honestly have no idea which one is authoritative. In the latter, using the Kickoff Menu Editor will create applications-kmenuedit.menu; to be safe, I have used this name for my own customised menu too, even though I made it in the text editor.

Within the DATA directories, you want to find "desktop-directories" for the styling of each submenu, and "applications" for the shortcuts to each program.

2. Editing Submenus

We'll take the last part first, because it's very simple. Open any of the files in "desktop-directories". For example, this is /usr/share/desktop-directories/kde-games-arcade.directory; it's the file for the Games > Arcade menu.

Code: Select all

[Desktop Entry]
Encoding=UTF-8
Type=Directory
Name=Arcade
Name[af]=Arkade
...lots more languages omitted...
Name[zh_TW]=大型遊戲機遊戲
Icon=applications-games-arcade
X-KDE-SuppressGenericNames=Game,Arcade Game
X-Ubuntu-Gettext-Domain=desktop_kdebase-runtime


Most of this is pretty self-explanatory. X-KDE-SuppressGenericNames is a setting that tells KDE to not show the "generic name" (explained below) if it's something as trivial and obvious as "Game" or "Arcade Game". Don't ask me what X-Ubuntu-Gettext-Domain does though!

Now we can use this as a model for writing an Action Games menu, like so:

Code: Select all

[Desktop Entry]
Encoding=UTF-8
Type=Directory
Name=Action Games
Icon=applications-games
X-KDE-SuppressGenericNames=Game,Action Game
X-Ubuntu-Gettext-Domain=desktop_kdebase-runtime


To find the name of the icon you want, just open up Properties on any of your files, click the file's icon and browse around. (You have to do this on some file of yours, not the system-wide menu files. Copy one to your Home if you like.) I recommend looking in the System Icons > Categories list.

Save this as kde-games-arcade.directory in your user-specific or system-wide local directory (~/.local/share/desktop-directories/ or /usr/local/share/desktop-directories/). It won't show up yet; don't panic.

3. Editing Applications

Now let's move some games around. Open a file from "applications" or its subdirectories; for instance, this is /usr/share/applications/kde4/kblackbox.desktop, the menu entry for KBlackBox:

Code: Select all

[Desktop Entry]
GenericName=Blackbox Logic Game
Exec=kblackbox -caption "%c"
Name=KBlackBox
Icon=kblackbox
X-DocPath=kblackbox/index.html
Type=Application
Terminal=false
X-KDE-StartupNotify=true
X-DBUS-StartupType=Multi
Categories=Qt;KDE;Game;BoardGame;
X-Ubuntu-Gettext-Domain=desktop_kdegames


Again, quite self-explanatory. "Name" is just like before, and could have translations into multiple languages. "GenericName" is the text that shows up below the name in the menu, and like the title suggests, it should be a generic summary of the application, like "Word processor" or "Space adventure game".

If you agree that KBlackBox is a Logic Game, not a Board Game, just edit that bit of the Categories line! (Remember that this line has to end with a semicolon after the last category.) Save the file to your user-specific or system-wide local directory (~/.local/share/applications/ or /usr/local/share/applications/) -- don't forget to put it in a subfolder if the original came from one!

Unlike the last example, this one should have an obvious effect when you open the Kickoff menu*. KBlackBox will have moved out of Board Games and into Logic Games. All is as it should be. Your new file has overridden the file of the same name in the system-wide, distro-set directory (/usr/share/applications/).

Now let's make things not as they should be, just for testing purposes. Edit that file again (whether it was KBlackBox or something else you were fiddling with) and put it into Action Games instead. Again, you'll see it leave its old category; but because Action Games isn't listed (yet), it will just sit in the root of the Games menu.

4. Customising Submenu Placement and Filling

Now we need to make our Action Games submenu display. Go to your system-wide "menus" folder (/etc/xdg/menus/), and make a copy of /etc/xdg/menus/kde4-applications.menu (or maybe /etc/xdg/menus/kde-applications.menu -- I don't know if it matters which).

Unfortunately, putting a file by this name in your user-specific "menus" folder (~/.config/menus/) doesn't seem to override anything, so for our purposes here we'll modify the system-wide settings. Hence why we made a copy!**

The pertinent bit of the file looks like this:

Code: Select all

   <Menu>
      <Name>Games</Name>
      <Directory>kde-games.directory</Directory>
      <Menu>
         <Name>Arcade</Name>
         <Directory>kde-games-arcade.directory</Directory>
         <Include>
            <And>
               <Category>Game</Category>
               <Category>ArcadeGame</Category>
            </And>
         </Include>
      </Menu>
      <Menu>
         <Name>Board</Name>
         <Directory>kde-games-board.directory</Directory>
         <Include>
            <And>
               <Category>Game</Category>
               <Category>BoardGame</Category>
            </And>
         </Include>
      </Menu>


Just duplicate one of the submenus of Games, edit it to match your Action Games, and you're done! For example:

Code: Select all

   <Menu>
      <Name>Games</Name>
      <Directory>kde-games.directory</Directory>
      <Menu>
         <Name>Action Games</Name>
         <Directory>kde-games-action.directory</Directory>
         <Include>
            <And>
               <Category>Game</Category>
               <Category>ActionGame</Category>
            </And>
         </Include>
      </Menu>
      <Menu>
         <Name>Arcade</Name>
         <Directory>kde-games-arcade.directory</Directory>
         <Include>
            <And>
               <Category>Game</Category>
               <Category>ArcadeGame</Category>
            </And>
         </Include>
      </Menu>
      <Menu>
         <Name>Board</Name>
         <Directory>kde-games-board.directory</Directory>
         <Include>
            <And>
               <Category>Game</Category>
               <Category>BoardGame</Category>
            </And>
         </Include>
      </Menu>


You'll also have to find the part where uncategorised games are put into the root Games menu, and remove ActionGames from it -- otherwise your games will be listed twice. It looks like this before the required edit:

Code: Select all

      <Include>
         <And>
            <Category>Game</Category>
            <Not>
               <Category>ArcadeGame</Category>
               <Category>BoardGame</Category>
               <Category>CardGame</Category>
               <Category>X-KDE-KidsGame</Category>
               <Category>KidsGame</Category>
               <Category>StrategyGame</Category>
               <Category>LogicGame</Category>
            </Not>
         </And>
      </Include>


Just add another <Category> element for ActionGame, and it will be excluded.

And we're done!

---

* Actually, it looks to me like Kickoff will update itself as soon as you look at where the application used to be. Close and reopen the menu and all should be well.

** What you can do is use the Menu Editor (right-click K > Menu Editor), make some trivial change, and save. You should now have a file called applications-kmenuedit.menu in your user-specific "menus" directory (~/.config/menus). Edit this to have the <Include> element like the example here. Whether this works or not is left as an exercise for the reader...

Nice job on a guide to manually editing the menu. Do you mind if this is moved to Tutorials & Tips?

Not at all!

Thanks. Moved to Tutorials & Tips.