chrome/common/extensions/api/side_panel.idl

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

// Use the `chrome.sidePanel` API to host content in the browser's side panel
// alongside the main content of a webpage.
namespace sidePanel {
  dictionary SidePanel {
    // Developer specified path for side panel display.
    DOMString default_path;
  };

  dictionary ManifestKeys {
    SidePanel side_panel;
  };

  // The options used when setting a side panel. Omitted properties are
  // unchanged.
  dictionary PanelOptions {
    // If specified, the side panel options will only apply to the tab with
    // this id. If omitted, these options set the default behavior (used for any
    // tab that doesn't have specific settings). Note: if the same path is set
    // for this tabId and the default tabId, then the panel for this tabId will
    // be a different instance than the panel for the default tabId.
    long? tabId;
    // The path to the side panel HTML file to use. This must be a local
    // resource within the extension package.
    DOMString? path;
    // Whether the side panel should be enabled. This is optional. The default
    // value is true.
    boolean? enabled;
  };

  // A dictionary containing the extension's options for how its side panel
  // behaves.
  dictionary PanelBehavior {
    // Whether clicking the extension's icon will toggle showing the extension's
    // entry in the side panel. Defaults to false.
    boolean? openPanelOnActionClick;
  };

  dictionary GetPanelOptions {
    // If specified, the side panel options for the given tab will be returned.
    // Otherwise, returns the default side panel options (used for any tab that
    // doesn't have specific settings).
    long? tabId;
  };

  // Options for opening the side panel.
  // At least one of `tabId` or `windowId` must be specified.
  dictionary OpenOptions {
    // The window in which to open the side panel. This is only applicable if
    // the extension has a global (non-tab-specific) side panel or
    // <code>tabId</code> is also specified. This will override any
    // currently-active global side panel the user has open in the given
    // window. At least one of this or <code>tabId</code> must be provided.
    long? windowId;

    // The tab in which to open the side panel. If the corresponding tab has
    // a tab-specific side panel, the panel will only be open for that tab.
    // If there is not a tab-specific panel, the global panel will be open in
    // the specified tab and any other tabs without a currently-open tab-
    // specific panel. This will override any currently-active side panel
    // (global or tab-specific) in the corresponding tab. At least one of this
    // or <code>windowId</code> must be provided.
    long? tabId;
  };

  callback VoidCallback = void();
  callback PanelOptionsCallback = void(PanelOptions options);
  callback PanelBehaviorCallback = void(PanelBehavior behavior);

  interface Functions {
    // Configures the side panel.
    // |options|: The configuration options to apply to the panel.
    // |callback|: Invoked when the options have been set.
    static void setOptions(
        PanelOptions options,
        optional VoidCallback callback);

    // Returns the active panel configuration.
    // |options|: Specifies the context to return the configuration for.
    // |callback|: Called with the active panel configuration.
    static void getOptions(
        GetPanelOptions options,
        PanelOptionsCallback callback);

    // Configures the extension's side panel behavior. This is an upsert
    // operation.
    // |behavior|: The new behavior to be set.
    // |callback|: Called when the new behavior has been set.
    static void setPanelBehavior(
        PanelBehavior behavior,
        optional VoidCallback callback);

    // Returns the extension's current side panel behavior.
    // |callback|: Called with the extension's side panel behavior.
    static void getPanelBehavior(
        PanelBehaviorCallback callback);

    // Opens the side panel for the extension.
    // This may only be called in response to a user action.
    // |options|: Specifies the context in which to open the side panel.
    // |callback|: Called when the side panel has been opened.
    static void open(
        OpenOptions options,
        VoidCallback callback);
  };
};