Safari Developer Library

Developer

SafariExtensionToolbarItem Class Reference

Options
Deployment Target:

On This Page

SafariExtensionToolbarItem

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.

Inheritance


Conforms To


Not Applicable

Import Statement


Not Applicable Not Applicable

Availability


Available in Safari 5.0 and later.
  • badge Property

    The current badge number.

    Declaration

    JavaScript

    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

    Available in Safari 5.0 and later.

  • image Property

    The URL of the current image.

    Declaration

    JavaScript

    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

    Available in Safari 5.0 and later.

  • label Property

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

    Declaration

    JavaScript

    attribute DOMString label

    Discussion

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

    Availability

    Available in Safari 5.0 and later.

  • paletteLabel Property

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

    Declaration

    JavaScript

    readonly attribute DOMString paletteLabel

    Discussion

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

    Availability

    Available in Safari 5.0 and later.

  • toolTip Property

    The tooltip (help tag) of the toolbar item.

    Declaration

    JavaScript

    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

    Available in Safari 5.0 and later.

  • menu Property

    The menu associated with this toolbar item.

    Declaration

    JavaScript

    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

    Available in Safari 5.1 and later.

  • popover Property

    The popover associated with the toolbar item.

    Declaration

    JavaScript

    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

    Available in Safari 5.1 and later.

  • Shows the menu for the toolbar item.

    Declaration

    JavaScript

    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.

  • Shows the popover for the toolbar item.

    Declaration

    JavaScript

    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.

  • browserWindow Property

    The containing browser window.

    Declaration

    JavaScript

    readonly attribute SafariBrowserWindow browserWindow

    Availability

    Available in Safari 5.0 and later.

  • command Property

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

    Declaration

    JavaScript

    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

    Available in Safari 5.0 and later.

  • disabled Property

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

    Declaration

    JavaScript

    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

    Available in Safari 5.0 and later.

  • identifier Property

    The unique identifier of the toolbar item.

    Declaration

    JavaScript

    readonly attribute DOMString identifier

    Discussion

    This attribute is required.

    Availability

    Available in Safari 5.0 and later.

  • Dispatches a validate event for this toolbar item.

    Declaration

    JavaScript

    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.