extensions/common/api/clipboard.webidl

// Copyright 2025 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// Supported image types.
enum ImageType {
  "png",
  "jpeg"
};

enum DataItemType {
  "textPlain",
  "textHtml"
};

// Additional data item to be added along with the |image_data| to describe
// the |image_data|.
dictionary AdditionalDataItem {
  // Type of the additional data item.
  required DataItemType type;

  // Content of the additional data item. Either the plain text string if
  // |type| is "textPlain" or markup string if |type| is "textHtml". The
  // data can not exceed 2MB.
  required DOMString data;
};

callback OnClipboardDataChangedListener = undefined();

interface OnClipboardDataChangedEvent : ExtensionEvent {
  static undefined addListener(OnClipboardDataChangedListener listener);
  static undefined removeListener(OnClipboardDataChangedListener listener);
  static boolean hasListener(OnClipboardDataChangedListener listener);
};

// The <code>chrome.clipboard</code> API is provided to allow users to
// access data of the clipboard. This is a temporary solution for
// chromeos platform apps until open-web alternative is available. It will be
// deprecated once open-web solution is available, which could be in 2017 Q4.
[platforms=("chromeos"),
 implemented_in="extensions/browser/api/clipboard/clipboard_api.h"]
interface Clipboard {
  // Sets image data to clipboard.
  //
  // |imageData|: The encoded image data.
  // |type|: The type of image being passed.
  // |additionalItems|: Additional data items for describing image data. The
  // callback is called with <code>chrome.runtime.lastError</code> set to error
  // code if there is an error. Requires clipboard and clipboardWrite
  // permissions.
  static Promise<undefined> setImageData(
      ArrayBuffer imageData,
      ImageType type,
      optional sequence<AdditionalDataItem> additionalItems);

  // Fired when clipboard data changes.
  // Requires clipboard and clipboardRead permissions for adding listener to
  // chrome.clipboard.onClipboardDataChanged event.
  // After this event fires, the clipboard data is available by calling
  // document.execCommand('paste').
  static attribute OnClipboardDataChangedEvent onClipboardDataChanged;
};

partial interface Browser {
  static attribute Clipboard clipboard;
};