Confirmed users
764
edits
Labs/Jetpack/Reboot/JEP/112: Difference between revisions
Small clarifications, copyediting
(→Specifying Contexts: Rearranged, clarified) |
(Small clarifications, copyediting) |
||
| Line 2: | Line 2: | ||
* Champion: Drew Willcoxon - adw at mozilla.com | * Champion: Drew Willcoxon - adw at mozilla.com | ||
* Status: Accepted/ | * Status: Accepted/Implementing | ||
* Bug Ticket: {{bug|548590}} | * Bug Ticket: {{bug|548590}} | ||
* Type: API | * Type: API | ||
| Line 35: | Line 35: | ||
** A tab-related extension adds an item that provides access to all the user's tabs. | ** A tab-related extension adds an item that provides access to all the user's tabs. | ||
** An extension adds an item when it's three o'clock. | ** An extension adds an item when it's three o'clock. | ||
* Radio and checkbox items. | * Radio and checkbox items. | ||
* The ability to modify the menu just before it's shown, and the ability to modify individual items already created by the extension. | * The ability to modify the menu just before it's shown, and the ability to modify individual items already created by the extension. | ||
* The ability to modify existing items other than to replace them with new items. | * The ability to modify existing items other than to replace them with new items. | ||
| Line 45: | Line 44: | ||
* Access to the browser's DOM, including popupshowing and popuphiding events. | * Access to the browser's DOM, including popupshowing and popuphiding events. | ||
* Menuitem icons should be package-able in XPIs, reference-able from code. | * Menuitem icons should be package-able in XPIs, reference-able from code. | ||
=== API Methods === | === API Methods === | ||
| Line 58: | Line 53: | ||
Adds an item to the context menu. The position at which the item is inserted is at the discretion of Jetpack. | Adds an item to the context menu. The position at which the item is inserted is at the discretion of Jetpack. | ||
; menuitem: The menuitem to add. See [[#Creating New Menuitems]]. | ; menuitem: The menuitem to add. See [[#Creating New Menuitems]]. <tt>Separator</tt>s, however, can't be added. | ||
==== insertBefore ==== | ==== insertBefore ==== | ||
| Line 94: | Line 89: | ||
Items should be added to the context menu, as its name implies, only when some particular context arises. Context can be related to page content or the page itself, but it should never be external to the page. (See [[#Non-Use Cases]] for examples.) | Items should be added to the context menu, as its name implies, only when some particular context arises. Context can be related to page content or the page itself, but it should never be external to the page. (See [[#Non-Use Cases]] for examples.) | ||
Instead of requiring consumers to manually add and remove items when particular contexts arise, this proposal introduces the notion that items are bound to one or more contexts, much as event listeners are bound to events | Instead of requiring consumers to manually add and remove items when particular contexts arise, this proposal introduces the notion that items are bound to one or more contexts, much as event listeners are bound to events. When the context menu is invoked, all of the items bound to the context giving rise to the menu are added to the menu. If no items are bound to the context, no items are added to the menu. This binding occurs through an item's context property. | ||
Contexts may be specified with any of the following types: | Contexts may be specified with any of the following types: | ||
| Line 144: | Line 139: | ||
<tt>Item(options)</tt> | <tt>Item(options)</tt> | ||
The <tt>Item</tt> constructor creates | The <tt>Item</tt> constructor creates simple menuitems. | ||
; options: An object that defines the following properties: | ; options: An object that defines the following properties: | ||
| Line 156: | Line 151: | ||
; icon: The URL of an icon to display in the menuitem. Optional. Note that some environments, [https://bugzilla.mozilla.org/show_bug.cgi?id=527253 notably Gnome 2.28], do not support menuitem icons either by default or at all. | ; icon: The URL of an icon to display in the menuitem. Optional. Note that some environments, [https://bugzilla.mozilla.org/show_bug.cgi?id=527253 notably Gnome 2.28], do not support menuitem icons either by default or at all. | ||
; label: The label of the menuitem, a string. | ; label: The label of the menuitem, a string. Required. | ||
; onCommand: An optional function that will be called when the menuitem is clicked. It is called as <tt>onCommand(contextObj, data)</tt>. <tt>contextObj</tt> is an object describing the context in which the menu was invoked. See [[#Context Descriptions]]. <tt>data</tt> is the item's <tt>data</tt> property. | ; onCommand: An optional function that will be called when the menuitem is clicked. It is called as <tt>onCommand(contextObj, data)</tt>. <tt>contextObj</tt> is an object describing the context in which the menu was invoked. See [[#Context Descriptions]]. <tt>data</tt> is the item's <tt>data</tt> property. | ||
| Line 176: | Line 171: | ||
; icon: The URL of an icon to display in the menuitem. Optional. Note that some environments, [https://bugzilla.mozilla.org/show_bug.cgi?id=527253 notably Gnome 2.28], do not support menuitem icons either by default or at all. | ; icon: The URL of an icon to display in the menuitem. Optional. Note that some environments, [https://bugzilla.mozilla.org/show_bug.cgi?id=527253 notably Gnome 2.28], do not support menuitem icons either by default or at all. | ||
; items: An array of menuitems | ; items: An array of menuitems that the submenu will contain. | ||
; label: The label of the menuitem, a string. | ; label: The label of the menuitem, a string. | ||
| Line 188: | Line 183: | ||
<tt>Separator(options)</tt> | <tt>Separator(options)</tt> | ||
The <tt>Separator</tt> constructor creates menu separators. | The <tt>Separator</tt> constructor creates menu separators. Separators can only be contained in <tt>Menu</tt>s; they can't be added to the top-level context menu. | ||
; options: An object that defines the following properties. If no properties are defined, then this argument is optional. | ; options: An object that defines the following properties. If no properties are defined, then this argument is optional. | ||
| Line 202: | Line 197: | ||
<span style="background-color: #fcc;"><em>This part of the proposal is under review.</em></span> | <span style="background-color: #fcc;"><em>This part of the proposal is under review.</em></span> | ||
Items that are part of the context menu by default are identified by case-sensitive IDs | Items that are part of the context menu by default are identified by case-sensitive strings IDs. | ||
TODO: Table of IDs, making up our own where XUL IDs don't exist, are inconsistent, or are ugly. What to do about non-Firefox apps? | TODO: Table of IDs, making up our own where XUL IDs don't exist, are inconsistent, or are ugly. What to do about non-Firefox apps? | ||
| Line 208: | Line 203: | ||
=== Context Descriptions === | === Context Descriptions === | ||
It would be useful if menuitem | It would be useful if menuitem callbacks had a way of examining the context in which they are invoked. For example, a command that downloads images needs to know the URL of the image that the user right-clicked when she opened the context menu. | ||
When a menuitem's | When a menuitem's callback is called, it is passed an object describing the context in which the context menu was invoked. This object has the following properties: | ||
<blockquote> | <blockquote> | ||