Adobe CEP8 API

Class: CSInterface

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

new CSInterface()

Source:
Returns:

A new CSInterface object

Members

<static> THEME_COLOR_CHANGED_EVENT

Users 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:

Source:
Example
// 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.
}

hostEnvironment

The host environment data object.

Source:

Methods

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.

Parameters:
Name Type Description
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.
Source:

closeExtension()

Closes this extension.

Source:

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.

Parameters:
Name Type Description
event

A CSEvent object.
Source:

dumpInstallationInfo()

Writes installation information to a file.

Source:
Returns:

The file path.

evalScript(script, callback)

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

Parameters:
Name Type Description
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.
Source:

getApplicationID()

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

Source:
Returns:

The unique ID string.

getCurrentApiVersion()

Retrieves current API version.

Since:
  • 4.2.0
Source:
Returns:

ApiVersion object.

getExtensionID()

Retrieves extension ID.

Since:
  • 4.2.0
Source:
Returns:

extension ID.

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.

Parameters:
Name Type Description
extensionIds

Optional, an array of unique identifiers for extensions of interest.
If omitted, retrieves data for all extensions.
Source:
Returns:

Zero or more #Extension objects.

getHostCapabilities()

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

Source:
Returns:

A #HostCapabilities object.

getHostEnvironment()

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

Source:
Returns:

A #HostEnvironment object.

getNetworkPreferences()

Retrieves network-related preferences.

Source:
Returns:

A JavaScript object containing network preferences.

getOSInformation()

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

Source:
Returns:

A string containing the OS version, or "unknown Operation System".
If user customizes the User Agent by setting CEF command parameter "--user-agent", only
"Mac OS X" or "Windows" will be returned.

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:
  • 4.2.0
Source:
Returns:

One of the following float number.


  • -1.0 when error occurs

  • 1.0 means normal screen

  • >1.0 means HiDPI screen

getSystemPath(pathType)

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

Parameters:
Name Type Description
pathType

The path-type constant defined in #SystemPath ,
Source:
Returns:

The platform-specific system path string.

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
Source:
Returns:

The window title.

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 key.value="localized string", 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:

Source:
Returns:

An object containing the resource bundle information.

isWindowVisible()

Get the visibility status of an extension window.

Since:
  • 6.0.0
Source:
Returns:

true if the extension window is visible; false if the extension window is hidden.

openURLInDefaultBrowser(url)

Opens a page in the default system browser.

Parameters:
Name Type Description
url

The URL of the page/file to open, or the email address.
Must use HTTP/HTTPS/file/mailto protocol. For example:
"http://www.adobe.com"
"https://github.com"
"file:///C:/log.txt"
"mailto:test@adobe.com"
Since:
  • 4.2.0
Source:
Returns:

One of these error codes:


  • NO_ERROR - 0

  • ERR_UNKNOWN - 1

  • ERR_INVALID_PARAMS - 2

  • ERR_INVALID_URL - 201

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.

Parameters:
Name Type Description
callback function

the callback function
Since:
  • 6.1.0
Source:

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.

Parameters:
Name Type Description
keyEventsInterest JSON_String

A JSON string describing those key events you are interested in. A null object or an empty string will lead to removing the interest
Since:
  • 6.1.0
Source:
Example
An example JSON string:

[
    {
        "keyCode": 48
    },
    {
        "keyCode": 123,
        "ctrlKey": true
    },
    {
        "keyCode": 123,
        "ctrlKey": true,
        "metaKey": true
    }
]

removeEventListener(type, listener, obj)

Removes a registered event listener.

Parameters:
Name Type Description
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.
Source:

requestOpenExtension(extensionId, startupParams)

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

Parameters:
Name Type Description
extensionId

The extension's unique identifier.
startupParams

Not currently used, pass "".
Source:
Example
To launch the extension "help" with ID "HLP" from this extension, call:
<code>requestOpenExtension("HLP", ""); </code>

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.
Parameters:
Name Type Description
width number

The new width
height number

The new height
Since:
  • 6.0.0
Source:

setContextMenu(menu, callback)

Set context menu by XML string.

Parameters:
Name Type Description
menu string

A XML string which describes menu structure.
callback function

The callback function which is called when a menu item is clicked. The only parameter is the returned ID of clicked menu item.
Since:
  • 5.2.0
    There are a number of conventions used to communicate what type of menu item to create and how it should be handled.
    • an item without menu ID or menu name is disabled and is not shown.
    • if the item label is "---" (three hyphens) then it is treated as a separator. The menu ID in this case will always be NULL.
    • checkable attribute takes precedence over Checked attribute.
    • a PNG icon. For optimal display results please supply a 16 x 16px icon as larger dimensions will increase the size of the menu item.
    • the items with icons and checkable items cannot coexist on the same menu level. The former take precedences over the latter.
    The Chrome extension contextMenus API was taken as a reference.
Source:
Example
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>'

setContextMenuByJSON(menu, callback)

Set context menu by JSON string.

Parameters:
Name Type Description
menu

A JSON string which describes menu structure.
callback function

The callback function which is called when a menu item is clicked. The only parameter is the returned ID of clicked menu item.
Since:
  • 6.0.0
    There are a number of conventions used to communicate what type of menu item to create and how it should be handled.
    • an item without menu ID or menu name is disabled and is not shown.
    • if the item label is "---" (three hyphens) then it is treated as a separator. The menu ID in this case will always be NULL.
    • checkable attribute takes precedence over Checked attribute.
    • a PNG icon. For optimal display results please supply a 16 x 16px icon as larger dimensions will increase the size of the menu item.
    • the items with icons and checkable items cannot coexist on the same menu level. The former take precedences over the latter.
    The Chrome extension contextMenus API was taken as a reference.
Source:
Example
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
         }
     ]
 }

setPanelFlyoutMenu(menu)

Set panel flyout menu by an XML.

Parameters:
Name Type Description
menu string

An XML string which describes menu structure.
Since:
  • 5.2.0
    Register a callback function for "com.adobe.csxs.events.flyoutMenuClicked" to get notified when a menu item is clicked. The "data" attribute of event is an object which contains "menuId" and "menuName" attributes. Register callback functions for "com.adobe.csxs.events.flyoutMenuOpened" and "com.adobe.csxs.events.flyoutMenuClosed" respectively to get notified when flyout menu is opened or closed.
Source:
Example
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>'

setScaleFactorChangedHandler(handler)

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

Parameters:
Name Type Description
handler

The function to be called when scale factor is changed.
Since:
  • 4.2.0
Source:

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.

Parameters:
Name Type Description
title string

The window title.
Since:
  • 6.1.0
Source:

updateContextMenuItem(menuItemID, enabled, checked)

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

Parameters:
Name Type Description
menuItemID string

The menu item ID.
enabled boolean

True to enable the item, false to disable it (gray it out).
checked boolean

True to select the item, false to deselect it.
Since:
  • 5.2.0
Source:

updatePanelMenuItem(menuItemLabel, enabled, checked)

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

Parameters:
Name Type Description
menuItemLabel string

The menu item label.
enabled boolean

True to enable the item, false to disable it (gray it out).
checked boolean

True to select the item, false to deselect it.
Since:
  • 5.2.0
Source:
See:
  • HostCapabilities.EXTENDED_PANEL_MENU
Returns:

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