NewElements

DSHDLib.Editors.ProjectData. Namespace

NewElements

Source:

Type Definitions

AudioElement

Description:
  • Properties specific to new audio elements - See BaseElement for common properties
Source:
Properties:
Name Type Attributes Default Description
url string <optional>
 Signed/public url of an audio file to import. Must be provided without asset
asset DSHDLib.Editors.ProjectData.NewElements.NewElementAsset <optional>
 Data reference to a previously imported audio track. Must be provided without url
context string <optional>
 "scene" One of: "scene", "page", "global"
track_name string <optional>
 An optional user-viewable/editable name for the audio track
trim_start number <optional>
 Optionally override the starting point, in seconds, of the audio track
trim_end number <optional>
 Optionally override the ending point, in seconds, of the audio track
Properties specific to new audio elements - See BaseElement for common properties
Type:

BaseElement

Description:
  • Base type for shared properties when creating all new element types
Source:
Properties:
Name Type Attributes Default Description
element_name string <optional>
<nullable>
 An optional element identifier/label. Must be unique across entire project
element_classes Array.<string> <optional>
 An optional list of classes associated with the element
type string One of: "text", "image", "vector", "video", "audio", "zone"
blend_mode string <optional>
 The blend mode to apply to the element. One of: "none", "multiply", "screen", "overlay", "darken", "lighten", "color-dodge", "color-burn", "hard-light", "soft-light", "difference", "exclusion", "hue", "saturation", "color", "luminosity"
page_id string <optional>
 Override the page on a project (retrieved from getProjectData) that the element is added to. Places on currently open page by default
scene_id string <optional>
 Override the scene on a video project (retrieved from getProjectData) that the element is added to. Places on currently open scene by default
selected bool <optional>
 true A value indicating whether the new element should be selected on the canvas (removing the existing selection) if it is being added to the currently visible page/scene
Base type for shared properties when creating all new element types

ImageElement

Description:
  • Properties specific to new image elements - See BaseElement for common properties
Source:
Properties:
Name Type Attributes Default Description
url string <optional>
 Signed/public url or the data url of an image (png, jpg, webp, heic, gif or tiff file) to import. Must be provided without asset
asset DSHDLib.Editors.ProjectData.NewElements.NewElementAsset <optional>
 Data reference to a previously imported image. Must be provided without url
width number <optional>
 The width of the image in the unit type of the project. Will be based off the height (preserving aspect ratio) if not supplied or sized relative to the canvas if neither are supplied
height number <optional>
 The height of the image in the unit type of the project. Will be based off the width (preserving aspect ratio) if not supplied or sized relative to the canvas if neither are supplied
left number <optional>
 The x coordinate to place the image in the unit type of the project. Horizontally centered if not provided
top number <optional>
 The y coordinate to place the image in the unit type of the project. Vertically centered if not provided
placement string <optional>
 "foreground" One of: "foreground", "background"
opacity number <optional>
 The opacity percentage to set on the new element, between 0 and 1
ignore_low_dpi bool <optional>
 false A value indicating whether the Poor Image Quality warning should trigger for this image when its pixel density is too low for the project's DPI (when the AI Upscale feature is enabled)
Properties specific to new image elements - See BaseElement for common properties
Type:

NewElementAsset

Description:
  • Asset reference
Source:
Properties:
Name Type Attributes Description
store string Must be "library"
asset_id number <optional>
 The internal asset_id of the image/vector/video/audio asset to place. Must be provided without asset_code
asset_code string <optional>
 The id of the image/vector/video/audio asset to place in the originating repository. Must be provided without asset_id
Asset reference
Type:
  • Object

TextAutoFitProperties

Description:
  • Properties for Auto Fit configuration on new text elements
Source:
Properties:
Name Type Attributes Description
max_font_size number <optional>
 The maximum font size (in pt on print projects and px otherwise) the text should grow to given the max_lines and/or max_height values. If not supplied, will use the new text's font size (prior to any possible reduction)
min_font_size number <optional>
 The minimum font size (in pt on print projects and px otherwise) the text should strink to given the max_lines and/or max_height values. Note that truncation may occur if/when the minimum is hit and the max_lines and/or max_height have been reached
max_lines number <optional>
 The maximum number of lines the text should wrap to. If not supplied and no max_height supplied, will use the new text's line count (prior to any possible reduction)
max_height number <optional>
 The maximum height the text should grow to in the unit type of the project. Supply -1 to use the height of the new text (prior to any possible reduction)
truncation_suffix string <optional>
 If/when truncation of the text occurs, this text is appended to the end of the rendered text (in place of the last characters that would have otherwise shown). Commonly supplied as "..."
Properties for Auto Fit configuration on new text elements
Type:
  • Object

TextElement

Description:
  • Properties specific to new text elements - See BaseElement for common properties
Source:
Properties:
Name Type Attributes Description
text string <optional>
 The actual text to display within the textbox. Must be provided without text_markup
text_markup string <optional>
 The actual text to display within the textbox, optionally including some html tags. Must be provided without text
width number <optional>
 The width of the textbox in the unit type of the project
left number <optional>
 The x coordinate to place the textbox in the unit type of the project. Horizontally centered if not provided
top number <optional>
 The y coordinate to place the textbox in the unit type of the project. Vertically centered if not provided
color string <optional>
 The fill color to apply to the new text
default_style string <optional>
 One of: "header", "subheader", "body"
font_file_id number <optional>
 The specific font (including weight/style) to use for the new text. Will override the default_style if supplied
font_size number <optional>
 The font size to use for the new text in pt for print projects or px for all other media types. Will override the default_style if supplied
align string <optional>
 The horizontal alignment within the textbox. One of: "left", "center", "right", "justify"
vertical_anchor string <optional>
 The anchor as line wrapping occurs. One of: "top", "middle", "bottom"
opacity number <optional>
 The opacity percentage to set on the new element, between 0 and 1
auto_fit DSHDLib.Editors.ProjectData.NewElements.TextAutoFitProperties <optional>
 The Auto Fit configuration to apply
text_token_map Object.<string, string> <optional>
 A map of tokens that may be present in the text and their respective default replacement values
Properties specific to new text elements - See BaseElement for common properties
Type:

VectorElement

Description:
  • Properties specific to new vector elements - See BaseElement for common properties
Source:
Properties:
Name Type Attributes Description
vector_type string One of: "shape", "svg", "pdf"
shape_type string <optional>
 If vector_type is "shape", one of: "rectangle", "ellipse", "triangle"
url string <optional>
 If vector_type is "svg" or "pdf", the signed/public url or the data url of an SVG/PDF to import
asset DSHDLib.Editors.ProjectData.NewElements.NewElementAsset <optional>
 If vector_type is "svg", a data reference to a previously imported SVG. Must be provided without url in this case
width number <optional>
 The width of the element in the unit type of the project. Will be based off the height (preserving aspect ratio) if not supplied or sized relative to the canvas if neither are supplied
height number <optional>
 The height of the element in the unit type of the project. Will be based off the width (preserving aspect ratio) if not supplied or sized relative to the canvas if neither are supplied
left number <optional>
 The x coordinate to place the element in the unit type of the project. Horizontally centered if not provided
top number <optional>
 The y coordinate to place the element in the unit type of the project. Vertically centered if not provided
constrain_proportions bool <optional>
 A value indicating whether by default the new element should allow the user to alter its aspect ratio during resize operations
color string <optional>
 If vector_type is "shape", the fill color to apply to the new element
color_map Object.<string, string> <optional>
 A map of RGB colors in the SVG to swap with alternate colors in any supported format
opacity number <optional>
 The opacity percentage to set on the new element, between 0 and 1
Properties specific to new vector elements - See BaseElement for common properties
Type:

VideoElement

Description:
  • Properties specific to new video elements - See BaseElement for common properties
Source:
Properties:
Name Type Attributes Default Description
url string <optional>
 Signed/public url of a video file to import. Must be provided without blob or asset
blob Blob <optional>
 A Blob of a video file to import. Must be provided without url or asset
blob_file_type string <optional>
 For non-browser supported files, provide the source file extension (without the ".") of the supplied blob
asset DSHDLib.Editors.ProjectData.NewElements.NewElementAsset <optional>
 Data reference to a previously imported video. Must be provided without url or blob
width number <optional>
 The width of the video in pixels. Will be based off the height (preserving aspect ratio) if not supplied or sized relative to the canvas if neither are supplied
height number <optional>
 The height of the video in pixels. Will be based off the width (preserving aspect ratio) if not supplied or sized relative to the canvas if neither are supplied
left number <optional>
 The x coordinate to place the video in pixels. Horizontally centered if not provided
top number <optional>
 The y coordinate to place the video in pixels. Vertically centered if not provided
trim_start number <optional>
 The position in seconds to start the new video
trim_end number <optional>
 The position in seconds to end the new video
expand_scene bool <optional>
 A value indicating whether the scene should be automatically expanded (if necessary) to fully contain the new video
placement string <optional>
 "foreground" One of: "foreground", "background"
opacity number <optional>
 The opacity percentage to set on the new element, between 0 and 1
Properties specific to new video elements - See BaseElement for common properties
Type:

ZoneElement

Description:
  • Properties specific to new zone elements - See BaseElement for common properties
Source:
Properties:
Name Type Attributes Default Description
zone_type string <optional>
 "fit" One of: "fit", "mask", "pattern"
enforce_boundary bool <optional>
 true If zone_type is "fit", a value indicating whether the zone should restrict movement of its contained element to its boundary
width number <optional>
 The width of the element in the unit type of the project. Will be sized relative to the canvas if not supplied
height number <optional>
 The height of the element in the unit type of the project. Will be sized relative to the canvas if not supplied
left number <optional>
 The x coordinate to place the element in the unit type of the project. Horizontally centered if not provided
top number <optional>
 The y coordinate to place the element in the unit type of the project. Vertically centered if not provided
opacity number <optional>
 The default opacity percentage to apply to elements added to the new zone element, between 0 and 1. Note that this can be overridden on the contained element itself
Properties specific to new zone elements - See BaseElement for common properties
Type: