Home > Element Reference : Tabbrowser

Contents

### Tabbrowser

This element is used for holding a set of read-only views of Web documents. Similar to the browser element, except that multiple documents can be displayed, each in a separate tab. This element is implemented as a set of browser elements inside a tabbox.

Attributes:

autocompleteenabled | autocompletepopup | autoscroll | contentcontextmenu | contenttooltip
handleCtrlPageUpDown | onbookmarkgroup | onnewtab

Properties and Methods:

| addProgressListener | addTab | appendGroup | browsers
canGoBack | canGoForward | contentDocument | contentTitle | contentViewerEdit
contentViewerFile | contentWindow | currentURI | docShell | documentCharsetInfo
getBrowserForTab | goBack | goBackGroup | goForward | goForwardGroup
goHome | gotoIndex | homePage | loadGroup | loadURI
loadURIWithFlags | markupDocumentViewer | reload | reloadAllTabs | reloadTab
reloadWithFlags | removeAllTabsBut | removeCurrentTab | removeProgressListener | removeTab
replaceGroup | securityUI | selectedBrowser | selectedTab | sessionHistory
stop | tabContainer | webBrowserFind | webNavigation | webProgress

#### Attributes:

Inherited from XUL Element:

align
allowevents
allownegativeassertions
class
coalesceduplicatearcs
collapsed
container
containment
context
contextmenu
datasources
dir
empty
equalsize
flags
flex
height
hidden
id
insertafter
insertbefore
left
maxheight
maxwidth
menu
minheight
minwidth
mousethrough
observes
ordinal
orient
pack
persist
popup
position
preference-editable
ref
removeelement
sortDirection
sortResource
sortResource2
statustext
style
template
tooltip
tooltiptext
top
uri
wait-cursor
width

##### autocompleteenabled Firefox only

Type: boolean

Set to true to enable autocomplete of fields.

##### autocompletepopup

Type: id of popup element

The id of a popup element used to hold autocomplete results for the tabbrowser.

##### autoscroll Firefox only

Type: boolean

Set to false to disable autoscroll for this tabbrowser. If this attribute is set to true or omitted, autoscroll will be enabled or depending on the user preference 'general.autoScroll'.

##### contentcontextmenu

Type: id of a menupopup element

A reference to the context menu for the content area in the tabbrowser.

##### contenttooltip

Type: id of a tooltip element

A reference to the tooltip element to be used for the content area in the tabbrowser.

##### handleCtrlPageUpDown

Type: boolean

If set to true or omitted, the tabbrowser will switch to the next tab when the Control and Page Up or Page Down keys are pressed. If this attribute is set to false, these keys do not navigate between tabs.

##### onbookmarkgroup Not in Firefox

Type: script code

This code executes when the user chooses the 'Bookmark This Group of Tabs' command.

##### onnewtab Not in Firefox

Type: script code

This script will be called when the new tab button is clicked.

#### Properties and Methods:

Inherited from XUL Element:

align
allowEvents
blur
boxObject
boxObject.element
boxObject.getLookAndFeelMetric
boxObject.height
boxObject.screenX
boxObject.screenY
boxObject.width
boxObject.x
boxObject.y
builder
className
click
collapsed
contextMenu
controllers
database
datasources
dir
doCommand
flex
focus
getElementsByAttribute
height
hidden
id
left
maxHeight
maxWidth
menu
minHeight
minWidth
observes
ordinal
orient
pack
persist
ref
resource
statusText
style
tooltip
tooltipText
top
width

Inherited from Element:

addEventListener
appendChild
attributes
childNodes
cloneNode
dispatchEvent
firstChild
getAttribute
getAttributeNS
getAttributeNode
getAttributeNodeNS
getElementsByTagName
getElementsByTagNameNS
hasAttribute
hasAttributeNS
hasAttributes
hasChildNodes
insertBefore
isSupported
lastChild
localName
namespaceURI
nextSibling
nodeName
nodeType
nodeValue
normalize
ownerDocument
parentNode
prefix
previousSibling
removeAttribute
removeAttributeNS
removeAttributeNode
removeChild
removeEventListener
replaceChild
setAttribute
setAttributeNS
setAttributeNode
setAttributeNodeNS
tagName

##### addProgressListener ( listener )

Return Type: no return value

Add a progress listener to the tabbrowser which will monitor loaded documents. The progress listener should implement the nsIWebProgressListener interface.

##### addTab ( url )

Return Type: tab element

Displays a new tab loading the specified URL as the document. The row of tabs will appear if needed.

##### appendGroup ( group ) Not in Firefox

Return Type: no return value

Add several new tabs to the end of the existing tabs. The argument should be an array of objects, one for each document to load. The objects may be defined in script and contain a 'URI' property for the URL of the page to load. A 'referrerURI' property may also be optionally used to set the referrer page.

##### browsers

Type: nodelist of browser elements

Holds a list of the browser elements inside the tabbrowser.

##### canGoBack

Type: boolean

This read-only property is true if there is a page to go back to in the session history and the Back button should be enabled.

##### canGoForward

Type: boolean

This read-only property is true if there is a page to go forward to in the session history and the Forward button should be enabled.

##### contentDocument

Type: document

This read-only property contains the document object in the tabbrowser.

##### contentTitle

Type: string

This read-only property contains the title of the document object in the tabbrowser.

##### contentViewerEdit

Type: nsIContentViewerEdit

This read-only property contains the nsIContentViewerEdit which handles clipboard operations on the document.

##### contentViewerFile

Type: nsIContentViewerFile

Reference to the nsIContentViewerFile interface for the document.

##### contentWindow

Type: window

This read-only property contains the window object in the tabbrowser.

##### currentURI

Type: string current URI

This read-only property contains the currently loaded URL. To change the URL, use the loadURI method.

##### docShell

Type: nsIDocShell

This read-only property contains the nsIDocShell object for the document.

##### documentCharsetInfo

Type: nsIDocumentCharsetInfo

This read-only property contains the nsIDocumentCharsetInfo object for the document which is used to handle which character set should be used to display the document.

##### getBrowserForTab ( tab )

Return Type: browser element

Returns a browser for specific tab element.

##### goBack ( )

Return Type: no return value

Go back one page in the history.

##### goBackGroup ( ) Not in Firefox

Return Type: no return value

Return to the previous group of tabs.

##### goForward ( )

Return Type: no return value

Go forward one page in the history.

##### goForwardGroup ( ) Not in Firefox

Return Type: no return value

Go forward to the next group of tabs.

##### goHome ( )

Return Type: no return value

Load the user's home page into the tabbrowser.

##### gotoIndex ( index )

Return Type: no return value

Navigate to the page in the history with the given index. Use a positive number to go forward and a negative number to go back.

##### homePage

Type: string home page URL

This property holds the value of the user's home page setting.

##### loadGroup ( group ) Not in Firefox

Return Type: the first tab

Loads a group of pages into multiple tabs. They are either appended or replaced depending on the state of the preference 'browser.tabs.loadGroup'. The argument should be an array of objects, one for each document to load. The objects may be defined in script and contain a 'URI' property for the URL of the page to load. A 'referrerURI' property may also be optionally used to set the referrer page. This function returns a reference to the first tab loaded.

##### loadURI ( uri , referrer , charset )

Return Type: no return value

Load a URL into the document, with the given referrer and character set.

##### loadURIWithFlags ( uri , flags , referrer , charset )

Return Type: no return value

Load a URL into the document, with the specified load flags and the given referrer and character set. In addition to the flags allowed for the reloadWithFlags methods, the following flags are also valid:

- LOAD_FLAGS_IS_REFRESH: This flag is used when the URL is loaded because of a meta tag refresh or redirect.
- LOAD_FLAGS_IS_LINK: This flag is used when the URL is loaded because a user clicked on a link. The HTTP Referer header is set accordingly.
- LOAD_FLAGS_BYPASS_HISTORY: Do not add the URL to the session history.
- LOAD_FLAGS_REPLACE_HISTORY: Replace the current URL in the session history with a new one. This flag might be used for a redirect.

##### markupDocumentViewer

Type: nsIMarkupDocumentViewer

This read-only property contains the nsIMarkupDocumentViewer which is responsible for drawing the document.

##### reload ( )

Reloads the document in the tabbrowser.

##### reloadAllTabs ( )

Return Type: no return value

Reloads the contents of all of the tabs.

##### reloadTab ( tab )

Return Type: no return value

Reloads the contents of a specific tab.

##### reloadWithFlags ( flags )

Return Type: no return value

Reloads the document in the tabbrowser with the given load flags. The flags listed below may be used, which are all constants of the webNavigation property (or the nsIWebNavigation interface). You may combine flags using a or symbol ( | )

- LOAD_FLAGS_NONE: No special flags. The document is loaded normally.
- LOAD_FLAGS_BYPASS_CACHE: Reload the page, ignoring if it is already in the cache. This is the flag used when the reload button is pressed while the Shift key is held down.
- LOAD_FLAGS_BYPASS_PROXY: Reload the page, ignoring the proxy server.
- LOAD_FLAGS_CHARSET_CHANGE: This flag is used if the document needs to be reloaded because the character set changed.

##### removeAllTabsBut ( tabElement )

Return Type: no return value

Removes all of the tab panels except for the one corresponding to the specified tab. If only one tab page is displayed, this method does nothing.

##### removeCurrentTab ( )

Return Type: tab element

Removes the currently displayed tab page. If it is the only displayed tab, this method does nothing.

##### removeProgressListener ( listener )

Return Type: no return value

Remove a progress listener from the tabbrowser.

##### removeTab ( tabElement )

Return Type: no return value

Removes a specific tabbed page corresponding to the given tab element. If only one tab is displayed, this method does nothing. If needed, the row of tabs will collapse if only one tab remains.

##### replaceGroup ( group ) Not in Firefox

Return Type: array of session history objects

replaces existing tabs with a new set. If there were more tabs before, the additional ones are not removed. You can use the removeTab function to remove the existing tabs first if that is desired. The argument should be an array of objects, one for each document to load. The objects may be defined in script and contain a 'URI' property for the URL of the page to load. A 'referrerURI' property may also be optionally used to set the referrer page. This method returns an array of the session history objects for the tabs that were removed.

##### securityUI

Type: nsISecureBrowserUI

The readonly property holds an object which may be used to determine the security level of the loaded document.

##### selectedBrowser

Type: browser element

This readonly property returns the currently displayed browser element.

##### selectedTab

Type: tab element

Holds the currently selected tab. You can modify this property to change the currently selected tab page.

##### sessionHistory

Type: nsISHistory

This read-only property contains the nsISHistory object which holds the session history.

##### stop ( )

Return Type: no return value

Equivalent to pressing the Stop button, this method stops the currently loading document.

##### tabContainer

Type: tabs element

Returns the tabs element that contains the tabs.

##### webBrowserFind

Type: nsIWebBrowserFind

This read-only property contains an nsIWebBrowserFind object which can be used to search for text in the document.

##### webNavigation

Type: nsIWebNavigation

This read-only property contains the nsIWebNavigation object for the document. Most of its methods are callable directly on the tabbrowser itself, such as goBack and goForward. It also contains the load constants used by reloadWithFlags and loadURIWithFlags.

##### webProgress

Type: nsIWebProgress

This read-only property contains an nsIWebProgress object which is used to monitor the progress of a document loading.

Copyright (C) 1999 - 2004 XulPlanet.com