From 6bf0a5cb5034a7e684dcc3500e841785237ce2dd Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 19:32:43 +0200 Subject: Adding upstream version 1:115.7.0. Signed-off-by: Daniel Baumann --- build/docs/chrome-registration.rst | 457 +++++++++++++++++++++++++++++++++++++ 1 file changed, 457 insertions(+) create mode 100644 build/docs/chrome-registration.rst (limited to 'build/docs/chrome-registration.rst') diff --git a/build/docs/chrome-registration.rst b/build/docs/chrome-registration.rst new file mode 100644 index 0000000000..e62636f7a2 --- /dev/null +++ b/build/docs/chrome-registration.rst @@ -0,0 +1,457 @@ +Chrome Registration +------------------- + +What is chrome? +--------------- + +`Chrome` is the set of user interface elements of the +application window that are outside the 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. + +``chrome.manifest`` files are used to register XPCOM components and sources for the chrome protocol. +Every application supplies a root ``chrome.manifest`` file that Mozilla reads on startup. + +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. + +Locale + Localizable applications keep all their localized information in + locale providers and Fluent FTL files, which are handled separately. + This allows translators to plug in a different + chrome package to translate an application without altering the rest + of the source code. In a chrome provider, localizable files are mostly + 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. + +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). + +.. code:: + + locale packagename localename path/to/files + skin packagename skinname path/to/files + +.. note:: + + The characters @ # ; : ? / are not allowed in the + packagename. + +Manifest instructions +--------------------- + +comments +~~~~~~~~ + +.. code:: + + # this line is a comment - you can put here whatever you want + +A line is a comment if it begins with the character '#'. Any following +character in the same line is ignored. + +manifest +~~~~~~~~ + +:: + + 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. + +component +~~~~~~~~~ + +:: + + 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 +~~~~~~~~ + +:: + + contract @foobar/mycontract;1 {00000000-0000-0000-0000-000000000000} [flags] + +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 +~~~~~~~~ + +:: + + category category entry-name value [flags] + +Registers an entry in the `category manager`. The +specific format and meaning of category entries depend 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 a +'/'. + +locale +~~~~~~ + +A locale package is registered with the line: + +.. code:: + + 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: + +.. code:: + + 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. + +style +~~~~~ + +Style overlays (custom CSS which will be applied to a chrome page) are +registered with the following syntax: + +.. code:: + + style chrome://URI-to-style chrome://stylesheet-URI [flags] + +override +~~~~~~~~ + +In some cases an extension or embedder may wish to override a chrome +file provided by the application or XULRunner. In order to allow for +this, the chrome registration manifest allows for "override" +instructions: + +.. code:: + + override chrome://package/type/original-uri.whatever new-resolved-URI [flags] + +Note: overrides are not recursive (so overriding +chrome://foo/content/bar/ with file:///home/john/blah/ will not usually +do what you want or expect it to do). Also, the path inside overridden +files is relative to the overridden path, not the original one (this can +be annoying and/or useful in CSS files, for example). + +resource +~~~~~~~~ + +Aliases can be created using the ``resource`` instruction: + +.. code:: + + resource aliasname uri/to/files/ [flags] + +This will create a mapping for ``resource:///`` URIs to the +path given. + +.. note:: + + **Note:** There are no security restrictions preventing web content + from including content at resource: URIs, so take care what you make + visible there. + +Manifest flags +-------------- + +Manifest lines can have multiple, space-delimited flags added at the end +of the registration line. These flags mark special attributes of chrome +in that package, or limit the conditions under which the line is used. + +application +~~~~~~~~~~~ + +Extensions may install into multiple applications. There may be chrome +registration lines which only apply to one particular application. The +flag + +.. code:: + + application=app-ID + +indicates that the instruction should only be applied if the extension +is installed into the application identified by *app-ID*. Multiple +application flags may be included on a single line, in which case the +line is applied if any of the flags match. + +This example shows how a different overlay can be used for different +applications: + +:: + + overlay chrome://browser/content/browser.xul chrome://myaddon/content/ffOverlay.xul application={ec8030f7-c20a-464f-9b0e-13a3a9e97384} + overlay chrome://messenger/content/mailWindowOverlay.xul chrome://myaddon/content/tbOverlay.xul application={3550f703-e582-4d05-9a08-453d09bdfdc6} + overlay chrome://songbird/content/xul/layoutBaseOverlay.xul chrome://myaddon/content/sbOverlay.xul application=songbird@songbirdnest.com + +appversion +~~~~~~~~~~ + +Extensions may install into multiple versions of an application. There +may be chrome registration lines which only apply to a particular +application version. The flag + +.. code:: + + appversion=version + appversionversion + appversion>=version + +indicates that the instruction should only be applied if the extension +is installed into the application version identified. Multiple +``appversion`` flags may be included on a single line, in which case the +line is applied if any of the flags match. The version string must +conform to the `Toolkit version format`. + +platformversion +~~~~~~~~~~~~~~~ + +When supporting more then one application, it is often more convenient +for an extension to specify which Gecko version it is compatible with. +This is particularly true for binary components. If there are chrome +registration lines which only apply to a particular Gecko version, the +flag + +.. code:: + + platformversion=version + platformversionversion + platformversion>=version + +indicates that the instruction should only be applied if the extension +is installed into an application using the Gecko version identified. +Multiple ``platformversion`` flags may be included on a single line, in +which case the line is applied if any of the flags match. + +contentaccessible +~~~~~~~~~~~~~~~~~ + +Chrome resources can no longer be referenced from within , +