View Single Post
Nathraiben's Avatar
Posts: 267 | Thanked: 408 times | Joined on May 2010 @ Austria
#107
Since I was asked for easy to follow instructions and as a kind of thank you to everybody who made this possible by contributing to this thread, here's a step-by-step tutorial on how I categorised my folders:

Disclaimer[1]: I did not, in any way, invent these techniques. Almost everybody was pulled from this thread, so thanks to those great people who deliberately messed up their phones countless times to bring us these pieces of information.

Disclaimer[2]: !!!IMPORTANT!!! I've included instructions for those who are less Linux savvy and also provide small tricks to get your phone back up when you happened to mess up. BUT I would really like to discourage anybody who doesn't yet feel comfortable with both Linux and their device to stay away from these techniques until either they were able to collect more experience or a stable, graphical application has been developed to make these changes.

Disclaimer[3]: These instructions work on my N900 with the PR 1.2 update - I don't know if/how it works on other devices and other versions. Also, I'm born lazy, so I only created top-level folders and thus cannot share any experiences on creating nested folders. It's not impossible, though, and has already been done in this thread.


Tutorial on Making Folders (variable version)

Step 1: Get to know your icons

It doesn't really matter where you begin, but since icons don't include any references to other files we're going to create they seem to be the best place to start.

Application menu icons are .png graphic files with dimensions of 48x48 pixel and arbitrary colour depth (with support for alpha transparancy), so you can easily create your own.

But before you even consider that, let's take a look at the icons already loaded to your device (either from the vanilla installation or added by applications downloaded with the application manager).

They are located in /usr/share/icons/hicolor/48x48/hildon/

Since that folder cannot be reached by the maemo File Manager, let's make a copy either on the MicroSD card or the folder /home/user/MyDocs, both of which can be opened with the file manager AND are available to your PC when you connect the device in mass storage mode. In this example we'll create a folder "Icons" directly on the device.

To do that, load XTerminal and perform the following command:
Code:
mkdir /home/user/MyDocs/Icons
(Note: To make sure there are no typos, after typing the first few letters of each folder hit the "Tab" button at the bottom of your screen for auto-completion. This works for all the commands using folder paths and has the additional advantage of saving a LOT of typing... )

Next time you open your file manager and click on "Nokia N900", you'll find this new folder under the name "Icons" there.

After that let's copy the content of the original folder to this new one:
Code:
cp /usr/share/icons/hicolor/48x48/hildon/* /home/user/MyDocs/Icons
(This might take a while, depending on how many applications you already installed)

Thanks to the * at the end of your source folder, all of the files within have been copied to our new Icons folder - that means in the file manager you can actually already browse them.

Write down the filenames of those you want to use for your folders and/or create your own files (but don't forget to copy any self created files back to the /usr/share/icons/hicolor/48x48/hildon/ folder).

Step 2: So who's this Hildon?

Hildon is the application framework behind Maemo's current UI and our application menu is part of it. So it's no wonder our next step will be done in Hildon's application folder. Actually, one of two folders, since we can either add our files to

/usr/share/applications/hildon
or
/home/user/.local/share/applications/hildon

The first is for system-wide settings, while the latter is for user-specific ones. On our device, which only has one user, this doesn't make much of a difference, but it can be considered "cleaner" to only make changes within the /home/user/ folder. And then there's also the advantage of there being no need for getting root access.

We will have to create a text file next, so unless you're one of the geeks who like to work with VI, open your application manager and get yourself one of the text editors. I like PyGTKEditor best so far, but the most common editor would be Leafpad, both of which should be in Maemo Extras (I think).

Back in X Terminal, let's create a file that will represent the general properties of our folder:

Code:
pygtkeditor /home/user/.local/share/applications/hildon/games.directory
(Replace "pygtkeditor" with the editor of your choice and "games" with a name that will later let you know which folder this file is supposed to describe. So obviously for our Games folder, games.directory will provide the settings.)

At this moment, your editor should pop up and warn you about the file not existing (well, at least PyGTKEditor does ), but we already knew that - we're going to create it now, after all!

For that, copy the following template into your empty text file:
Code:
[Desktop Entry]
Type=Directory
Name=
Icon=
X-Osso-User-Position=1
X-Maemo-Category=Main
X-Text-Domain=maemo-af-desktop
Just leave the last three lines as they are (at least for me, changing X-Osso-User-Position didn't have any influence on the order in which the folders are displayed...) and only enter values for Name and Icon.

In this example, Name would be set to "Games", for hopefully obvious reasons.

As for the Icon, now the results of Step1 come into play: From the list of icons we want to use we'll have to choose the one for the Games folder and enter it's filename (WITHOUT the extension - so cut off the .png). I used "filemanager_games_folder", the yellow folder icon featuring a die.

So now the games.directory file should look about like this:
Code:
[Desktop Entry]
Type=Directory
Name=Games
Icon=filemanager_games_folder
X-Osso-User-Position=1
X-Maemo-Category=Main
X-Text-Domain=maemo-af-desktop
Save and exit.

Step 3: Let's screw up our system!

So far all we have done was pretty uncritical, since we didn't edit any standard files but only created our own. Now we'll actually mess with on of the system-generated files, so beware: Whatever you do in there, it might completely knockout Hildon (take a look at the appendix for possible solutions).

The file we're going to edit is /home/user/.config/menus/hildon.menu

You might want to backup the file, but it's not necessary - if you mess up, just delete the file and during the next boot routine it will be restored (actually, like with the files in the Hildon application folder, there's a system-wide and a user-specific version: if you delete the user-specific one, a copy of the system-wide will be copied in at boot time).

Take a deep breath and open the file in your text editor:
Code:
pygtkeditor /home/user/.config/menus/hildon.menu
If you've ever worked with XML files before, the original content of the file should look rather familiar. It's a structured representation of what the application menu should look like - that is, at the moment it simply displays all applications that are not displayed in another folder (well, and since there IS no other folder, it displays all of them).

We're going to overwrite this with our own code now:
Code:
<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN"
 "http://www.freedesktop.org/standards/menu-spec/menu-1.0.dtd">

<Menu>

  <Name>Main</Name>

  <!-- Search only in the hildon directory. -->
  <AppDir>/usr/share/applications/hildon</AppDir>
  <AppDir>/home/user/.local/share/applications/hildon</AppDir>
  <DirectoryDir>/usr/share/applications/hildon</DirectoryDir>
  <DirectoryDir>/home/user/.local/share/applications/hildon</DirectoryDir>

  <OnlyUnallocated/>
  <Include><All/></Include>

  <MergeDir>submenus</MergeDir>

</Menu>
Wait... that's all?

Actually, yes. This approach is very generic, which has the benefit that you only have to edit this file ONCE and never have to touch it again. If ever you feel like adding another folder (or editing/removing an existing one), you can switch this step completely. Less messing with standard files is always an advantage.

Let's take a short look at what the various parts of this XML coding actually do:
Code:
<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN"
 "http://www.freedesktop.org/standards/menu-spec/menu-1.0.dtd">
This simply tells the system what kind of file it has to expect and includes a link to a set of rules for the elements that are allowed in this file. If you want to know more, follow the link - else, just make sure you always have this at the top of your menu file.

Code:
  <!-- Search only in the hildon directory. -->
  <AppDir>/usr/share/applications/hildon</AppDir>
  <AppDir>/home/user/.local/share/applications/hildon</AppDir>
  <DirectoryDir>/usr/share/applications/hildon</DirectoryDir>
  <DirectoryDir>/home/user/.local/share/applications/hildon</DirectoryDir>
Here we tell Hildon where to look for the various files.

AppDir sets the director(y/ies) in which the .desktop files can be found that describe the various applications. Those files are similar to the .directory file we created earlier but also include shell code for actually starting the application when it is clicked.

DirectoryDir does the same for .directory files.

(As you can see, per default directories and applications are stored in the same folders.)

Code:
  <OnlyUnallocated/>
  <Include><All/></Include>
This is the part that makes sure that all applications are displayed in the main folder - but only when they are not already allocated to another folder.

Code:
  <MergeDir>submenus</MergeDir>
And that's our "variable" part. Instead of manually adding folders and applications, we simply tell Hildon to look for include-able .menu files in the submenus subfolder (/home/user/.config/menus/submenus).

Since there are no files in there (actually, right now not even the subfolder itself has been created), no folders will be displayed. That also means that none of the applications are allocated in any folders, so the current behaviour of Hilden will be:

Display all of the applications in the main folder. Great, all this work so far for nothing...

Still, let's save and exit back to X Terminal again.

Before we move one, here's a quick note on how fickle hildon.menu is: As soon as you touch the screen for too long while in the application menu, the new re-order feature will kick in. While normally quite the nice feature, in our case it means certain exodus for our beautiful folders, since it completely overwrites the hildon.menu file.

So, just in case this ever happens, let's create a backup file for this file:

Code:
cp /home/user/.config/menus/hildon.menu /home/user/.config/menus/hildon.backup
Step 4: Can we make our folder display now, please?

First we have to create the subfolder we stated above in the MergeDir tag:
Code:
mkdir /home/user/.config/menus/submenus
This will hold all the .menu files that will later be included. Whenever we add/delete/modify one of these, it will immediately influence our application menu - as stressed above, there's no necessity to touch the hildon.menu file again.

As proof of concept, create the .menu file for our Games folder:
Code:
pygtkeditor /home/user/.config/menus/submenus/games.menu
The content of this file will be a bit similar to the hildon.menu, since it's the same kind of XML file. Here's the framework for our Games folder:
Code:
<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN"
 "http://www.freedesktop.org/standards/menu-spec/menu-1.0.dtd">

<Menu>

  <Name>Main</Name>

  <Menu>
    <Name>Games</Name>
    <Directory>games.directory</Directory>
  </Menu>

</Menu>
The outer construct is the same as before, but instead of the folder declarations, the include and the directory merge there's a second Menu tag within the Main one.

That is actually our new subfolder, named Games (like the name we specified in the .directory file) and linked to the file games.directory - the one created before.

At this point the directory will be completely empty (and thus still all applications displayed in the main menu), but feel free to save and start the application menu to check whether the folder is already showing.

Then come back to your text editor for adding more content into the games.menu file.

Step 5: Into the folder you must go

Actually, before adding more content, let's exit the text editor and take a look at what we can actually add...

Remember the part about the .desktop files being stored in the same directories as the .directory files? With that knowledge we can now fetch a list of them by entering:

Code:
ls /usr/share/applications/hildon/
(Note: Again there's also the folder /home/user/.local/share/applications/hildon/ - so check in there, too, if you cannot find one of your applications.)

From that list, let's pick two games to add to our Games menu: maemoblocks.desktop and chess_startup.desktop - copy or not them down before you open games.menu in your text editor again:

Code:
pygtkeditor /home/user/.config/menus/submenus/games.menu
After the Directory tag (at the same level) we can now include those two applications:

Code:
    <Include>
      <Filename>maemoblocks.desktop</Filename>
      <Filename>chess_startup.desktop</Filename>
    </Include>
All the other games we might want to add later have to go between those Include tags, framed with their own Filename tags.

Your games.menu file should now look like this:

Code:
<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN"
 "http://www.freedesktop.org/standards/menu-spec/menu-1.0.dtd">

<Menu>

  <Name>Main</Name>

  <Menu>
    <Name>Games</Name>
    <Directory>games.directory</Directory>

    <Include>
      <Filename>maemoblocks.desktop</Filename>
      <Filename>chess_startup.desktop</Filename>
    </Include>

  </Menu>

</Menu>
Save, exit and... well, we're done! When you click the Games folder in the application menu, two icons should be displayed there: the Chess and Blocks application. In turn, those two should now be excluded from the main menu.

Rinse and repeat with as many folders as you would like to.

Last edited by Nathraiben; 2010-06-17 at 14:33.
 

The Following 16 Users Say Thank You to Nathraiben For This Useful Post: