sdk/fidl/fuchsia.fonts.experimental/provider.test.fidl

// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// NOTE: This file is unstable and should not be depended on.
// TODO(seancuff): Convert doc comments to markdown.

library fuchsia.fonts.experimental;

using fuchsia.fonts as ff;
using fuchsia.intl;

/// The maximum number of font families that can be returned in a
/// `TypefaceInfoResponse`.
const uint32 MAX_TYPEFACE_RESULTS = 16;

enum Error {
    NOT_FOUND = 1;
    INTERNAL = 2;
};

/// Experimental additions to `Provider`.
[Discoverable]
protocol Provider {
    /// Get an exact font by asset ID. This would typically be called
    /// after `ListTypefaces`, e.g. as part of a font selection interface.
    /// As with `fuchsia.fonts.GetTypeface`, it is the caller's responsibility
    /// to properly parse the file.
    ///
    /// Possible errors:
    /// `NOT_FOUND` if no asset with the requested `id` exists.
    /// `INTERNAL` if the requested `id` exists, but the asset failed to load.
    ///
    /// Eventually this should probably be folded into `GetTypeface`.
    GetTypefaceById(uint32 id) -> (ff.TypefaceResponse response) error Error;

    /// Creates a `ListTypefacesIterator` instance that will return a paginated
    /// list of fonts matching `request`.
    ///
    /// Possible errors:
    /// `INTERNAL` if something bad happens.
    ListTypefaces(ListTypefacesRequest request, request<ListTypefacesIterator> iterator) -> () error Error;

    /// Returns a `TypefaceInfo` for each font in the requested `family`. The
    /// results' `family` fields will hold the canonical family name, even if
    /// this method is called with an alias.
    ///
    /// This method should be called only if the caller knows `family` exists.
    /// Requesting a family that does not exist results in an error. To search
    /// for fonts by family name (or alias), use `ListTypefaces` instead.
    ///
    /// Possible errors:
    /// `NOT_FOUND` if no family name or alias matches the requested `family`.
    GetTypefacesByFamily(ff.FamilyName family) -> (TypefaceInfoResponse response) error Error;
};

protocol ListTypefacesIterator {
    /// Returns the next chunk of `TypefaceInfo` for all typefaces that match
    /// the bound `ListTypefacesRequest`. If `response.results` is empty, no
    /// results remain.
    GetNext() -> (TypefaceInfoResponse response);
};

/// Query parameters for `ListTypefaces`. Results must match all included
/// fields. All fields are optional; omitted fields will match any font.
table ListTypefacesRequest {
    /// Optional flags to modify matching behavior. Ignored if no other fields
    /// are set.
    1: ListTypefacesFlags flags;

    /// The name or alias of a font family. By default, families whose name
    /// exactly matches`family`. For substring matching, set the request's
    /// `MATCH_FAMILY_NAME_SUBSTRING` flag.
    2: ff.FamilyName family;

    /// Results must have a slant within this inclusive range.
    3: SlantRange slant;

    /// Results must have a weight within this inclusive range.
    4: WeightRange weight;

    /// Results must have a width within this inclusive range.
    5: WidthRange width;

    /// Languages that results must support.
    /// Each result must support all requested languages.
    6: vector<fuchsia.intl.LocaleId>:ff.MAX_FACE_QUERY_LANGUAGES languages;

    /// Code points that results must include.
    /// Each result must include all requested code points.
    7: vector<uint32> code_points;

    /// Generic font family which results must belong to. If a font's generic
    /// family is not set, it will only be matched if this field is also not
    /// set. However, omitting this field will still cause it to match any font.
    8: ff.GenericFontFamily generic_family;
};

bits ListTypefacesFlags : uint32 {
    /// Match families whose name or alias exactly contains the requested
    /// `FamilyName`. If not set, match families whose name or alias exactly
    /// matches `FamilyName`.
    ///
    /// Note: Matching will always ignore case.
    MATCH_FAMILY_NAME_SUBSTRING = 0x00000001;
};

/// Represents a range of acceptable `Slant`s. Both bounds are inclusive.
struct SlantRange {
    ff.Slant lower;
    ff.Slant upper;
};

/// Represents a range of acceptable `Weight`s. Both bounds are inclusive.
struct WeightRange {
    ff.Weight lower;
    ff.Weight upper;
};

/// Represents a range of acceptable `Width`s. Both bounds are inclusive.
struct WidthRange {
    ff.Width lower;
    ff.Width upper;
};

table TypefaceInfoResponse {
    1: vector<TypefaceInfo>:MAX_TYPEFACE_RESULTS results;
};

/// Collection of typeface metadata that should be sufficient for clients to
/// perform some kind of selection (likely via human) and request an exact font.
table TypefaceInfo {
    /// Identifier for the font asset. This ID is valid for the lifetime of the
    /// font service. May be used in conjunction with `font_index` to directly
    /// request this font.
    1: uint32 asset_id;

    /// Index of the font within its parent asset. May be used in conjunction
    /// with `asset_id` to directly request this font.
    2: uint32 font_index;

    3: ff.FamilyName family;
    4: ff.Style2 style;
    5: vector<fuchsia.intl.LocaleId> languages;
    6: ff.GenericFontFamily generic_family;
};