CSInterface

class Version(major, minor, micro, special)

Version Defines a version number with major, minor, micro, and special components. The major, minor and micro values are numeric; the special value can be any string.

Arguments:
  • major – The major version component, a positive integer up to nine digits long.
  • minor – The minor version component, a positive integer up to nine digits long.
  • micro – The micro version component, a positive integer up to nine digits long.
  • special – The special version component, an arbitrary string.
Returns:

A new Version() object.
Version.MAX_NUM

The maximum value allowed for a numeric version component. This reflects the maximum value allowed in PlugPlug and the manifest schema.

class VersionBound(version, inclusive)

VersionBound Defines a boundary for a version range, which associates a Version() object with a flag for whether it is an inclusive or exclusive boundary.

Arguments:
  • version – The Version() object.
  • inclusive – True if this boundary is inclusive, false if it is exclusive.
Returns:

A new VersionBound() object.
class VersionRange(lowerBound, upperBound)

VersionRange Defines a range of versions using a lower boundary and optional upper boundary.

Arguments:
  • lowerBound – The :js:class: VersionBound() object.
  • upperBound – The :js:class: VersionBound() object, or null for a range with no upper boundary.
Returns:

A new VersionRange() object.
class Runtime(name, versionRange)

Runtime Represents a runtime related to the CEP infrastructure. Extensions can declare dependencies on particular CEP runtime versions in the extension manifest.

Arguments:
  • name – The runtime name.
  • version – A VersionRange() object that defines a range of valid versions.
Returns:

A new Runtime() object.
class Extension(id, name, mainPath, basePath, windowType, width, height, minWidth, minHeight, maxWidth, maxHeight, defaultExtensionDataXml, specialExtensionDataXml, requiredRuntimeList, isAutoVisible, isPluginExtension)

Extension Encapsulates a CEP-based extension to an Adobe application.

Arguments:
  • id – The unique identifier of this extension.
  • name – The localizable display name of this extension.
  • mainPath – The path of the “index.html” file.
  • basePath – The base path of this extension.
  • windowType – The window type of the main window of this extension. Valid values are defined by CSXSWindowType().
  • width – The default width in pixels of the main window of this extension.
  • height – The default height in pixels of the main window of this extension.
  • minWidth – The minimum width in pixels of the main window of this extension.
  • minHeight – The minimum height in pixels of the main window of this extension.
  • maxWidth – The maximum width in pixels of the main window of this extension.
  • maxHeight – The maximum height in pixels of the main window of this extension.
  • defaultExtensionDataXml – The extension data contained in the default ExtensionDispatchInfo() section of the extension manifest.
  • specialExtensionDataXml – The extension data contained in the application-specific ExtensionDispatchInfo() section of the extension manifest.
  • requiredRuntimeList – An array of Runtime() objects for runtimes required by this extension.
  • isAutoVisible – True if this extension is visible on loading.
  • isPluginExtension – True if this extension has been deployed in the Plugins folder of the host application.
Returns:

A new Extension() object.
class CSEvent(type, scope, appId, extensionId)

CSEvent A standard JavaScript event, the base class for CEP events.

Arguments:
  • type – The name of the event type.
  • scope – The scope of event, can be “GLOBAL” or “APPLICATION”.
  • appId – The unique identifier of the application that generated the event.
  • extensionId – The unique identifier of the extension that generated the event.
Returns:

A new CSEvent() object
CSEvent.data

Event-specific data.

class SystemPath()

SystemPath Stores operating-system-specific location constants for use in the CSInterface().getSystemPath() method.

Returns:A new SystemPath() object.
SystemPath.APPLICATION
SystemPath.COMMON_FILES

The path to common files for Adobe applications.

SystemPath.EXTENSION

The path to current extension.

SystemPath.HOST_APPLICATION

The path to hosting application’s executable.

SystemPath.MY_DOCUMENTS

The path to the user’s default document folder.

SystemPath.USER_DATA

The path to user data.

class ColorType()

ColorType Stores color-type constants.

ColorType.GRADIENT

Gradient color type.

ColorType.NONE

Null color type.

ColorType.RGB

RGB color type.

class RGBColor(red, green, blue, alpha)

RGBColor Stores an RGB color with red, green, blue, and alpha values. All values are in the range [0.0 to 255.0]. Invalid numeric values are converted to numbers within this range.

Arguments:
  • red – The red value, in the range [0.0 to 255.0].
  • green – The green value, in the range [0.0 to 255.0].
  • blue – The blue value, in the range [0.0 to 255.0].
  • alpha – The alpha (transparency) value, in the range [0.0 to 255.0]. The default, 255.0, means that the color is fully opaque.
Returns:

A new RGBColor object.
class Direction(x, y)

Direction A point value in which the y component is 0 and the x component is positive or negative for a right or left direction, or the x component is 0 and the y component is positive or negative for an up or down direction.

Arguments:
  • x – The horizontal component of the point.
  • y – The vertical component of the point.
Returns:

A new Direction() object.
class GradientStop(offset, rgbColor)

GradientStop Stores gradient stop information.

Arguments:
  • offset – The offset of the gradient stop, in the range [0.0 to 1.0].
  • rgbColor – The color of the gradient at this point, an RGBColor() object.
Returns:

GradientStop object.
class GradientColor(type, direction, numStops, arrGradientStop)

GradientColor Stores gradient color information.

Arguments:
  • type – The gradient type, must be “linear”.
  • direction – A Direction() object for the direction of the gradient (up, down, right, or left).
  • numStops – The number of stops in the gradient.
  • gradientStopList – An array of GradientStop() objects.
Returns:

A new GradientColor() object.
class UIColor(type, antialiasLevel, color)

UIColor Stores color information, including the type, anti-alias level, and specific color values in a color object of an appropriate type.

Arguments:
  • type – The color type, 1 for “rgb” and 2 for “gradient”. The supplied color object must correspond to this type.
  • antialiasLevel – The anti-alias level constant.
  • color – A RGBColor() or GradientColor() object containing specific color information.
Returns:

A new UIColor() object.
class AppSkinInfo(baseFontFamily, baseFontSize, appBarBackgroundColor, panelBackgroundColor, appBarBackgroundColorSRGB, panelBackgroundColorSRGB, systemHighlightColor)

AppSkinInfo Stores window-skin properties, such as color and font. All color parameter values are UIColor() objects except that systemHighlightColor is RGBColor() object.

Arguments:
  • baseFontFamily – The base font family of the application.
  • baseFontSize – The base font size of the application.
  • appBarBackgroundColor – The application bar background color.
  • panelBackgroundColor – The background color of the extension panel.
  • appBarBackgroundColorSRGB – The application bar background color, as sRGB.
  • panelBackgroundColorSRGB – The background color of the extension panel, as sRGB.
  • systemHighlightColor – The operating-system highlight color, as sRGB.
Returns:

AppSkinInfo object.
class HostEnvironment(appName, appVersion, appLocale, appUILocale, appId, isAppOnline, appSkinInfo)

HostEnvironment Stores information about the environment in which the extension is loaded.

Arguments:
  • appName – The application’s name.
  • appVersion – The application’s version.
  • appLocale – The application’s current license locale.
  • appUILocale – The application’s current UI locale.
  • appId – The application’s unique identifier.
  • isAppOnline – True if the application is currently online.
  • appSkinInfo – An AppSkinInfo() object containing the application’s default color and font styles.
Returns:

A new HostEnvironment() object.
class HostCapabilities(EXTENDED_PANEL_MENU, EXTENDED_PANEL_ICONS, DELEGATE_APE_ENGINE, SUPPORT_HTML_EXTENSIONS, DISABLE_FLASH_EXTENSIONS)

HostCapabilities Stores information about the host capabilities.

Arguments:
  • EXTENDED_PANEL_MENU – True if the application supports panel menu.
  • EXTENDED_PANEL_ICONS – True if the application supports panel icon.
  • DELEGATE_APE_ENGINE – True if the application supports delegated APE engine.
  • SUPPORT_HTML_EXTENSIONS – True if the application supports HTML extensions.
  • DISABLE_FLASH_EXTENSIONS – True if the application disables FLASH extensions.
Returns:

A new HostCapabilities() object.
class ApiVersion(major, minor, micro)

ApiVersion Stores current api version.

Since 4.2.0

Arguments:
  • major – The major version
  • minor – The minor version.
  • micro – The micro version.
Returns:

ApiVersion object.

MenuItemStatus Stores flyout menu item status

Since 5.2.0

Arguments:
  • menuItemLabel – The menu item label.
  • enabled – True if user wants to enable the menu item.
  • checked – True if user wants to check the menu item.
Returns:

MenuItemStatus object.
class ContextMenuItemStatus(menuItemID, enabled, checked)

ContextMenuItemStatus Stores the status of the context menu item.

Since 5.2.0

Arguments:
  • menuItemID – The menu item id.
  • enabled – True if user wants to enable the menu item.
  • checked – True if user wants to check the menu item.
Returns:

MenuItemStatus object.
class CSInterface()

CSInterface This is the entry point to the CEP extensibility infrastructure. Instantiate this object and use it to:

  • Access information about the host application in which an extension is running
  • Launch an extension
  • Register interest in event notifications, and dispatch events
Returns:A new CSInterface() object
CSInterface.THEME_COLOR_CHANGED_EVENT

User can add this event listener to handle native application theme color changes. Callback function gives extensions ability to fine-tune their theme color after the global theme color has been changed. The callback function should be like below:

Examples:

// event is a CSEvent object, but user can ignore it.
function OnAppThemeColorChanged(event)
{
   // Should get a latest HostEnvironment object from application.
   var skinInfo = JSON.parse(window.__adobe_cep__.getHostEnvironment()).appSkinInfo;
   // Gets the style information such as color info from the skinInfo,
   // and redraw all UI controls of your extension according to the style info.
}
CSInterface.addEventListener(type, listener, obj)

Registers an interest in a CEP event of a particular type, and assigns an event handler. The event infrastructure notifies your extension when events of this type occur, passing the event object to the registered handler function.

Arguments:
  • type – The name of the event type of interest.
  • listener – The JavaScript handler function or method.
  • obj – Optional, the object containing the handler method, if any. Default is null.
CSInterface.closeExtension()

Closes this extension.

CSInterface.dispatchEvent(event)

Triggers a CEP event programmatically. Yoy can use it to dispatch an event of a predefined type, or of a type you have defined.

Arguments:
CSInterface.dumpInstallationInfo()

Writes installation information to a file.

Returns:The file path.
CSInterface.evalScript(script, callback)

Evaluates a JavaScript script, which can use the JavaScript DOM of the host application.

Arguments:
  • script – The JavaScript script.
  • callback – Optional. A callback function that receives the result of execution. If execution fails, the callback function receives the error message EvalScript_ErrMessage().
CSInterface.getApplicationID()

Retrieves the unique identifier of the application. in which the extension is currently running.

Returns:The unique ID string.
CSInterface.getCurrentApiVersion()

Retrieves current API version.

Since 4.2.0

Returns:ApiVersion object.
CSInterface.getExtensionID()

Retrieves extension ID.

Since 4.2.0

Returns:extension ID.
CSInterface.getExtensions(extensionIds)

Retrieves the list of extensions currently loaded in the current host application. The extension list is initialized once, and remains the same during the lifetime of the CEP session.

Arguments:
  • extensionIds – Optional, an array of unique identifiers for extensions of interest. If omitted, retrieves data for all extensions.
Returns:

Zero or more Extension() objects.
CSInterface.getHostCapabilities()

Retrieves host capability information for the application in which the extension is currently running.

Returns:A HostCapabilities() object.
CSInterface.getHostEnvironment()

Retrieves information about the host environment in which the extension is currently running.

Returns:A HostEnvironment() object.
CSInterface.getNetworkPreferences()

Retrieves network-related preferences.

Returns:A JavaScript object containing network preferences.
CSInterface.getOSInformation()

Retrieves version information for the current Operating System, See http://www.useragentstring.com/pages/Chrome/ for Chrome navigator().userAgent values.

If user customizes the User Agent by setting CEF command parameter “–user-agent”, only “Mac OS X” or “Windows” will be returned.

Returns:A string containing the OS version, or “unknown Operation System”.
CSInterface.getScaleFactor()

Retrieves the scale factor of screen. On Windows platform, the value of scale factor might be different from operating system’s scale factor, since host application may use its self-defined scale factor.

  • -1.0 when error occurs
  • 1.0 means normal screen
  • >1.0 means HiDPI screen

Since 4.2.0

Returns:Number
CSInterface.getSystemPath(pathType)

Retrieves a path for which a constant is defined in the system.

Arguments:
  • pathType – The path-type constant defined in SystemPath() ,
Returns:

The platform-specific system path string.
CSInterface.getWindowTitle()

Get the title of the extension window. This function works with modal and modeless extensions in all Adobe products, and panel extensions in Photoshop, InDesign, InCopy, Illustrator, Flash Pro and Dreamweaver.

Since 6.1.0

Returns:The window title.
CSInterface.hostEnvironment

The host environment data object.

CSInterface.initResourceBundle()

Initializes the resource bundle for this extension with property values for the current application and locale. To support multiple locales, you must define a property file for each locale, containing keyed display-string values for that locale. See localization documentation for Extension Builder and related products.

Keys can be in the form <code>key.value=”localized string”</code>, for use in HTML text elements. For example, in this input element, the localized key().value string is displayed instead of the empty value() string:

<code><input type=”submit” value=”” data-locale=”key”/></code>

Returns:An object containing the resource bundle information.
CSInterface.isWindowVisible()

Get the visibility status of an extension window.

Since 6.0.0

Returns:true if the extension window is visible; false if the extension window is hidden.
CSInterface.openURLInDefaultBrowser(url)

Opens a page in the default system browser.

Since 4.2.0

Arguments:
Returns:

One of these error codes: * NO_ERROR - 0 * ERR_UNKNOWN - 1 * ERR_INVALID_PARAMS - 2 * ERR_INVALID_URL - 201
CSInterface.registerInvalidCertificateCallback(callback)

Register the invalid certificate callback for an extension. This callback will be triggered when the extension tries to access the web site that contains the invalid certificate on the main frame. But if the extension does not call this function and tries to access the web site containing the invalid certificate, a default error page will be shown.

Since 6.1.0

Arguments:
  • callback – the callback function
CSInterface.registerKeyEventsInterest(keyEventsInterest)

Register an interest in some key events to prevent them from being sent to the host application.

This function works with modeless extensions and panel extensions. Generally all the key events will be sent to the host application for these two extensions if the current focused element is not text input or dropdown, If you want to intercept some key events and want them to be handled in the extension, please call this function in advance to prevent them being sent to the host application.

Since 6.1.0

This JSON string should be an array, each object has following keys:

  • keyCode: [Required] represents an OS system dependent virtual key code identifying the unmodified value of the pressed key.
  • ctrlKey: [optional] a Boolean that indicates if the control key was pressed (true) or not (false) when the event occurred.
  • altKey: [optional] a Boolean that indicates if the alt key was pressed (true) or not (false) when the event occurred.
  • shiftKey: [optional] a Boolean that indicates if the shift key was pressed (true) or not (false) when the event occurred.
  • metaKey: [optional] (Mac Only) a Boolean that indicates if the Meta key was pressed (true) or not (false) when the event occurred. On Macintosh keyboards, this is the command key. To detect Windows key on Windows, please use keyCode instead.

An example JSON string:

[
    {
        "keyCode": 48
    },
    {
        "keyCode": 123,
        "ctrlKey": true
    },
    {
        "keyCode": 123,
        "ctrlKey": true,
        "metaKey": true
    }
]
Arguments:
  • keyEventsInterest – A JSON string describing those key events you are interested in. A null object or an empty string will lead to removing the interest
CSInterface.removeEventListener(type, listener, obj)

Removes a registered event listener.

Arguments:
  • type – The name of the event type of interest.
  • listener – The JavaScript handler function or method that was registered.
  • obj – Optional, the object containing the handler method, if any. Default is null.
CSInterface.requestOpenExtension(extensionId, params)

Loads and launches another extension, or activates the extension if it is already loaded.

Arguments:
  • extensionId – The extension’s unique identifier.
  • startupParams – Not currently used, pass “”.

Examples:

To launch the extension "help" with ID "HLP" from this extension, call:
<code>requestOpenExtension("HLP", ""); </code>
CSInterface.resizeContent(width, height)

Resize extension’s content to the specified dimensions. 1. Works with modal and modeless extensions in all Adobe products. 2. Extension’s manifest min/max size constraints apply and take precedence. 3. For panel extensions

3.1 This works in all Adobe products except:
  • Premiere Pro
  • Prelude
  • After Effects
3.2 When the panel is in certain states (especially when being docked),
it will not change to the desired dimensions even when the specified size satisfies min/max constraints.

Since 6.0.0

Arguments:
  • width – The new width
  • height – The new height
CSInterface.setContextMenu(menu, callback)

An example menu XML:

<Menu>
  <MenuItem Id="menuItemId1" Label="TestExample1" Enabled="true" Checkable="true" Checked="false" Icon="./image/small_16X16.png"/>
  <MenuItem Id="menuItemId2" Label="TestExample2">
    <MenuItem Id="menuItemId2-1" Label="TestExample2-1" >
      <MenuItem Id="menuItemId2-1-1" Label="TestExample2-1-1" Enabled="false" Checkable="true" Checked="true"/>
    </MenuItem>
    <MenuItem Id="menuItemId2-2" Label="TestExample2-2" Enabled="true" Checkable="true" Checked="true"/>
  </MenuItem>
  <MenuItem Label="---" />
  <MenuItem Id="menuItemId3" Label="TestExample3" Enabled="false" Checkable="true" Checked="false"/>
</Menu></code>
Arguments:
  • menu – A XML string which describes menu structure.
  • callback – The callback function which is called when a menu item is clicked. The only parameter is the returned ID of clicked menu item.
CSInterface.setContextMenuByJSON(menu, callback)

An example menu JSON:

{
     "menu": [
         {
             "id": "menuItemId1",
             "label": "testExample1",
             "enabled": true,
             "checkable": true,
             "checked": false,
             "icon": "./image/small_16X16.png"
         },
         {
             "id": "menuItemId2",
             "label": "testExample2",
             "menu": [
                 {
                     "id": "menuItemId2-1",
                     "label": "testExample2-1",
                     "menu": [
                         {
                             "id": "menuItemId2-1-1",
                             "label": "testExample2-1-1",
                             "enabled": false,
                             "checkable": true,
                             "checked": true
                         }
                     ]
                 },
                 {
                     "id": "menuItemId2-2",
                     "label": "testExample2-2",
                     "enabled": true,
                     "checkable": true,
                     "checked": true
                 }
             ]
         },
         {
             "label": "---"
         },
         {
             "id": "menuItemId3",
             "label": "testExample3",
             "enabled": false,
             "checkable": true,
             "checked": false
         }
     ]
 }
Arguments:
  • menu – A JSON string which describes menu structure.
  • callback – The callback function which is called when a menu item is clicked. The only parameter is the returned ID of clicked menu item.
CSInterface.setPanelFlyoutMenu(menu)

An example menu XML:

<Menu>
  <MenuItem Id="menuItemId1" Label="TestExample1" Enabled="true" Checked="false"/>
  <MenuItem Label="TestExample2">
    <MenuItem Label="TestExample2-1" >
      <MenuItem Label="TestExample2-1-1" Enabled="false" Checked="true"/>
    </MenuItem>
    <MenuItem Label="TestExample2-2" Enabled="true" Checked="true"/>
  </MenuItem>
  <MenuItem Label="---" />
  <MenuItem Label="TestExample3" Enabled="false" Checked="false"/>
</Menu>
Arguments:
  • menu – A XML string which describes menu structure.
CSInterface.setScaleFactorChangedHandler(handler)

Set a handler to detect any changes of scale factor. This only works on Mac.

Since 4.2.0

Arguments:
  • handler – The function to be called when scale factor is changed.
CSInterface.setWindowTitle(title)

Set the title of the extension window. This function works with modal and modeless extensions in all Adobe products, and panel extensions in Photoshop, InDesign, InCopy, Illustrator, Flash Pro and Dreamweaver.

Since 6.1.0

Arguments:
  • title – The window title.
CSInterface.updateContextMenuItem(menuItemID, enabled, checked)

Updates a context menu item by setting the enabled and selection status.

Since 5.2.0

Arguments:
  • menuItemID – The menu item ID.
  • enabled – True to enable the item, false to disable it (gray it out).
  • checked – True to select the item, false to deselect it.
CSInterface.updatePanelMenuItem(menuItemLabel, enabled, checked)

Updates a menu item in the extension window’s flyout menu, by setting the enabled and selection status.

Since 5.2.0

Arguments:
  • menuItemLabel – The menu item label.
  • enabled – True to enable the item, false to disable it (gray it out).
  • checked – True to select the item, false to deselect it.
Returns:

false when the host application does not support this functionality (HostCapabilities.EXTENDED_PANEL_MENU is false). Fails silently if menu label is invalid.