Bug 1270832 - Activate standard c++ library hardening r=glandium
[gecko.git] / dom / webidl / Localization.webidl
blob20c075d9da1aaa2daa152c6be8245ad412b9bbb4
1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3  * License, v. 2.0. If a copy of the MPL was not distributed with this
4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6 /**
7  * L10nIdArgs is an object used to carry localization tuple for message
8  * translation.
9  *
10  * Fields:
11  *    id - identifier of a message.
12  *  args - an optional record of arguments used to format the message.
13  *         The argument will be converted to/from JSON, and the API
14  *         will only handle strings and numbers.
15  */
16 dictionary L10nIdArgs {
17   UTF8String? id = null;
18   L10nArgs? args = null;
21 /**
22  * When no arguments are required to format a message a simple string can be
23  * used instead.
24  */
25 typedef (UTF8String or L10nIdArgs) L10nKey;
27 /**
28  * L10nMessage is a compound translation unit from Fluent which
29  * encodes the value and (optionally) a list of attributes used
30  * to translate a given widget.
31  *
32  * Most simple imperative translations will only use the `value`,
33  * but when building a Message for a UI widget, a combination
34  * of a value and attributes will be used.
35  */
36 dictionary AttributeNameValue {
37   required UTF8String name;
38   required UTF8String value;
41 dictionary L10nMessage {
42   UTF8String? value = null;
43   sequence<AttributeNameValue>? attributes = null;
46 /**
47  * Localization is an implementation of the Fluent Localization API.
48  *
49  * An instance of a Localization class stores a state of a mix
50  * of localization resources and provides the API to resolve
51  * translation value for localization identifiers from the
52  * resources.
53  *
54  * Methods:
55  *    - addResourceIds     - add resources
56  *    - removeResourceIds  - remove resources
57  *    - formatValue        - format a single value
58  *    - formatValues       - format multiple values
59  *    - formatMessages     - format multiple compound messages
60  *
61  */
62 [Func="mozilla::intl::Localization::IsAPIEnabled", Exposed=Window]
63 interface Localization {
64   /**
65    * Constructor arguments:
66    *    - aResourceids         - a list of localization resource URIs
67    *                             which will provide messages for this
68    *                             Localization instance.
69    *    - aSync                - Specifies if the initial state of the Localization API is synchronous.
70    *                             This enables a number of synchronous methods on the
71    *                             Localization API.
72    *    - aRegistry            - optional custom L10nRegistry to be used by this Localization instance.
73    *    - aLocales             - custom set of locales to be used for this Localization.
74    */
75   [Throws]
76   constructor(sequence<L10nResourceId> aResourceIds,
77               optional boolean aSync = false,
78               optional L10nRegistry aRegistry,
79               optional sequence<UTF8String> aLocales);
81   /**
82    * A method for adding resources to the localization context.
83    */
84   undefined addResourceIds(sequence<L10nResourceId> aResourceIds);
86   /**
87    * A method for removing resources from the localization context.
88    *
89    * Returns a new count of resources used by the context.
90    */
91   unsigned long removeResourceIds(sequence<L10nResourceId> aResourceIds);
93   /**
94    * Formats a value of a localization message with a given id.
95    * An optional dictionary of arguments can be passed to inform
96    * the message formatting logic.
97    *
98    * Example:
99    *    let value = await document.l10n.formatValue("unread-emails", {count: 5});
100    *    assert.equal(value, "You have 5 unread emails");
101    */
102   [NewObject] Promise<UTF8String?> formatValue(UTF8String aId, optional L10nArgs aArgs);
104   /**
105    * Formats values of a list of messages with given ids.
106    *
107    * Example:
108    *    let values = await document.l10n.formatValues([
109    *      {id: "hello-world"},
110    *      {id: "unread-emails", args: {count: 5}
111    *    ]);
112    *    assert.deepEqual(values, [
113    *      "Hello World",
114    *      "You have 5 unread emails"
115    *    ]);
116    */
117   [NewObject] Promise<sequence<UTF8String?>> formatValues(sequence<L10nKey> aKeys);
119   /**
120    * Formats values and attributes of a list of messages with given ids.
121    *
122    * Example:
123    *    let values = await document.l10n.formatMessages([
124    *      {id: "hello-world"},
125    *      {id: "unread-emails", args: {count: 5}
126    *    ]);
127    *    assert.deepEqual(values, [
128    *      {
129    *        value: "Hello World",
130    *        attributes: null
131    *      },
132    *      {
133    *        value: "You have 5 unread emails",
134    *        attributes: {
135    *          tooltip: "Click to select them all"
136    *        }
137    *      }
138    *    ]);
139    */
140   [NewObject] Promise<sequence<L10nMessage?>> formatMessages(sequence<L10nKey> aKeys);
142   undefined setAsync();
144   [NewObject, Throws]
145   UTF8String? formatValueSync(UTF8String aId, optional L10nArgs aArgs);
146   [NewObject, Throws]
147   sequence<UTF8String?> formatValuesSync(sequence<L10nKey> aKeys);
148   [NewObject, Throws]
149   sequence<L10nMessage?> formatMessagesSync(sequence<L10nKey> aKeys);
153  * A helper dict for converting between JS Value and L10nArgs.
154  */
155 [GenerateInitFromJSON, GenerateConversionToJS]
156 dictionary L10nArgsHelperDict {
157   required L10nArgs args;