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 therumps.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 isNone
, 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 norNone
will result in a standardTypeError
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.
¶ 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 toTrue
, 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 usualdict.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 itsrumps.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
- if the element is a string or is not an iterable itself, it will be converted to a
-
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¶