mozilla

Revision 19091 of Chrome registration

  • Revision slug: Chrome_Registration
  • Revision title: Chrome registration
  • Revision id: 19091
  • Created:
  • Creator: ziyunfei
  • Is current revision? No
  • Comment 1 words added, 2227 words removed

Revision Content

What is chrome?

Chrome is the set of user interface elements of the application window that are outside window's content area. Toolbars, menu bars, progress bars, and window title bars are all examples of elements that are typically part of the chrome.

Mozilla locates and reads the root chrome.manifest file for extensions and themes.

{{ gecko_callout_heading("2.0") }}

With Gecko 1.9.2 and older, Mozilla reads chrome/*.manifest files from applications. Starting with Gecko 2.0 {{ geckoRelease("2.0") }}, the root chrome.manifest is the only manifest used; you can add manifest commands to that file to load secondary manifests.

Chrome providers

A supplier of chrome for a given window type (e.g. for the browser window) is called a chrome provider. The providers work together to supply a complete set of chrome for a particular window, from the images on the toolbar buttons to the files that describe the text, content and appearance of the window itself.

There are three basic types of chrome providers:

Content

The main source file for a window description comes from the content provider, and it can be any file type viewable from within Mozilla. It will typically be a XUL file, since XUL is designed for describing the contents of windows and dialogs. The JavaScript files that define the user interface are also contained within the content packages, as well as most XBL binding files.

Locale

Localizable applications keep all their localized information in locale providers. This allows translators to plug in a different chrome package to translate an application without altering the rest of the source code. The two main types of localizable files are DTD files and Java-style properties files.

Skin

A skin provider is responsible for providing a complete set of files that describe the visual appearance of the chrome. Typically a skin provider will provide CSS files and images.

Note: Scripts (including those found in XBL) loaded from skin packages will not execute.

The chrome registry

The Gecko runtime maintains a service known as the chrome registry that provides mappings from chrome package names to the physical location of chrome packages on disk.

This chrome registry is configurable and persistent, and thus a user can install different chrome providers, and select a preferred skin and locale. This is accomplished through xpinstall and the extension manager.

In order to inform the chrome registry of the available chrome, a text manifest is used: this manifest is "chrome.manifest" in the root of an extension, or theme, or XULRunner application.

The plaintext chrome manifests are in a simple line-based format. Each line is parsed individually; if the line is parsable the chrome registry takes the action identified by that line; otherwise the chrome registry ignores that line (and prints a warning message in the runtime error console).

locale packagename localename path/to/files
skin packagename skinname path/to/files

{{ warning("Firefox 2, ThunderBird 2, and SeaMonkey 1.1 will not find the chrome when packagename is mixed case. If the above example had a packagename of CamelCasePackage, you would get an error message similar to \"No chrome registered for chrome://camelcasepackage/path/to/files\". Firefox 3, ThunderBird 3, and SeaMonkey 2 support mixed case. Bug resolved in Mozilla 1.9. See Bug 132183.") }}

Manifest instructions

comments

A line is a comment if it begins with the character '#'; any other character in the line is ignored.

# this line is a comment - you can put whatever you want here

manifest

{{ gecko_minversion_inline("2.0b4") }}

manifest subdirectory/foo.manifest [flags]

This will load a secondary manifest file. This can be useful for separating component and chrome registration instructions, or separate platform-specific registration data.

binary-component

{{ gecko_minversion_inline("2.0b2") }}

binary-component components/mycomponent.dll [flags]

Instructs Mozilla to register and use a binary component. It should be combined with the abi flag, since binary components are ABI-specific. Prior to Firefox 4, files in the components directory were registered automatically.

interfaces

{{ gecko_minversion_inline("2.0b2") }}

interfaces component/mycomponent.xpt [flags]

Instructs Mozilla to load interface information from a typelib file produced by XPIDL. Prior to Firefox 4, files in the components directory were registered automatically.

component

{{ gecko_minversion_inline("2.0b2") }}

component {00000000-0000-0000-0000-000000000000} components/mycomponent.js [flags]

Informs Mozilla about a component CID implemented by an XPCOM component implemented in JavaScript (or another scripting language, if applicable). The ClassID {0000...} must match the ClassID implemented by the component. To generate a unique ClassID, use a UUID generator program or site.

contract

{{ gecko_minversion_inline("2.0b2") }}

contract @foobar/mycontract;1 {00000000-0000-0000-0000-000000000000} [flags]

u

Maps a contract ID (a readable string) to the ClassID for a specific implementation. Typically a contract ID will be paired with a component entry immediately preceding.

category

{{ gecko_minversion_inline("2.0b2") }}

category category entry-name value [flags]

Registers an entry in the category manager. The specific format and meaning of category entries depends on the category.

content

A content package is registered with the line

content packagename uri/to/files/ [flags]

This will register a location to use when resolving the URI chrome://packagename/content/.... The URI may be absolute or relative to the location of the manifest file. Note: it must end with an '/'.

locale

A locale package is registered with the line

locale packagename localename uri/to/files/ [flags]

This will register a locale package when resolving the URI chrome://packagename/locale/... . The localename is usually a plain language identifier "en" or a language-country identifier "en-US". If more than one locale is registered for a package, the chrome registry will select the best-fit locale using the user's preferences.

skin

A skin package is registered with the line

skin packagename skinname uri/to/files/ [flags]

This will register a skin package when resolving the URI chrome://packagename/skin/... . The skinname is an opaque string identifying an installed skin. If more than one skin is registered for a package, the chrome registry will select the best-fit skin using the user's preferences.

overlay

XUL overlays are registered with the following syntax:

overl

Revision Source

<h2 name="What_is_Chrome.3F">What is chrome?</h2>
<p><a href="/en/Chrome" title="en/Chrome">Chrome</a> is the set of user interface elements of the application window that are outside window's content area. Toolbars, menu bars, progress bars, and window title bars are all examples of elements that are typically part of the chrome.</p>
<p>Mozilla locates and reads the root <code>chrome.manifest</code> file for extensions and themes.</p>
<div class="geckoVersionNote"> <p>{{ gecko_callout_heading("2.0") }}</p> <p>With Gecko 1.9.2 and older, Mozilla reads <code>chrome/*.manifest</code> files from applications. Starting with Gecko 2.0 {{ geckoRelease("2.0") }}, the root <code>chrome.manifest</code> is the only manifest used; you can add <a href="/en/Chrome_Registration#manifest" title="en/Chrome Registration#manifest"><code>manifest</code></a> commands to that file to load secondary manifests.</p>
</div>
<h2 name="Chrome_Providers">Chrome providers</h2>
<p>A supplier of chrome for a given window type (e.g. for the browser window) is called a chrome provider. The providers work together to supply a complete set of chrome for a particular window, from the images on the toolbar buttons to the files that describe the text, content and appearance of the window itself.</p>
<p>There are three basic types of chrome providers:</p>
<h3 name="Content">Content</h3>
<p>The main source file for a window description comes from the content provider, and it can be any file type viewable from within Mozilla. It will typically be a XUL file, since XUL is designed for describing the contents of windows and dialogs. The JavaScript files that define the user interface are also contained within the content packages, as well as most XBL binding files.</p>
<h3 name="Locale">Locale</h3>
<p>Localizable applications keep all their localized information in locale providers. This allows translators to plug in a different chrome package to translate an application without altering the rest of the source code. The two main types of localizable files are DTD files and Java-style properties files.</p>
<h3 name="Skin">Skin</h3>
<p>A skin provider is responsible for providing a complete set of files that describe the visual appearance of the chrome. Typically a skin provider will provide CSS files and images.</p>
<p><em>Note</em>: Scripts (including those found in <a href="/en/XBL" title="en/XBL">XBL</a>) loaded from skin packages will not execute.</p>
<h2 name="The_Chrome_Registry">The chrome registry</h2>
<p>The Gecko runtime maintains a service known as the chrome registry that provides mappings from chrome package names to the physical location of chrome packages on disk.</p>
<p>This chrome registry is configurable and persistent, and thus a user can install different chrome providers, and select a preferred skin and locale. This is accomplished through xpinstall and the extension manager.</p>
<p>In order to inform the chrome registry of the available chrome, a text manifest is used: this manifest is "chrome.manifest" in the root of an extension, or theme, or XULRunner application.</p>
<p>The plaintext chrome manifests are in a simple line-based format. Each line is parsed individually; if the line is parsable the chrome registry takes the action identified by that line; otherwise the chrome registry ignores that line (and prints a warning message in the runtime error console).</p>
<pre class="eval" style="white-space: pre-wrap;">locale packagename localename path/to/files
skin packagename skinname path/to/files
</pre>
<p>{{ warning("Firefox 2, ThunderBird 2, and SeaMonkey 1.1 will not find the chrome when <code>packagename</code> is mixed case. If the above example had a <code>packagename</code> of <strong>C</strong>amel<strong>C</strong>ase<strong>P</strong>ackage, you would get an error message similar to \"No chrome registered for chrome://<strong>c</strong>amel<strong>c</strong>ase<strong>p</strong>ackage/path/to/files\". Firefox 3, ThunderBird 3, and SeaMonkey 2 support mixed case. Bug resolved in Mozilla 1.9. See <a class="external" href="https://bugzilla.mozilla.org/show_bug.cgi?id=132183" title="https://bugzilla.mozilla.org/show_bug.cgi?id=132183">Bug 132183</a>.") }}</p>
<h2 name="Manifest_Instructions">Manifest instructions</h2>
<h3 name="comments">comments</h3>
<p>A line is a comment if it begins with the character '#'; any other character in the line is ignored.</p>
<pre class="eval" style="white-space: pre-wrap;"># this line is a comment - you can put whatever you want here
</pre>
<h3 name="content">manifest</h3>
<p>{{ gecko_minversion_inline("2.0b4") }}</p>
<pre>manifest <em>subdirectory/foo.manifest [flags]</em>
</pre>
<p>This will load a secondary manifest file. This can be useful for separating component and chrome registration instructions, or separate platform-specific registration data.</p>
<h3>binary-component</h3>
<p>{{ gecko_minversion_inline("2.0b2") }}</p>
<pre>binary-component <em>components/mycomponent.dll [flags]</em>
</pre>
<p>Instructs Mozilla to register and use a binary component. It should be combined with the abi flag, since binary components are ABI-specific. <a href="/en/XPCOM/XPCOM_changes_in_Gecko_2.0" title="en/XPCOM/XPCOM changes in Gecko 2.0">Prior to Firefox 4</a>, files in the components directory were registered automatically.</p>
<h3>interfaces</h3>
<p>{{ gecko_minversion_inline("2.0b2") }}</p>
<pre>interfaces <em>component/mycomponent.xpt [flags]</em>
</pre>
<p>Instructs Mozilla to load interface information from a typelib file produced by XPIDL. <a href="/en/XPCOM/XPCOM_changes_in_Gecko_2.0" title="en/XPCOM/XPCOM changes in Gecko 2.0">Prior to Firefox 4</a>, files in the components directory were registered automatically.</p>
<h3>component</h3>
<p>{{ gecko_minversion_inline("2.0b2") }}</p>
<pre>component <em>{00000000-0000-0000-0000-000000000000} components/mycomponent.js [flags]</em>
</pre>
<p>Informs Mozilla about a component CID implemented by an XPCOM component implemented in JavaScript (or another scripting language, if applicable). The ClassID {0000...} must match the ClassID implemented by the component. To generate a unique ClassID, use a UUID generator program or site.</p>
<h3>contract</h3>
<p>{{ gecko_minversion_inline("2.0b2") }}</p>
<pre>contract <em>@foobar/mycontract;1 <em>{00000000-0000-0000-0000-000000000000} [flags]</em></em>
</pre>
<p>u</p>
<p>Maps a contract ID (a readable string) to the ClassID for a specific implementation. Typically a contract ID will be paired with a component entry immediately preceding.</p>
<h3>category</h3>
<p>{{ gecko_minversion_inline("2.0b2") }}</p>
<pre>category <em>category entry-name value [flags]</em>
</pre>
<p>Registers an entry in the <a href="/en/XPCOM_Interface_Reference/nsICategoryManager" title="en/XPCOM Interface Reference/nsICategoryManager">category manager</a>. The specific format and meaning of category entries depends on the category.</p>
<h3 name="content">content</h3>
<p>A content package is registered with the line</p>
<pre class="eval" style="white-space: pre-wrap;">content <em>packagename</em> <em>uri/to/files/</em> <em>[flags]</em>
</pre>
<p>This will register a location to use when resolving the URI <code>chrome://<em>packagename</em>/content/...</code>. The URI may be absolute or relative to the location of the manifest file. Note: it must end with an '/'.</p>
<h3 name="locale">locale</h3>
<p>A locale package is registered with the line</p>
<pre class="eval" style="white-space: pre-wrap;">locale <em>packagename</em> <em>localename</em> <em>uri/to/files/</em> <em>[flags]</em>
</pre>
<p>This will register a locale package when resolving the URI chrome://<em>packagename</em>/locale/... . The <em>localename</em> is usually a plain language identifier "en" or a language-country identifier "en-US". If more than one locale is registered for a package, the chrome registry will select the best-fit locale using the user's preferences.</p>
<h3 name="skin">skin</h3>
<p>A skin package is registered with the line</p>
<pre class="eval" style="white-space: pre-wrap;">skin <em>packagename</em> <em>skinname</em> <em>uri/to/files/</em> <em>[flags]</em>
</pre>
<p>This will register a skin package when resolving the URI <a class=" external" href="chrome://packagename/skin/" rel="freelink">chrome://packagename/skin/</a>... . The <em>skinname</em> is an opaque string identifying an installed skin. If more than one skin is registered for a package, the chrome registry will select the best-fit skin using the user's preferences.</p>
<h3 name="overlay">overlay</h3>
<p>XUL overlays are registered with the following syntax:</p>
<pre class="eval" style="white-space: pre-wrap;">overl</pre>
Revert to this revision