chrome/common/extensions/api/wm_desks_private.idl

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

// Private API for trusted extensions/apps to do desk related operations.
[platforms=("chromeos"),
 implemented_in="chrome/browser/chromeos/extensions/wm/wm_desks_private_api.h"]
namespace wmDesksPrivate {
  enum SavedDeskType {
    // Desk saved for regular desk template.
    kTemplate,

    // Desk saved for Save & Recall.
    kSaveAndRecall,

    // Unknown desk type.
    kUnknown
  };

  dictionary RemoveDeskOptions {
    // Define whether close all windows on the desk and combine them to the
    // active desk to the left.
    boolean combineDesks;

    // Define whether removed desk is retrievable.
    boolean? allowUndo;
  };

  dictionary Desk {
    // Unique ID for a desk.
    DOMString deskUuid;

    // User readable name of the desk.
    DOMString deskName;
  };

  dictionary SavedDesk {
    // Unique ID for a saved desk.
    DOMString savedDeskUuid;

    // User readable name of the saved desk.
    DOMString savedDeskName;

    // Saved desk type.
    SavedDeskType savedDeskType;
  };

  // Launch desk options
  dictionary LaunchOptions {
    // User readable name of the desk.
    DOMString? deskName;
  };

  // Window properties
  dictionary WindowProperties {
    // If window show up on all desks.
    boolean allDesks;
  };

  callback DeskIdCallback = void (DOMString deskId);
  callback VoidCallback = void ();
  callback GetDeskTemplateJsonCallback = void (DOMString templateJson);
  callback GetAllDesksCallback = void (Desk[] desks);
  callback GetSavedDesksCallback = void (SavedDesk[] saveDesks);
  callback SaveActiveDeskCallback = void (SavedDesk desk);
  callback GetDeskByIDCallback = void (Desk desk);

  interface Functions {
    // Returns all available previously-saved desks.
    static void getSavedDesks(
        GetSavedDesksCallback callback);

    // Launches a desk, if `templateUuid` is present in the options, launches a
    // desk template, otherwise launches an empty desk. If `deskName` is present
    // in the options, using provided name as desk name, otherwise launches with
    // auto generated name.
    static void launchDesk(
        LaunchOptions launchOptions,
        DeskIdCallback callback);

    // Gets the template associated with the templateUuid and returns its JSON
    // representation.  Returns an error if either the template could not be
    // found or the user profile is not valid.
    static void getDeskTemplateJson(
        DOMString templateUuid,
        GetDeskTemplateJsonCallback callback);

    // Removes a desk as specified in `deskId`. If `combineDesks` of
    // `RemoveDeskOptions` is present or set to true, remove the desk and
    // combine windows to the active desk to the left. If `allowUndo` is
    // present or set to true, prompt the user with a notification allowing for
    // the desk to be retrieved. Otherwise close all windows on the desk.
    static void removeDesk(
        DOMString deskId,
        optional RemoveDeskOptions removeDeskOptions,
        optional VoidCallback callback);

    // Returns all available desks.
    static void getAllDesks(GetAllDesksCallback callback);

    // Sets the window properties for window identified by the `windowId`.
    static void setWindowProperties(
        long windowId,
        WindowProperties windowProperties,
        optional VoidCallback callback);

    // Saves the current active desk to the library and remove it from the desk
    // bar.
    static void saveActiveDesk(
        SaveActiveDeskCallback callback);

    // Deletes the saved desk from the library.
    static void deleteSavedDesk(
        DOMString savedDeskUuid,
        optional VoidCallback callback);

    // Launches a saved desk from the library back to active desk.
    static void recallSavedDesk(
        DOMString savedDeskUuid,
        DeskIdCallback callback);

    // Retrieves the UUID of the current active desk.
    static void getActiveDesk(DeskIdCallback callback);

    // Switches to the target desk.
    static void switchDesk(
        DOMString deskUuid, VoidCallback callback);

    // Retrieves desk by the desk UUID.
    static void getDeskByID(
        DOMString deskUuid, GetDeskByIDCallback callback);
  };

  interface Events {
    // Fires when new desks is added.
    static void OnDeskAdded(DOMString deskId, boolean fromUndo);

    // Fires when desk removal is finalized.
    static void OnDeskRemoved(DOMString deskId);

    // Fires when desk activation changed.
    static void OnDeskSwitched(DOMString activated, DOMString deactivated);
    };

};