Settings

All keys listed below can be modified through the Editor API. The nested settings inside UBQSettings can be reached via key paths, e.g. page/title/show.

Settings

`BlockAnimationSettings`

Member	Type	Default	Description
enabled	`bool`	`true`	Whether animations should be enabled or not.

`CameraClampingSettings`

Member	Type	Default	Description
overshootMode	`CameraClampingOvershootMode`	`Reverse`	Controls what happens when the clamp area is smaller than the viewport. Center: the clamp area is centered in the viewport. Reverse: the clamp area can move inside the viewport until it hits the edges.

`CameraSettings`

Member	Type	Default	Description
clamping	`CameraClampingSettings: CameraClampingOvershootMode overshootMode`	`{}`	Clamping settings for the camera.

`ControlGizmoSettings`

Member	Type	Default	Description
blockScaleDownLimit	`float`	`8.0`	Scale-down limit for blocks in screen pixels when scaling them with the gizmos or with touch gestures. The limit is ensured to be at least 0.1 to prevent scaling to size zero.
showCropHandles	`bool`	`{true}`	Whether or not to show the handles to adjust the crop area during crop mode.
showCropScaleHandles	`bool`	`{true}`	Whether or not to display the outer handles that scale the full image during crop.
showMoveHandles	`bool`	`{true}`	Whether or not to show the move handles.
showResizeHandles	`bool`	`{true}`	Whether or not to display the non-proportional resize handles (edge handles)
showRotateHandles	`bool`	`{true}`	Whether or not to show the rotation handles.
showScaleHandles	`bool`	`{true}`	Whether or not to display the proportional scale handles (corner handles)

`DebugFlags`

Flags that control debug outputs.

Member	Type	Default	Description
enforceScopesInAPIs	`bool`	`false`	Whether APIs calls that perform edits should throw errors if the corresponding scope does not allow the edit.
showHandlesInteractionArea	`bool`	`{false}`	Display the interaction area around the handles.
useDebugMipmaps	`bool`	`false`	Enable the use of colored mipmaps to see which mipmap is used.

`MouseSettings`

Member	Type	Default	Description
enableScroll	`bool`	`true`	Whether the engine processes mouse scroll events.
enableZoom	`bool`	`true`	Whether the engine processes mouse zoom events.

`PageSettings`

Member	Type	Default	Description
allowCropInteraction	`bool`	`true`	If crop interaction (by handles and gestures) should be possible when the enabled arrangements allow resizing.
allowMoveInteraction	`bool`	`false`	If move interaction (by handles and gestures) should be possible when the enabled arrangements allow moving and if the page layout is not controlled by the scene, e.g., in a ‘VerticalStack’.
allowResizeInteraction	`bool`	`false`	If a resize interaction (by handles and gestures) should be possible when the enabled arrangements allow resizing.
allowRotateInteraction	`bool`	`false`	If rotation interaction (by handles and gestures) should be possible when the enabled arrangements allow rotation and if the page layout is not controlled by the scene, e.g., in a ‘VerticalStack’.
dimOutOfPageAreas	`bool`	`true`	Whether the opacity of the region outside of all pages should be reduced.
innerBorderColor	`Color`	`createRGBColor(0.0, 0.0, 0.0, 0.0)`	Color of the inner frame around the page.
marginFillColor	`Color`	`createRGBColor(0.79, 0.12, 0.40, 0.1)`	Color of frame around the bleed margin area of the pages.
marginFrameColor	`Color`	`createRGBColor(0.79, 0.12, 0.40, 0.0)`	Color filled into the bleed margins of pages.
moveChildrenWhenCroppingFill	`bool`	`false`	Whether the children of the page should be transformed to match their old position relative to the page fill when a page fill is cropped.
outerBorderColor	`Color`	`createRGBColor(1.0, 1.0, 1.0, 0.0)`	Color of the outer frame around the page.
restrictResizeInteractionToFixedAspectRatio	`bool`	`false`	If the resize interaction should be restricted to fixed aspect ratio resizing.
title	`PageTitleSettings(bool show, bool showOnSinglePage, bool showPageTitleTemplate, bool appendPageName, string separator, Color color, string fontFileUri)`	“	Page title settings.

`PageTitleSettings`

Member	Type	Default	Description
appendPageName	`bool`	`true`	Whether to append the page name to the title if a page name is set even if the name is not specified in the template or the template is not shown
color	`Color`	`createRGBColor(1., 1., 1.)`	Color of page titles visible in preview mode, can change with different themes.
fontFileUri	`string`	`DEFAULT_FONT`	Font of page titles.
separator	`string`	`"-"`	Title label separator between the page number and the page name.
show	`bool`	`true`	Whether to show titles above each page.
showOnSinglePage	`bool`	`true`	Whether to hide the the page title when only a single page is given.
showPageTitleTemplate	`bool`	`true`	Whether to include the default page title from `page.titleTemplate`

`PlaceholderControlsSettings`

Member	Type	Default	Description
showButton	`bool`	`true`	Show the placeholder button.
showOverlay	`bool`	`true`	Show the overlay pattern.

`Settings`

Member	Type	Default	Description
alwaysHighlightPlaceholders	`bool`	`false`	Whether placeholder elements should always be highlighted in the scene.
basePath	`string`	`""`	The root directory to be used when resolving relative paths or when accessing `bundle://` URIs on platforms that don’t offer bundles.
blockAnimations	`BlockAnimationSettings: bool enabled`	`{}`	Settings that configure the behavior of block animations.
borderOutlineColor	`Color`	`createRGBColor(0., 0., 0., 1.0)`	The border outline color, defaults to black.
camera	`CameraSettings: CameraClampingSettings clamping`	`{}`	Settings that configure the behavior of the camera.
clearColor	`Color`	`createClear()`	The color with which the render target is cleared before scenes get rendered. Only used while renderMode == Preview, else #00000000 (full transparency) is used.
colorMaskingSettings	`ColorMaskingSettings(Color maskColor, bool secondPass)`	`{}`	A collection of settings used to perform color masking.
controlGizmo	`ControlGizmoSettings(bool showCropHandles, bool showCropScaleHandles, bool showMoveHandles, bool showResizeHandles, bool showScaleHandles, bool showRotateHandles, float blockScaleDownLimit)`	`{}`	Settings that configure which touch/click targets for move/scale/rotate/etc. are enabled and displayed.
cropOverlayColor	`Color`	`createRGBColor(0., 0., 0., 0.39)`	Color of the dimming overlay that’s added in crop mode.
debug	`DebugFlags(bool useDebugMipmaps, bool showHandlesInteractionArea, bool enforceScopesInAPIs)`	`{}`	?
defaultEmojiFontFileUri	`string`	`EMOJI_FONT`	URI of default font file for emojis.
defaultFontFileUri	`string`	`DEFAULT_FONT`	URI of default font file This font file is the default everywhere unless overriden in specific settings.
doubleClickSelectionMode	`DoubleClickSelectionMode`	`Hierarchical`	The current mode of selection on double-click.
doubleClickToCropEnabled	`bool`	`true`	Whether double clicking on an image element should switch into the crop editing mode.
emscriptenCORSConfigurations	`vector< CORSConfiguration >`	`{}`	CORS Configurations: `<origin, value>` pairs. See `FetchAsyncService-emscripten.cpp` for details.
errorStateColor	`Color`	`createRGBColor(1., 1., 1., 0.7)`	The error state color for design blocks.
fallbackFontUri	`string`	`""`	The URI of the fallback font to use for text that is missing certain characters.
forceSystemEmojis	`bool`	`true`	Whether the system emojis should be used for text.
globalScopes	`GlobalScopes(Text text, Fill fill, Stroke stroke, Shape shape, Layer layer, Appearance appearance, Lifecycle lifecycle, Editor editor)`	`Allow)`	Global scopes.
handleFillColor	`Color`	`createWhite()`	The fill color for handles.
highlightColor	`Color`	`createRGBColor(0.2, 85. / 255., 1.)`	Color of the selection, hover, and group frames and for the handle outlines for non-placeholder elements.
license	`string`	`""`	A valid license string in JWT format.
maxImageSize	`int`	`4096`	The maximum size at which images are loaded into the engine. Images that exceed this size are down-scaled prior to rendering. Reducing this size further reduces the memory footprint. Defaults to 4096x4096.
mouse	`MouseSettings(bool enableZoom, bool enableScroll)`	`{}`	Settings that configure the behavior of the mouse.
page	`PageSettings(PageTitleSettings title, Color marginFillColor, Color marginFrameColor, Color innerBorderColor, Color outerBorderColor, bool dimOutOfPageAreas, bool allowCropInteraction, bool allowResizeInteraction, bool restrictResizeInteractionToFixedAspectRatio, bool allowRotateInteraction, bool allowMoveInteraction, bool moveChildrenWhenCroppingFill)`	`{}`	Page related settings.
placeholderControls	`PlaceholderControlsSettings(bool showOverlay, bool showButton)`	`{}`	Supersedes how the blocks’ placeholder controls are applied.
placeholderHighlightColor	`Color`	`createRGBColor(0.77, 0.06, 0.95)`	Color of the selection, hover, and group frames and for the handle outlines for placeholder elements.
positionSnappingThreshold	`float`	`4.`	Position snapping threshold in screen space.
progressColor	`Color`	`createRGBColor(1., 1., 1., 0.7)`	The progress indicator color.
renderTextCursorAndSelectionInEngine	`bool`	`true`	Whether the engine should render the text cursor and selection highlights during text editing. This can be set to false, if the platform wants to perform this rendering itself.
rotationSnappingGuideColor	`Color`	`createRGBColor(1., 0.004, 0.361)`	Color of the rotation snapping guides.
rotationSnappingThreshold	`float`	`0.15`	Rotation snapping threshold in radians.
ruleOfThirdsLineColor	`Color`	`createRGBColor(0.75, 0.75, 0.75, 0.75)`	Color of the rule-of-thirds lines.
showBuildVersion	`bool`	`false`	Show the build version on the canvas.
snappingGuideColor	`Color`	`createRGBColor(1., 0.004, 0.361)`	Color of the position snapping guides.
textVariableHighlightColor	`Color`	`createRGBColor(0.7, 0., 0.7)`	Color of the text variable highlighting borders.
touch	`TouchSettings(bool dragStartCanSelect, bool singlePointPanning, PinchGestureAction pinchAction, RotateGestureAction rotateAction)`	`{}`	Settings that configure which touch gestures are enabled and which actions they trigger.
useSystemFontFallback	`bool`	`false`	Whether the IMG.LY hosted font fallback is used for fonts that are missing certain characters, covering most of the unicode range.

`TouchSettings`

Member	Type	Default	Description
dragStartCanSelect	`bool`	`true`	Whether dragging an element requires selecting it first. When not set, elements can be directly dragged.
pinchAction	`PinchGestureAction`	`Scale`	The action to perform when a pinch gesture is performed.
rotateAction	`RotateGestureAction`	`Rotate`	Whether or not the two finger turn gesture can rotate selected elements.
singlePointPanning	`bool`	`true`	Whether or not dragging on the canvas should move the camera (scrolling). When not set, the scroll bars have to be used. This setting might get overwritten with the feature flag `preventScrolling`.

engine.editor.findAllSettings();
engine.editor.getSettingType('doubleClickSelectionMode');

const unsubscribeSettings = engine.editor.onSettingsChanged(() =>
  console.log('Editor settings have changed');
);

const unsubscribeRoleChange = engine.editor.onRoleChanged((role) => {
  console.log('Role': role);
});

engine.editor.setSettingBool('doubleClickToCropEnabled', true);
engine.editor.getSettingBool('doubleClickToCropEnabled');
engine.editor.setSettingInt('integerSetting', 0);
engine.editor.getSettingInt('integerSetting');
engine.editor.setSettingFloat('positionSnappingThreshold', 2.0);
engine.editor.getSettingFloat('positionSnappingThreshold');
engine.editor.setSettingString('license', 'invalid');
engine.editor.getSettingString('license');
engine.editor.setSettingColor('highlightColor', { r: 1, g: 0, b: 1, a: 1 }); // Pink
engine.editor.getSettingColor('highlightColor');
engine.editor.setSettingEnum('doubleClickSelectionMode', 'Direct');
engine.editor.getSettingEnum('doubleClickSelectionMode');
engine.editor.getSettingEnumOptions('doubleClickSelectionMode');
engine.editor.getRole();
engine.editor.setRole('Adopter');

Change Settings

In this example, we will show you how to use the CreativeEditor SDK’s CreativeEngine to control with the editor API. A list of all available settings can be found above.

Exploration

findAllSettings(): string[]

Returns a list of all the settings available.

Returns A list of settings keypaths.

getSettingType(keypath: string): SettingType

Returns the type of a setting.

keypath: The settings keypath, e.g. doubleClickSelectionMode.
Returns The setting type.

Functions

onSettingsChanged: (callback: () => void) => (() => void)

Subscribe to changes to the editor settings.

callback: This function is called at the end of the engine update, if the editor settings have changed.
Returns A method to unsubscribe.

onRoleChanged: (callback: (role: RoleString) => void) => (() => void)

Subscribe to changes to the editor role. This lets you react to changes in the role of the user and update engine and editor settings in response.

callback: This function will be called immediately after a role has been set and the default settings for that role have been applied. This function will also be called in case the role is set to the same value as before.
Returns A function for unsubscribing

setSettingBool(keypath: SettingsBool, value: boolean): void

Set a boolean setting.

keypath: The settings keypath, e.g. doubleClickToCropEnabled
value: The value to set.
Throws An error, if the keypath is invalid.

setSettingBool(keypath: `ubq://${SettingsBool}`, value: boolean): void

Support for ubq:// prefixed keypaths will be removed in a future release.

getSettingBool(keypath: SettingsBool): boolean

Get a boolean setting.

keypath: The settings keypath, e.g. doubleClickToCropEnabled
Throws An error, if the keypath is invalid.

getSettingBool(keypath: `ubq://${SettingsBool}`): boolean

Support for ubq:// prefixed keypaths will be removed in a future release.

setSettingInt(keypath: string, value: number): void

Set an integer setting.

keypath: The settings keypath.
value: The value to set.
Throws An error, if the keypath is invalid.

getSettingInt(keypath: string): number

Get an integer setting.

keypath: The settings keypath.
Throws An error, if the keypath is invalid.

setSettingFloat(keypath: SettingsFloat, value: number): void

Set a float setting.

keypath: The settings keypath, e.g. positionSnappingThreshold
value: The value to set.
Throws An error, if the keypath is invalid.

setSettingFloat(keypath: `ubq://${SettingsFloat}`, value: number): void

Support for ubq:// prefixed keypaths will be removed in a future release.

getSettingFloat(keypath: SettingsFloat): number

Get a float setting.

keypath: The settings keypath, e.g. positionSnappingThreshold
Throws An error, if the keypath is invalid.

getSettingFloat(keypath: `ubq://${SettingsFloat}`): number

Support for ubq:// prefixed keypaths will be removed in a future release.

setSettingString(keypath: SettingsString, value: string): void

Set a string setting.

keypath: The settings keypath, e.g. license
value: The value to set.
Throws An error, if the keypath is invalid.

setSettingString(keypath: `ubq://${SettingsString}`, value: string): void

Support for ubq:// prefixed keypaths will be removed in a future release.

getSettingString(keypath: SettingsString): string

Get a string setting.

keypath: The settings keypath, e.g. license
Throws An error, if the keypath is invalid.

getSettingString(keypath: `ubq://${SettingsString}`): string

Support for ubq:// prefixed keypaths will be removed in a future release.

setSettingColor(keypath: SettingsColor, value: Color): void

Set a color setting.

keypath: The settings keypath, e.g. highlightColor.
value: The The value to set.

setSettingColor(keypath: `ubq://${SettingsColor}`, value: Color): void

Support for ubq:// prefixed keypaths will be removed in a future release.

getSettingColor(keypath: SettingsColor): Color

Get a color setting.

keypath: The settings keypath, e.g. highlightColor.
Throws An error, if the keypath is invalid.

getSettingColor(keypath: `ubq://${SettingsColor}`): Color

Support for ubq:// prefixed keypaths will be removed in a future release.

setSettingEnum<T extends keyof SettingsEnum>(keypath: T, value: SettingsEnum[T]): void

Set an enum setting.

keypath: The settings keypath, e.g. doubleClickSelectionMode.
value: The enum value as string.

setSettingEnum<T extends keyof SettingsEnum>(keypath: `ubq://${T}`, value: SettingsEnum[T]): void

Support for ubq:// prefixed keypaths will be removed in a future release.

getSettingEnum<T extends keyof SettingsEnum>(keypath: T): SettingsEnum[T]

Get an enum setting.

keypath: The settings keypath, e.g. doubleClickSelectionMode.
Returns The value as string.

getSettingEnum<T extends keyof SettingsEnum>(keypath: `ubq://${T}`): SettingsEnum[T]

Support for ubq:// prefixed keypaths will be removed in a future release.

getSettingEnumOptions<T extends keyof SettingsEnum>(keypath: T): string[]

Get the possible enum options for a given enum setting.

keypath: The settings keypath, e.g. doubleClickSelectionMode.
Returns The possible enum options as strings.

getSettingEnumOptions<T extends keyof SettingsEnum>(keypath: `ubq://${T}`): string[]

Support for ubq:// prefixed keypaths will be removed in a future release.

getRole(): RoleString

Get the current role of the user

setRole(role: RoleString): void

Set the role of the user and apply role-dependent defaults for scopes and settings

Full Code

Here’s the full code:

engine.editor.findAllSettings();
engine.editor.getSettingType('doubleClickSelectionMode');

const unsubscribeSettings = engine.editor.onSettingsChanged(() =>
  console.log('Editor settings have changed');
);

const unsubscribeRoleChange = engine.editor.onRoleChanged((role) => {
  console.log('Role': role);
});

engine.editor.setSettingBool('doubleClickToCropEnabled', true);
engine.editor.getSettingBool('doubleClickToCropEnabled');
engine.editor.setSettingInt('integerSetting', 0);
engine.editor.getSettingInt('integerSetting');
engine.editor.setSettingFloat('positionSnappingThreshold', 2.0);
engine.editor.getSettingFloat('positionSnappingThreshold');
engine.editor.setSettingString('license', 'invalid');
engine.editor.getSettingString('license');
engine.editor.setSettingColor('highlightColor', { r: 1, g: 0, b: 1, a: 1 }); // Pink
engine.editor.getSettingColor('highlightColor');
engine.editor.setSettingEnum('doubleClickSelectionMode', 'Direct');
engine.editor.getSettingEnum('doubleClickSelectionMode');
engine.editor.getSettingEnumOptions('doubleClickSelectionMode');
engine.editor.getRole();
engine.editor.setRole('Adopter');