Now that menu API is more or less solid, I thought it's time to write down some guidelines. Should be useful both for developing new stuff and for polishing old features.
Feel free to come up with better suggestions, or post some screenshots that I could reuse to illustrate the points below. However, if you feel like suggesting some facelift or a new keybinding, it may be a good idea to use this thread:
http://www.magiclantern.fm/forum/index.php?topic=4386.325Clutter:- (I start with this because I think it's the biggest usability problem right now)
- Think twice before adding YAMLMO (yet another ml menu option). There are already hundreds (if not one thousand).
- Try to avoid vertical scrolling (otherwise you can no longer see at a glance what settings are enabled).
- If you end up with a menu with lots of items, hide less-common options under the Advanced option, or in a submenu.
Submenus: (now we have multi-level submenus too)
- Prefer a top-level boolean option that turns your feature on and off, and put all the settings in the submenu.
- Sometimes you need a submenu just for grouping some items (e.g. benchmarks, or some general preferences), but there's no feature to be turned on and off. That's fine too. Try to put these items at the end of the menu though.
- Try to summarize the important submenu settings in the top-level menu (so you can tell at a glance what setting you are using). Example: most items from Shoot and Overlay menus.
- Do not abuse multi-level submenus: unrolled menu structures are generally quicker to navigate and easier to survey.
Values:- Prefer pickboxes whenever possible (tip: use the
CHOICES macro).
- Try to provide reasonable default settings (make your feature usable out of the box).
- When the toggled variable (.priv) is 0, try to interpret this setting as "OFF" (of course, only if it makes sense).
- Make sure your setting appears on the Delta menu when you change it from default, and also make sure it disappears from there when you go back to default value.
- Use reasonable .min and .max limits (e.g. instead of providing 1000 choices, try to select 5 or 10 choices that will make a difference).
Icons:- in most cases, the icon type is autodetected (you may override it if autodetection is not smart enough)
-
IT_ACTION: when you click on the item and something starts running (e.g. a task); do not use it for things that can be toggled on or off, for example.
- IT_BOOL: simplest setting (you toggle it on or off)
- IT_PERCENT: a scalar value (quantity)
- IT_PERCENT_OFF: a scalar value with an OFF position (zero is interpreted as OFF)
- IT_DICE: a set of discrete choices without an OFF position (historically this was represented by a dice icon)
- IT_DICE_OFF: a set of discrete choices with an OFF position.
- IT_SUBMENU: on submenus without top-level value.
Colors:- green: something that can be turned off
- light blue: something that can't be turned off
- if an item is turned off, its value should be grayed out (but not its name)
- if an item can't be used in the current context, gray it out completely (see below)
Warnings:- if an item can't be used (e.g. a photo-only feature in movie mode), gray it out
(MENU_WARN_NOT_WORKING) and explain what to do in order to use it.
- use
depends_on to check for some common things like LiveView or movie/photo mode, and use a
MENU_UPDATE_FUNC for more complex logic.
- you can provide usage tips
(MENU_WARN_INFO), especially non-obvious stuff.
Alignment:- Try to keep the menus nicely aligned (just like you do with code indentation)
- Extend submenu_width as needed (so your menu feels neither too cramped nor too loose - just right)
Ordering:- Try to group similar items (avoid things like boolean/action/boolean/action/scalar, try boolean/boolean/scalar/action/action instead)
- Try to move action items at the end of the menu
- Same for grouping submenus (try to place them at the end of the menu)
Help:- Each item should include a short description (
.help, optionally .help2).
- For items with multiple choices, help2 can be used to describe every single choice (simply describe one choice per line).
- Make sure the help text actually fits on the screen!
- For modules: also include a short description in the README.rst file (
details here). Make sure your description fits in the ML menu!