blob: 5b512560009309b67a841e43606e12905d8b3428 [file] [log] [blame]
// Copyright 2017 The Cobalt Authors. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// Custom, not a standard.
// This is an API for accessing system-level closed caption settings and
// exposing them to HTML5 apps. It supports detecting if captions are enabled at
// a system level, and retrieving values of various captioning style
// properties assigned by the system.
// For each captioning style property that this API supports, there are two
// attributes. The first accesses the system-level setting for a property, and
// the second determines the state of that property. For possible states, see
// ./caption_state.idl. To use a particular property, you should check its
// state first to ensure that the property is properly supported.
// For example, if you want to get your system's font size, you would first
// check the value of the "fontSizeState" attribute. If it contains
// "unsupported", then the system does not support font size settings, so use
// your application's font size settings instead. If it contains "unset", then
// the user has not set the property in their system, so you should also use
// your application settings instead. If it contains another value, then you
// can safely access the corresponding "fontSize" attribute. If you attempt
// to access a property that is unsupported or unset, it will return null.
// One property which behaves a bit differently is the one that determines
// whether captions are enabled or disabled at a system level. It is important
// to note that this property can both be read from and written to, and if using
// either of these behaviors, you should use the corresponding check to ensure
// that it is supported. If you try to read from the property and doing so is
// not supported, it will return false. If you try to write to it and doing so
// is not supported, the value will silently not change.
interface SystemCaptionSettings : EventTarget {
// TODO: Make the functions for style properties return nullable enum types
// instead of nullable DOMStrings.
// It seems that Cobalt's bindings generation code does not support
// nullable enums in IDL. To handle this, the attributes for style properties
// return nullable DOMStrings instead. The underlying Cobalt implementation
// ensures that a string corresponding to the proper enum value is returned
// by each attribute.
readonly attribute DOMString? backgroundColor;
readonly attribute CaptionState backgroundColorState;
readonly attribute DOMString? backgroundOpacity;
readonly attribute CaptionState backgroundOpacityState;
readonly attribute DOMString? characterEdgeStyle;
readonly attribute CaptionState characterEdgeStyleState;
readonly attribute DOMString? fontColor;
readonly attribute CaptionState fontColorState;
readonly attribute DOMString? fontFamily;
readonly attribute CaptionState fontFamilyState;
readonly attribute DOMString? fontOpacity;
readonly attribute CaptionState fontOpacityState;
readonly attribute DOMString? fontSize;
readonly attribute CaptionState fontSizeState;
readonly attribute DOMString? windowColor;
readonly attribute CaptionState windowColorState;
readonly attribute DOMString? windowOpacity;
readonly attribute CaptionState windowOpacityState;
// "enabled" means that the user has chosen to enable closed captions
// on the system.
attribute boolean isEnabled;
// There are separate checks for reading and writing to the enabled attribute,
// as some systems allow the value to be queried but not written to. Setting
// the enabled attribute will change the system-wide enabled setting.
// Attempting to read isEnabled when supportsIsEnabled is false will
// always return false. Attempting to set isEnabled when supportsSetEnabled is
// false will fail silently.
readonly attribute boolean supportsIsEnabled;
readonly attribute boolean supportsSetEnabled;
// Some platforms may specify that when setting a property, it should override
// data from video streams and application settings (unless the application
// has its own overrides). Depending on whether this attribute contains true
// or false, the CaptionState return value should be interpreted differently.
// Refer to the documentation in ./caption_state.idl for details.
readonly attribute boolean supportsOverride;
attribute EventHandler onchanged;
};