MenuItem¶

class rumps.MenuItem(title, callback=None, key=None, icon=None, dimensions=None, template=None)¶

Represents an item within the application’s menu.

A rumps.MenuItem is a button inside a menu but it can also serve as a menu itself whose elements are other MenuItem instances.

Encapsulates and abstracts Objective-C NSMenuItem (and possibly a corresponding NSMenu as a submenu).

A couple of important notes:

A new MenuItem instance can be created from any object with a string representation.

Attempting to create a MenuItem by passing an existing MenuItem instance as the first parameter will not result in a new instance but will instead return the existing instance.

Remembers the order of items added to menu and has constant time lookup. Can insert new MenuItem object before or after other specified ones.

Note

When adding a MenuItem instance to a menu, the value of title at that time will serve as its key for lookup performed on menus even if the title changes during program execution.

Parameters:

title – the name of this menu item. If not a string, will use the string representation of the object.
callback – the function serving as callback for when a click event occurs on this menu item.
key – the key shortcut to click this menu item. Must be a string or None.
icon – a path to an image. If set to None, the current image (if any) is removed.
dimensions – a sequence of numbers whose length is two, specifying the dimensions of the icon.
template – a boolean, specifying template mode for a given icon (proper b/w display in dark menu bar)

d[key]: Return the item of d with key key. Raises a KeyError if key is not in the map.

d[key] = value: Set d[key] to value if key does not exist in d. value will be converted to a MenuItem object if not one already.

del d[key]: Remove d[key] from d. Raises a KeyError if key is not in the map.

add(menuitem)¶: Adds the object to the menu as a rumps.MenuItem using the rumps.MenuItem.title as the key. menuitem will be converted to a MenuItem object if not one already.

callback¶: Return the current callback function.

New in version 0.2.0.

clear()¶: Remove all MenuItem objects from within the menu of this MenuItem.

get(k[, d]) → D[k] if k in D, else d. d defaults to None.¶

has_key(k) → True if D has a key k, else False¶

icon¶: The path to an image displayed next to the text for this menu item. If set to None, the current image (if any) is removed.

Changed in version 0.2.0: Setting icon to None after setting it to an image will correctly remove the icon. Returns the path to an image rather than exposing a PyObjC class.

insert_after(existing_key, menuitem)¶

Insert a rumps.MenuItem in the menu after the existing_key.

Parameters:	existing_key – a string key for an existing MenuItem value. menuitem – an object to be added. It will be converted to a MenuItem if not one already.

insert_before(existing_key, menuitem)¶

Insert a rumps.MenuItem in the menu before the existing_key.

Parameters:	existing_key – a string key for an existing MenuItem value. menuitem – an object to be added. It will be converted to a MenuItem if not one already.

items() → list of (key, value) pairs in od¶

iteritems()¶: od.iteritems -> an iterator over the (key, value) pairs in od

iterkeys() → an iterator over the keys in od¶

itervalues()¶: od.itervalues -> an iterator over the values in od

key¶: The key shortcut to click this menu item.

New in version 0.2.0.

keys() → list of keys in od¶

pop(k[, d]) → v, remove specified key and return the corresponding¶: value. If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), return and remove a (key, value) pair.¶: Pairs are returned in LIFO order if last is true or FIFO order if false.

set_callback(callback, key=None)¶

Set the function serving as callback for when a click event occurs on this menu item. When callback is None, it will disable the callback function and grey out the menu item. If key is a string, set as the key shortcut. If it is None, no adjustment will be made to the current key shortcut.

Changed in version 0.2.0: Allowed passing None as both callback and key. Additionally, passing a key that is neither a string nor None will result in a standard TypeError rather than various, uninformative PyObjC internal errors depending on the object.

Parameters:	callback – the function to be called when the user clicks on this menu item. key – the key shortcut to click this menu item.

set_icon(icon_path, dimensions=None, template=None)¶

Sets the icon displayed next to the text for this menu item. If set to None, the current image (if any) is removed. Can optionally supply dimensions.

Changed in version 0.2.0: Setting icon to None after setting it to an image will correctly remove the icon. Passing dimensions a sequence whose length is not two will no longer silently error.

Parameters:	icon_path – a file path to an image. dimensions – a sequence of numbers whose length is two. template – a boolean who defines the template mode for the icon.

setdefault(k[, d]) → od.get(k,d), also set od[k]=d if k not in od¶

state¶

The state of the menu item. The “on” state is symbolized by a check mark. The “mixed” state is symbolized by a dash.

Setting states¶
State	Number
ON	1
OFF	0
MIXED	-1

template¶: Template mode for an icon. If set to None, the current icon (if any) is displayed as a color icon. If set to True, template mode is enabled and the icon will be displayed correctly in dark menu bar mode.

title¶: The text displayed in a menu for this menu item. If not a string, will use the string representation of the object.

update(iterable, **kwargs)¶

Update with objects from iterable after each is converted to a rumps.MenuItem, ignoring existing keys. This update is a bit different from the usual dict.update method. It works recursively and will parse a variety of Python containers and objects, creating MenuItem object and submenus as necessary.

If the iterable is an instance of rumps.MenuItem, then add to the menu.

Otherwise, for each element in the iterable,

if the element is a string or is not an iterable itself, it will be converted to a rumps.MenuItem and the key will be its string representation.

if the element is a rumps.MenuItem already, it will remain the same and the key will be its rumps.MenuItem.title attribute.

if the element is an iterable having a length of 2, the first value will be converted to a rumps.MenuItem and the second will act as the submenu for that MenuItem

if the element is an iterable having a length of anything other than 2, a ValueError will be raised

if the element is a mapping, each key-value pair will act as an iterable having a length of 2

values() → list of values in od¶

viewitems() → a set-like object providing a view on od's items¶

viewkeys() → a set-like object providing a view on od's keys¶

viewvalues() → an object providing a view on od's values¶