This element is used for the tooltip popups. For text-only tooltips, this element doesn't need to be used; instead you may just add a tooltiptext
attribute to an element.
More information is available in the XUL tutorial.
- Attributes
- crop, default, label, noautohide, onpopuphidden, onpopuphiding, onpopupshowing, onpopupshown, page, position
- Properties
- accessibleType, label, popupBoxObject, position, state
Examples
<tooltip id="moretip" orient="vertical" style="background-color: #33DD00;"> <label value="Click here to see more information"/> <label value="Really!" style="color: red;"/> </tooltip> <vbox> <button label="Simple" tooltiptext="A simple popup"/> <button label="More" tooltip="moretip"/> </vbox>
Attributes
-
crop
- Type: one of the values below
-
If the label of the element is too big to fit in its given space, the text will be cropped on the side specified by the
crop
attribute. An ellipsis will be used in place of the cropped text. If the box direction is reversed, the cropping is reversed. -
-
start
- The text will be cropped on its left side in left-to-right text locales, and the right side in right-to-left locales.
-
end
- The text will be cropped on its right side in left-to-right text locales, and the right side in right-to-left locales.
-
left
- The text will be cropped on its left side.
-
right
- The text will be cropped on its right side.
-
center
- The text will be cropped in the middle, showing both the start and end of the text normally.
-
none
- The text will be not be cropped using an ellipsis. However, the text will simply be cut off if it is too large. The side depends on the CSS text alignment.
-
-
Depending on the platform and theme being used, some elements will have set a maximum width so they will always appear cropped. If you wish to use the value
none
and the displayed text is larger than this maximum width, you may be able to use the max-width CSS property (or the maxwidth attribute) to override this size. For example, for a menuitem in a menu you can add the following CSS rule when you want to use the valuenone
: -
menupopup > menuitem, menupopup > menu { max-width: none; }
-
label
- Type: string
-
The label that will appear on the element. If this is left out, no text appears. For an editable
menuitem
element the value of this attribute is copied to themenulist
.value property upon user selection of themenuitem
.
-
noautohide
- Type: boolean
- If this attribute is set to
false
or omitted, thetooltip
will automatically disappear after a few seconds. If this attribute is set totrue
, this will not happen and the tooltip will only hide when the user moves the mouse to another element.
-
onpopuphiding
- Type: script code
- This event is sent to a popup when it is about to be hidden.
-
onpopupshowing
- Type: script code
- This event is sent to a popup just before it is opened. This handler is usually used to dynamically set the contents when the user requests to display it. Returning
false
from this event handler prevents the popup from appearing.
-
onpopupshown
- Type: script code
- This event is sent to a popup after it has been opened, much like the
onload
event is sent to a window when it is opened.
-
page
- Type: boolean
-
Setting the
page
attribute to true will result in the tooltip being filled automatically as appropriate for abrowser
content area tooltip, i.e. the tooltip text is set according to the DOM element in the browser that the user hovered over.
Example
<tooltip id="pageTooltip" page="true"/> <browser tooltip="pageTooltip"/>
-
position
- Type: string
-
The
position
attribute determines where the popup appears relative to the element the user clicked to invoke the popup. This allows you to place the popup on one side of a button. Note that a context menu will never respect this attribute, always appearing relative to the mouse cursor. -
This value can be specified either as a single word offering pre-defined alignment positions, or as 2 words specifying exactly which part of the anchor and popup should be aligned. -
If specified as 2 words, the value indicates which corner or edge of the anchor (the first word) is aligned which which corner of the popup (the second word). The anchor value (ie, the first word) can be one oftopleft
,topright
,bottomleft
,bottomright
,leftcenter
,rightcenter
,topcenter
orbottomcenter
. The popup value (ie, the second word) can be one oftopleft
,topright
,bottomleft
orbottomright
. -
Positions specified as a single word string are shortcuts for the values above. Valid single-word values areafter_start
,after_end
,before_start
,before_end
,end_after
,end_before
,start_after
,start_before
,overlap
,at_pointer
orafter_pointer
. - For more details, including examples, please see popup positioning
Properties
-
accessibleType
- Type: integer
- A value indicating the type of accessibility object for the element.
-
popupBoxObject
-
Type:
nsIPopupBoxObject
-
This read-only property holds the
nsIPopupBoxObject
that implements the popup. You wouldn't normally need to use this property as all of its functions are available via the popup itself.
-
state
- Type: string
-
This read only property indicates whether the popup is open or not. Four values are possible:
closed
: The popup is closed and not visible.open
: The popup is open and visible on screen.showing
: A request has been made to open the popup, but it has not yet been shown. This state will occur during the popupshowing event.hiding
: The popup is about to be hidden. This state will occur during the popuphiding event.
Methods
-
hidePopup()
- Return type: no return value
- Closes the popup immediately.
-
moveTo( x, y )
- Return type: no return value
- Moves the popup to a new location defined by screen coordinates (and not client coordinates).
- If both x and y have the value -1 the call will realign the popup with its anchor node.
-
openPopup( anchor , position , x , y , isContextMenu, attributesOverride, triggerEvent )
- Return type: no return value
Opens the popup relative to a specified node at a specific location.
- anchor
-
The popup may be either anchored to another node or opened freely. To anchor a popup to a node, supply an anchor node and set the position to a string indicating the manner in which the popup should be anchored. The anchor node does not need to be in the same document as the popup. Unanchored popups may be created by supplying
null
as the anchor node. The direction in which the popup is oriented depends on the direction of the anchor. - position
-
Possible values for position are:
before_start
,before_end
,after_start
,after_end
,start_before
,start_after
,end_before
,end_after
,overlap
, andafter_pointer
. Check Positioning of the Popup Guide for a precise description of the effect of the different values. - x, y
-
For an anchored popup, the
x
andy
arguments may be used to offset the popup from its anchored position by some number, measured in CSS pixels. An unanchored popup appears at the position specified by x and y, relative to the viewport of the document containing the popup node. In this case, theposition
andattributesOverride
arguments are ignored. - isContextMenu
-
The
isContextMenu
argument should betrue
for context menus andfalse
for all other types of popups. It affects menu item highlighting; that is, while a context menu is open, menus opened earlier do not highlight or execute their items. - attributesOverride
-
If the
attributesOverride
argument istrue
, the position attribute on the popup node overrides theposition
value argument. IfattributesOverride
isfalse
, the attribute is only used if theposition
argument is empty. - triggerEvent
- The event that triggered the popup (such as a mouse click, if the user clicked something to open the popup).
-
openPopupAtScreen( x, y, isContextMenu )
- Return type: no return value
- Open the popup at a specific screen position specified by x and y. This position may be adjusted if it would cause the popup to be off of the screen. The x and y coordinates are measured in CSS pixels.
-
showPopup( element, x, y, popupType, anchor, align )
Deprecated since Gecko 1.9 -
Return type: no return value
Deprecated in favor of openPopup and openPopupAtScreen -
Opens a popup element. There are two ways of specifying where the popup appears, either at a specific screen position, or relative to some element in the window. If either x or y are set to values, the popup will appear at the screen coordinate (x,y). If x and y are
-1
, the popup will be positioned relative to the element specified as the first argument. This is what you might do to show a popup below a button, for example. In this latter case, the anchor and align arguments may be used to further control where the popup appears relative to the element. The anchor argument corresponds to thepopupanchor
attribute on the element. The align argument corresponds to thepopupalign
attribute on the element. The anchor and align arguments are ignored if either x or y are not-1
.
-
To have a popup appear relative to another element yet still offset by some number of pixels, determine the actual screen position of the element using the
boxObject
.screenX andboxObject
.screenY properties of the element, and use those as the x and y arguments offset by the desired values.
-
The popupType should be either the string
popup
,context
, ortooltip
. Each type of popup is intended to be displayed only temporarily; they are not expected to be displayed permanently. Only one popup may be displayed at a time.
-
sizeTo( width, height )
- Return type: no return value
- Changes the current size of the popup to the new width and height.
Related
TBD