SafariExtensionToolbarItem Class Reference

Inherits from
Technology area
Safari Extensions
Availability
Available in Safari 5.0 and later.

Overview

Instances of the SafariExtensionToolbarItem represent items that your extension adds to the Safari toolbar. Users can select which toolbar items are shown by selecting Customize Toolbar in the same way that they can add and remove toolbar items provided by Safari.

Tasks

Setting Up the Appearance

Using Menus and Popovers

Handling Click Events

Properties

badge

The current badge number.

attribute long badge
Discussion

The default value, 0, hides the badge. Badges can only display positive numbers. If you set a value that is too long, the beginning and the end of the value are shown, with an ellipsis in the middle.

Setting a value of NaN or Infinity is treated as 0. Non-integer values are rounded to the nearest integer.

Availability

browserWindow

The containing browser window.

readonly attribute SafariBrowserWindow browserWindow
Availability

command

The command identifier that the toolbar item sends when it is clicked.

attribute DOMString command
Discussion

This attribute is optional; its value defaults to the value of identifier.

Setting a value of null, undefined, or the empty string has no effect.

Availability

disabled

A Boolean value that indicates whether the toolbar item is disabled.

attribute boolean disabled
Discussion

The default value is false. Nothing happens when the user tries to interact with a toolbar item that is disabled.

Availability

identifier

The unique identifier of the toolbar item.

readonly attribute DOMString identifier
Discussion

This attribute is required.

Availability

image

The URL of the current image.

attribute DOMString image
Discussion

This attribute can be changed to the URL of an image in the extension bundle. Setting a value of null, undefined, or the empty string has no effect.

To support HiDPI, provide an image of the appropriate resolution at the same location, with the suffix @2x after its name. For example some/path/image-name@2x.png and some/path/image-name.png provide the same image at high resolution and standard resolution, respectively.

Availability

label

The label of the toolbar item, as shown in the toolbar’s overflow menu.

attribute DOMString label
Discussion

This attribute is required. Setting a value of null, undefined, or the empty string has no effect.

Availability

menu

The menu associated with this toolbar item.

attribute SafariExtensionMenu menu
Discussion

If the value of this property is null or undefined, no menu is displayed.

If the command attribute is defined, the menu is displayed when the user clicks and holds on the toolbar item; otherwise, it is displayed when the user clicks on the toolbar item.

A toolbar item may have either a menu or a popover, but not both; when you set the menu property, the popover property is set to null.

Availability

paletteLabel

The label of the toolbar item, as shown in the Customize palette.

readonly attribute DOMString paletteLabel
Discussion

This attribute is optional; its value defaults to the value of label.

Availability

popover

The popover associated with the toolbar item.

attribute SafariExtensionPopover popover
Discussion

If the value of this property is null or undefined, no popover is displayed.

If the command attribute is defined, the popover is displayed when the user clicks and holds on the toolbar item; otherwise, it is displayed when the user clicks on the toolbar item.

A toolbar item may have either a popover or a menu, but not both; when you set the popover property, the menu property is set to null.

Availability

toolTip

The tooltip (help tag) of the toolbar item.

attribute DOMString toolTip
Discussion

This attribute is optional; its value defaults to the value of label.

Setting a value of null, undefined, or the empty string has no effect.

Availability

Methods

showMenu

Shows the menu for the toolbar item.

void showMenu ();
Discussion

If the value of the menu property is null or undefined, no menu is displayed.

Availability
  • Available in Safari 5.1 and later.

showPopover

Shows the popover for the toolbar item.

void showPopover ();
Discussion

If the value of the popover property is null or undefined, no popover is displayed.

Availability
  • Available in Safari 5.1 and later.

validate

Dispatches a validate event for this toolbar item.

void validate ();
Discussion

You should call this method after a state change occurs that is relevant to your validate-event listeners. Safari also automatically sends validate events for many common browser actions, such as switching tabs and navigating to a new page.

Availability
  • Available in Safari 5.0 and later.