From f7eeb18411681bd126bd2cd2973dbfc398238124 Mon Sep 17 00:00:00 2001 From: Patrick Date: Thu, 4 Mar 2021 16:26:48 +0200 Subject: [PATCH] Add examples and docstrings to Overlay and Underlay --- src/actions/overlay.ts | 25 ++++++++++++++-- src/actions/underlay.ts | 29 ++++++++++++++++-- src/qualifiers/textStyle.ts | 59 ++++++++++++++++++++++++++++++++----- 3 files changed, 100 insertions(+), 13 deletions(-) diff --git a/src/actions/overlay.ts b/src/actions/overlay.ts index 0f16bb5a..1de8d244 100644 --- a/src/actions/overlay.ts +++ b/src/actions/overlay.ts @@ -5,14 +5,33 @@ import {LayerAction} from "./layer/LayerAction"; * @description Adds a video, text or an image layer as an overlay over the base layer.
* @memberOf Actions * @namespace Overlay + * @see Visit {@link Qualifiers.TextStyle|TextStyle} for advanced text options + * @see {@link Actions.Underlay| The underlay action} * @example * import {Cloudinary} from "@cloudinary/base/instance/Cloudinary"; * * const yourCldInstance = new Cloudinary({cloud:{cloudName:'demo'}}); - * const image = yourCldInstance.image('woman'); + * const myVideo = yourCldInstance.video('dog'); * - * image.overlay( - * Overlay.source(Source.image('sample')) + * import {source} from "@cloudinary/base/actions/overlay" + * import {image, video, text} from "@cloudinary/base/qualifiers/source" + * import {TextStyle} from '@cloudinary/base/qualifiers/textStyle + * + * myVideo.overlay( + * source(image('myImage')) + * ) + * + * myVideo.overlay( + * source(video('myVideo')) + * ) + * + * myVideo.overlay( + * source(text('My text'), 'arial_15') + * ) + * + * // Or a text with more complex options + * myVideo.overlay( + * source(text('My text'), new TextStyle('arial', 50)) * ) */ diff --git a/src/actions/underlay.ts b/src/actions/underlay.ts index baf7e822..b41c4359 100644 --- a/src/actions/underlay.ts +++ b/src/actions/underlay.ts @@ -8,16 +8,39 @@ import {FetchSource} from "../qualifiers/source/sourceTypes/FetchSource"; * @memberOf Actions * @namespace Underlay * @description Adds an image or a text layer as an underlay under the base layer.
+ * @see Visit {@link Qualifiers.TextStyle|TextStyle} for advanced text options + * @see {@link Actions.Overlay| The overlay action} * @example * import {Cloudinary} from "@cloudinary/base/instance/Cloudinary"; * * const yourCldInstance = new Cloudinary({cloud:{cloudName:'demo'}}); - * const image = yourCldInstance.image('woman'); - * image.underlay( - * Underlay.source(Source.image('sample')) + * const myVideo = yourCldInstance.video('dog'); + * + * import {source} from "@cloudinary/base/actions/underlay" + * import {image, video, text} from "@cloudinary/base/qualifiers/source" + * import {TextStyle} from '@cloudinary/base/qualifiers/textStyle + * + * myVideo.underlay( + * source(image('myImage')) + * ) + * + * myVideo.underlay( + * source(video('myVideo')) + * ) + * + * myVideo.underlay( + * source(text('My text'), 'arial_15') + * ) + * + * // Or a text with more complex options + * myVideo.underlay( + * source(text('My text'), new TextStyle('arial', 50)) * ) */ + + + /** * @summary action * @description Adds a layer for an asset diff --git a/src/qualifiers/textStyle.ts b/src/qualifiers/textStyle.ts index 04c2bf9e..e8f59a85 100644 --- a/src/qualifiers/textStyle.ts +++ b/src/qualifiers/textStyle.ts @@ -6,10 +6,11 @@ import {serializeCloudinaryCharacters} from "../internal/utils/serializeCloudina /** * @summary qualifier * @description Specifies how to style your layered text, controls the font, font size, line spacing and more. - * Learn more: {@link https://cloudinary.com/documentation/image_transformations#adding_text_overlays | Adding text overlays to images} - * Learn more: {@link https://cloudinary.com/documentation/video_manipulation_and_delivery#adding_text_captions | Adding text overlays to videos} + *
Learn more: {@link https://cloudinary.com/documentation/image_transformations#adding_text_overlays | Adding text overlays to images} + *
Learn more: {@link https://cloudinary.com/documentation/video_manipulation_and_delivery#adding_text_captions | Adding text overlays to videos} + * @see {@link Actions.Overlay| The overlay action} + * @see {@link Actions.Underlay| The underlay action} * @memberOf Qualifiers - * @namespace TextStyle */ class TextStyle { private _lineSpacing: number; @@ -24,6 +25,10 @@ class TextStyle { private _stroke: boolean; private _fontHinting: string; + /** + * @param {string} fontFamily The font family + * @param {number | string} fontSize The font size + */ constructor(fontFamily: string, fontSize: string | number) { if (!fontFamily || !fontSize) { throw `You must provide a fontFamily and fontSize to a TextStyle`; @@ -32,56 +37,96 @@ class TextStyle { this._fontSize = fontSize; } + /** + * @param {number} spacing The spacing between multiple lines in pixels. + */ lineSpacing(spacing: number): this { this._lineSpacing = spacing; return this; } + + /** + * @param spacing The spacing between the letters, in pixels. + */ letterSpacing(spacing: number): this { this._letterSpacing = spacing; return this; } + /** + * The antialias setting to apply to the text. When this parameter is not specified, the default antialiasing for the subsystem and target device are applied. + * @param antiAlias + */ fontAntialias(antiAlias: string): this { this._fontAntialias = antiAlias; return this; } + /** + * The name of any universally available font or a custom font, specified as the public ID of a raw, authenticated font in your account. + * For details on custom fonts, see {@link https://cloudinary.com/documentation/image_transformations#using_custom_fonts_for_text_overlays|Using custom fonts for text overlays}. + * @param {string} fontFamilyName + */ fontFamily(fontFamilyName: string): this { this._fontFamily = fontFamilyName; return this; } + /** + * @param {number} fontSize The font size + */ fontSize(fontSize: number | string): this { this._fontSize = fontSize ; return this; } - fontWeight(fontWeight: string): this { + /** + * @param {string} fontWeight The font weight + */ + fontWeight(fontWeight: 'normal' | 'bold' | 'thin' | 'light' | string): this { this._fontWeight = fontWeight; return this; } - fontStyle(fontStyle: string): this { + /** + * + * @param {string} fontStyle The font style. + */ + fontStyle(fontStyle: 'normal' | 'italic' | string): this { this._fontStyle = fontStyle; return this; } + /** + * @param {string} fontHinting The outline hinting style to apply to the text. When this parameter is not specified, the default hint style for the font and target device are applied. + */ fontHinting(fontHinting: string): this { this._fontHinting = fontHinting; return this; } - textDecoration(textDecoration: string): this { + /** + * + * @param {string} textDecoration The font decoration type. + */ + textDecoration(textDecoration: 'normal' | 'underline' | 'strikethrough' | string): this { this._textDecoration = textDecoration; return this; } - textAlignment(textAlignment: string): this { + + /** + * @param {string} textAlignment The text alignment + */ + textAlignment(textAlignment: 'left' | 'center' | 'right' | 'end' | 'start' | 'justify' | string): this { this._textAlignment = textAlignment; return this; } + /** + * @description Whether to include an outline stroke. Set the color and weight of the stroke + */ stroke(): this { this._stroke = true; return this;