View source for Minimenu

Minimenu is a [[GUI]] (window manager) designed for the Pandora box. It is designed like a user interface for the most game consoles, so it is quite easy to launch software. On the other hand it hasn't all the features of the full blown XFCE GUI so assistants etc. are missing.
[[Image:Minimenu_Games.png|thumb]]

[[PND]]s get recognized and grouped by their categories.
You can customize settings and use different skins: [[Minimenu#Skinning_the_Interface]]

*[http://www.youtube.com/watch?v=h4lB3tkIFwY Video about Minimenu]

== Interesting Menu Items for General Usage ==

=== Force all preview caching now ===

With default configuration, preview pictures will be pulled in as you rest the selection on applications (and not during menu load time, since it is too slow to do that, currently.) When pulled in, a preview pic is cached to RAM (so is instant for pulling up this session again). With default configuration, the preview pic will also attempt to cache out to SD card so that even next session of the menu, it will pull up very quickly (partial second.) However, that very first time you pull up any given preview pic, it will take a few seconds to load due to mounting the pnd-application, looking for the preview inside, and unmounting the application.

The Force All Preview option is in the Select menu; this option allows you to take the preview caching hit right away, for all applications. Trigger this option, then ignore your Pandora for a couple minutes while it chugs away.

Upon completion, all pnd-applications containing Previews should have them in their SD cache (assuming you had sufficient space free.) What this means is that pulling up preview pics should be instant for this sesssion, and very fast for future sessions as well.. no more waiting a few seconds for the first time pull up of a preview picture.

=== Overriding application details ===

An [[.ovr]] file may be created in the same location as a [[pnd]]-application, with the same name except for .ovr at the end -- an application named "Foo.pnd" could have an override file named "Foo.ovr"; that file is mostly handled by libpnd (See above for details), but minimenu extends it to support "Notes".

See the example below; [[Introduction_to_PNDs#I_want_to_override_the_.PND_icon.2C_name.2C_or_other_settings.2C_how_is_this_done.3F]]


==== Preview picture ====

[[Libpnd hub]] does not handle preview picture overrides, so [[minimenu]] does this on its own.

In the same location as a pnd file, a preview override may be specified.

If the pnd-file is named "Foo.pnd", minimenu will look for Foo_pvw#0.png for "subapp 0"'s preview. "Subapp 1"'s preview would be checked for as "Foo_pvw#1.png"

== Default configuration is.. ==

* Runs without X, and with X.
* Look for applications in the Pandora normal places; your SD cards, in /pandora/desktop and /pandora/menu and /pandora/apps
* Look for additional apps in /pandora/mmenu (say, if you want to have minimenu-only applications, for some reason)
* Look for skins in /etc/pandora/mmenu/skins (on Pandora), but also in SD in /pandora/mmenu/skins/ -- so you can develope skins, or download them and drop them there on your SD.
* Will show pnd-applications in their Main Category tab, and in their Main Sub Category 1 tab. (But not in Main Sub 2, or Alt Category, Alt Sub 1, or Alt Sub 2)
* Will show an "All" tab
* Will show a tab for each non-empty directory in /media -- ie: your SD cards (or USB devices, or other mounts)
* Will not wrap tabs -- when you hit right-trigger to switch to the next right tab, and there are no more, it won't go to the first tab
* Will use DaveC's skin
* Will load application icons when the menu starts up (its pretty fast, so this is usually okay)
* Will load preview pics after the selection rests on an application in the grid for a second or two (ie: not on startup, since it is _very slow_)
* Will try to cache preview pics onto SD card (firstly on the same SD as the application, but will also search other SDs/devices until it finds one with at least 500KB free space)
* Will load preview pics in real time (make you wait while it loads, not do it in background while you do other stuff.)
* Will scroll whole page of the grid up and down
* Will wrap around left/right of grid, staying on same row
* Will wrap around top/bottom of the grid
* Will look for 'category conf' file in /pandora/mmenu on your SDs as mmcatmap.conf; most people will never create this file
* Will honour icon overrides and icon name, category overrides (this is handled by libpnd before minimenu sees it.) However, will also look in the ovr file for 'notes' to show in the Detail panel, and will also look for "preview overrides".

== Global/User Preferences ==

Users will generally not have to touch '''mmenu.conf''' at all -- hopefully the defaults are sensible. Still, it can be tweaked.

Skinners will generally touch '''mmskin.conf''' in their skin's directory, and WILL NOT put options in their that belong in the other conf files. Thus we achieve separation -- user can change skins and still have their settings applied, and the skin can change its appearance its own way without depending on user mucking with files.

Minimenu will search for mmenu.conf in a sequence of locations, so that you may override it without clobbering the built in system defaults.
# /pandora/mmenu/mmenu.conf - so you can override it on your SD cards
# /etc/pandora/conf/mmenu.conf - the system default
# ./minimenu/mmenu.conf - so you can run from 'current directory' while doing development. Most people can ignore this.

Options in minumenu are broken up into config file sections.

Most options have internal defaults, but many do not, so the conf files are needed; if you break a conf file, it will often still work.. but you can make minimenu crash, so be careful and keep conf file backups. It is probably wise to edit conf files via the override on SD cards, and put skins on SD cards, so that worst case.. pop out your SD and you're good to go with default system again.

=== [minimenu] section ===

{|class="wikitable"
!Entry!!Values
|-
|skin_searchpath||defines the directories that will be searched to find skin-directories. A skin directory is a _directory containing mmskin.conf_ so searchpath may include /media/*/pandora/mmenu/skins to mean that SD cards will be searched in /pandora/mmenu/skins - a skin named "Foo" will then be /pandora/mmenu/skins/Foo/ and contain mmskin.conf
|-
|skin_selected||defines where to store the name of the activated skin; if this file does not exist, or the named skin cannot be found, the skin named 'default' will be searched for in skin_searchpath
|-
|skin_confname||the name of the conf file to look for in skins; if you change this, everything will break :)
|-
|load_previews_new||if set to >0, will attempt to load preview pics _at startup of menu every time_ -- EXTREMELY SLOW for un-cached previews; if, however, you have recently done a "force cache all previews", and thus are fully cached, it might not be too bad. Highly unadvisable.
|-
|load_previews_later||if set to >0, will want to load preview pics later; if set to 0, will not even try to load preview pictures, ever.
|-
|load_icons_later||if set to >0, will attempt to load icons after menu starts; normally set to 0, meaning load icons during menu startup (advisable, since its pretty fast.)
|-
|defer_icon_us||when load_icons_later is activated, this is the microseconds delay between loading icons. (ie: background thread will load icon, then another icon, then another .. with this delay between)
|-
|threaded_preview||if set to >0, will load preview pics in background; not advisable. Normally will make you wait while preview happens. First releases of Pandora will probably take a few seconds to load each preview, and doing it in background chugs the user experience too much. (A later improvement to pnd_run.sh or creating a fast-mount script that skips the Union Filesystem Mount will make preview loading MANY times faster, at which point this might be a good option.)
|-
|loglevel||if you wish to turn up or down the logging
|-
|x11_present_sh||define the command used to figure out if X is present or not; some apps require X, or require no X, or don't care; the menu may decide to filter out apps depending on their requirements and whethor X is running or not
|-
|desktop_apps||if set to >0, will look in the desktop searchpath for apps (/pandora/desktop say; see /etc/pandora/conf/desktop)
|-
|menu_apps||if set to >0, will look in menu searchpath too -- see /etc/pandora/conf/desktop
|-
|aux_searchpath||if you wish to look somewhere else for applications entirely (such as for minimenu specific apps? or another pile of apps?) then look in this searchpath
|}

=== [utility] Section ===
{|class="wikitable"
!Entry!!Values
|-
|terminal|| specifies the command to run when the Select menu is used and user requests to run a Terminal; ie: you could set it to Xterm, or Konsole, or Terminal, or whatever you prefer.
|-
|}

=== [display] Section ===
{|class="wikitable"
!Entry!!Values
|-
|fullscreen||if >0, will attempt to grab the full screen and have no window decorations when in X11; if 0, will be a normal window that you can flip to other windows
|-
|screen_width||used for calculation of a few defaults; don't mess with it.
|}

=== [tabs] Section ===
{|class="wikitable"
!Entry!!Values
|-
|wraparound||if >0, will wrap from leftmost tab to rightmost tab and vice-versa, when trying to switch tabs using the triggers. Normally will just stop at left/rightmost tabs
|-
|top_maincat||if >0, will include apps in the tab for their main category
|-
|top_maincat1||if >0, will include apps in the tab for their main categories first subcategory
|-
|top_maincat2||if >0, will include apps in the tab for their main categories second subcategory
|-
|top_altcat||if >0, will include apps in the tab for their alternate category
|-
|top_altcat1|| if >0, will include apps in the tab for their alternate categories first subcategory
|-
|top_altcat2 || if >0, will include apps in the tab for their alternate categories second subcategory
|}

=== [grid] Section ===
{|class="wikitable"
!Entry!!Values
|-
|scroll_increment||when scrolling the grid up/down, how many rows to scroll by
|-
|wrap_horiz_samerow||when wrapping left/right on the grid, stay on same row or go to next/previous row?
|-
|wrap_vert_stop ||if set >0, will not wrap top/bottom when user pressing up/down
|}

=== [previewpic] Section ===

{|class="wikitable"
!Entry!!Values
|-
|defer_timer_ms || the amoung of time (milliseconds) that the user most leave the selection in one place before the menu goes to pull up the preview pic (either from RAM cache, SD cache or pnd-file if not yet cached)
|-
|do_cache || if set to >0, will attempt to cache preview pics from pnd apps out to SD for faster loading next session (ie: in first release of the device, pulling preview from pnd may take 3-4 seconds, but pulling from SD cache may take half-second)
|-
|cache_searchpath || the list of locations to attempt to _cache to_ -- after pulling a preview pic, try to stick the preview here for faster retrieval; note that it will always try the same drive as the app came from first, to try to keep the preview in the same SD as the pnd is.
|-
|cache_minfree || the amount of space required to make the SD usable for caching too; ie: this is designed so the cache will not use up your vary last amount of space on an SD. If space is insufficient, the next location in cache_searchpath will be checked
|-
|cache_path || the location to write the cached preview pics out to, relative to the matching searchpath; ie: If a pnd-file is on SD2, it will first try SD2, and then check SD1 and go across the searchpath; once a candidate is found (if!), then the cache_path on that device will be used
|-
|cache_findpath || the searchpath that helps the menu find the previews; should work out to the same locations as covered by cache_searchpath but include the full cache_path as well, but could also include other locations should you have downloaded pre-cached previews or preview overrides
|}

=== [categories] Section ===
{|class="wikitable"
!Entry!!Values
|-
|catmap_searchpath || the searchpath to be looked through to find the mmcatmap.conf file (which need not exist at all.)
|-
|catmap_confname || should you wish to rename the mmcatmap.conf file for some reason
|-
|do_all_cat || if >0, will show an "All" tab to which all applications will be sent (in addition to their other categories as defined in [tabs] above
|}

=== [filesystem] Section ===

{|class="wikitable"
!Entry!!Values
|-
|do_browser || if >0, the directory browser will be enabled
|-
|tab_searchpaths || the list of directories that will be opened for browsers, and each will have its own tab
|}

Note the examples:
NOTE: to keep from having a million tabs, minimenu will only show directory browser tabs that are non-empty
# if tab_searchpaths is just "/media", then one tab ("/media") will be created, and you can browse that
# if you put "/media/*", then one tab will be created for each subdir in /media (one per SD, plus USB and other mounts)
# you could make the browser point to many locations, such as "/media/*:/:/home" which would show one for each /media subdir, as well as a tab for / (root of filesystem), as well as /home (show one to contain all home directories.)

== Setting up Category Mapping/Merging/Aliasing and Custom Tabs ==

An optional conf file may be created to specify 'category mapping' functionality.

This conf file should be called mmcatmap.conf (unless the name has been changed in mmenu.conf), and should be located in one of the following locations (unless an alternate searchpath has been specified in mmenu.conf)
# On your SD cards in /pandora/mmenu/mmcatmap.conf
# on device in /etc/pandora/mmenu/mmcatmap.conf
# ./minimenu (relative to current working directory) as mmcatmap.conf -- really only useful for developers

The goals of the mmcatmap.conf are a few..
# Allow renaming or aliasing categories (from what developers specify in pnd-applications PXML.xml)
# Allow merging categories (so you can put apps that would be across 5 catrgories, into 3 of your own design)
# Allow order of tabs to be specified (rather than be 'random' as determined from applications)

Applications are _encouraged_ (but not forced) to stick to Freedesktop Category Standards (and should stick to syntax standard.. ie: no spaces, etc.) So in general you should encounter a limited number of categories (not "Foofy123!" but things like "Games" with subcategory "Emulator". See PXML.xml specification for guidelines.) However, developers may specify whatever they like into the PXML.xml and perhaps you disagree or wish to use your own category/tab assignments.

=== Note on category overrides ===

There are two main kinds of overrides in this context:
# A per-pnd (and per-subapplication) override; see .ovr files above and below for how to override a category of a specific application
# A per-category override; that is what mmcatmap.conf is for, read on!

=== Example mmcatmap.conf ===

<source lang="apache">
[categories]
# Normally for mmenu, an encountered category is just used as is. 5 cats exist, you get 5 tabs.
# If map_on is >0, then category transforms will occur
#   @NEWCAT oldcat1:oldcat2      <- means oldcat1, if found, will map to NEWCAT. "@" is discarded.
#   NOTE: FreeDesktop rules do not allow categories with spaces in the name; if needed, I can add it with quoting.
# If map_default_on is set (>0), then any unmapped categories will be forced into the default category bucket (map_default_cat.)
#   If map_default_on is off (=0), then unmapped categories will become their own categories as normal.
#   Should probably still have an @ line to create the default category, since creating the cats comes before assigning defaults
# NOTE: Individual app overrides occur at the time of app scanning, so before this category mapping occurs and thus is effected
map_on                  0               # if >0, will do category mapping at all; if 0, don't do any of this.
map_default_on          0               # if >0, any unmapped category will get forced to map_default_cat; set to 0 to leave unmapped cats alone
map_default_cat         Spam            # see map_default_on
# NOTE: List the categories in reverse order to how you wish them in the tab list; last one shows up as first tab
@Woogle                 Audio
@Jimmy                  Game
@Spam
</source>

* map_on -- if >0, will turn category magic on; by default, this file and section is ignored.
* map_default_on -- if >0, means that any category not otherwise mapped will be sent to the map_default_cat category. ie: So you must now define mappings for all tabs to _keep_
* map_default_cat -- the name of the category that all not-explicitly-mapped categories will be sent to, if map_default_on is set (similar to how "All" tab works)

The main goods are the config entries starting with "@"

NOTE: The tabs in the config should be listed in reverse order to how you wish them displayed. In the example above, you will get tabs "Spam", "Jimmy", "Woogle", even though they are listed Woogle, then Jimmy, then Spam.

The format is:
@TABNAME<whitespace>category1:category2:category-etc-etc

example: Map the category "Audio" to be instead called "Woogle".
<pre>
@Woogle Audio
</pre>

example: Map the category "Game" and "Audio" to instead be called "Multimedia"
<pre>
@Multimedia Game:Audio
</pre>

NOTE: In the large example above, note that the "default" is specified to be "Spam", and if enabled, you then need to define "@Spam" tab for it to refer to (even if nothing is mapped to it in the @Spam line itself.)

NOTE: The categories will at first come from the pnd-applications (in their PXML.xml as specified by the developer), and then possibly be overriden by the .ovr file. This is at the libpnd level before minimenu ever catches wind of the application. Then during application discovery, minimenu will get a list of categories and applications, and pass them through mmcatmap.conf to determine the final list of tabs and categories to use.

Consider: If two pnd-files ezist, as in AwesomeGame in category Game, and SoundOff in Audio, you will normally get two tabs (Game and Audio), plus an All tab, plus a /media/mmcblk1p1 tab for SD1 (say.) If you then put in mmcatmap.conf a line "@Foo Audio", then you will essentially rename Audio to "Foo", and still get two tabs - Game and Foo. You could create a new tab with "@Whizzo Audio:Game" to merge those two categories into one new one called Whizzo, instead.

== Skinning the Interface ==

Skinning guide in gp32x forum: http://www.gp32x.com/board/index.php?/topic/53990-skinning-minimenu/

A mmskin.conf from February 2011: http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=blob;f=minimenu/skin/default/mmskin.conf;h=695888b3ae310d7ea04b4e682baed0c0c6fc4349;hb=98c1d081629ac9cbb3056b39097a3db968ce4055

=== Setting up a skin you download ===

=== Creating new skins ===

== adding new new launchers ==
[http://www.gp32x.com/board/index.php?/topic/54647-guide-add-custom-launchers-to-the-main-menu/page__view__findpost__p__880004 add custom launchers add custom launchers]


[[Category:Operating system]]
[[Category:Documentation]]
[[Category:GUI]]