Source: editor.js

goog.provide('sync.api.Editor');
goog.provide('sync.api.Editor.LinkOpenedEvent');
goog.provide('sync.api.Editor.WebappMessageReceived');

goog.require('goog.events.EventTarget');
goog.require('sync.api.WebappMessage');
goog.require('sync.actions.AttributeEditingActionsProvider');

/**
 * A visual editor for an XML document.
 *
 * @constructor
 */
sync.api.Editor = function() {
  goog.events.EventTarget.call(this);
};
goog.inherits(sync.api.Editor, goog.events.EventTarget);


/**
 * Returns the actions manager for the current editor.
 *
 * @return {sync.api.ActionsManager} the actions manager of this editor.
 */
sync.api.Editor.prototype.getActionsManager = function() {
  return null;
};


/**
 * Returns the selection method of the editor.
 *
 * @return {sync.api.SelectionModel} The selection model.
 */
sync.api.Editor.prototype.getSelectionManager = function() {
  return null;
};

/**
 * A callback invoked when the asynchronous request for the XML content finishes.
 * If the operation is successful, the first
 * parameter is <code>null</code> and the second one is a string that represents
 * the content. If case of an error, the first parameter is an object describing
 * the error.
 *
 * @callback sync.api.Editor~onXmlContentReceived
 *
 * @param {object} error The error object, or null if the request was successful.
 * @param {string} content The serialized XML content.
 */

/**
 * Retrieves the content of the XML document asynchronously.
 *
 * @param {sync.api.Editor~onXmlContentReceived} callback The callback that will be called
 * once the XML content is retrieved.
 */
sync.api.Editor.prototype.getXmlContent = function(callback) {
};


/**
 * <p>Registers an enhancer for a type of form controls.
 *
 * <p>This registration should be performed before the editor is loaded, so that the enhancer can
 * be used for the initial rendering of the document.
 *
 * @param {string} name The type of the form-control, which is the fully qualified name of the
 * Java WebappFormControlRenderer class.
 * @param {function(HTMLElement, sync.api.Editor)} enhancer The constructor for an instance of {@link sync.formctrls.Enhancer}
 * that will be used to enhance form controls rendered by the specified Java renderer.
 *
 */
sync.api.Editor.prototype.registerEnhancer = function(name, enhancer) {
};

/**
 * <p>Notifies the server that the client is still alive.
 *
 * <p>When it receives the keep-alive message, the server makes sure to:
 * <ul>
 *  <li>extend the document lifetime in memory
 *  <li>extend the license for the current user
 *  <li>keep the edited documents locked (if the URLStreamHandler supports locking).
 * <ul>
 *
 * @param {number} interval The interval between two keepalive requests (in seconds).
 */
sync.api.Editor.prototype.enableKeepalives = function(interval) {
};


/**
 * Sets the editor status as modified or not.
 *
 * If the editor is modified, when the user leaves the page, we
 * warn them that there are unsaved changes.
 *
 * @param {boolean} dirty Whether the editor should be marked as dirty or not.
 */
sync.api.Editor.prototype.setDirty = function(dirty) {
};

/**
 * @return {boolean} true if the document is read-only.
 */
sync.api.Editor.prototype.isDirty = function() {
};

/**
 * Loads an editor with the given options.
 *
 * Should not be called if the editor was not already loaded
 *
 * @param {sync.api.Workspace.LoadingOptions} options The options used to open the editor.
 */
sync.api.Editor.prototype.load = function(options) {
};

/**
 * Register a provider that is used to determine a custom interface used to edit an attribute.
 *
 * @param {sync.actions.AttributeEditingActionsProvider} attributeActionsProvider The actions provider.
 */
sync.api.Editor.prototype.registerAttributeActionsProvider = function(attributeActionsProvider) {
};

/**
 * Event types generated by this editor.
 *
 * @enum {string}
 */
sync.api.Editor.EventTypes = {
  /**
   * Generated when a link is about to be opened.
   */
  LINK_OPENED: 'link_openend',
  /**
   * Generated when an WebappMessage whose type is not handled by the webapp itself
   * was reported on the server-side.
   */
  CUSTOM_MESSAGE_RECEIVED: 'custom_message',
  /**
   * Generated when some editor-related actions were loaded.
   */
  ACTIONS_LOADED: 'actions_loaded',
  /**
   * Generated the editor changes its dirty status.
   */
  DIRTY_STATUS_CHANGED: 'dirty_status_changed'
};


/**
 * Link opened event.
 *
 * <hr/>
 * <p>
 * Example of listening for this event:
 * </p>
 * <pre>
 * goog.events.listen(editor, sync.api.Editor.EventTypes.LINK_OPENED, function(e) {
 *   // e is of type sync.api.Editor.LinkOpenedEvent
 * });
 * </pre>
 *
 * @param {string} url The URL to be opened
 * @param {boolean} external Whether the link should be opened in an
 * external application.
 * @param {object=} params The parameters to pass to the new editor.
 *
 * @constructor
 */
sync.api.Editor.LinkOpenedEvent = function(url, external, params) {
  this.type = sync.api.Editor.EventTypes.LINK_OPENED;
  /**
   * The URL that will be opened.
   *
   * @type {string}
   */
  this.url = url;
  /**
   * Flag indicating whether the link is an external one, e.g. to a web page.
   *
   * @type {boolean}
   */
  this.external = external;
  /**
   * Key-value mapping that contains parameters that will be passed to the new editor in case it is
   * opened in the oXygen XML WebApp.
   *
   * @type {Object.<string,string>}
   */
  this.params = params || {};
};


/**
 * Event triggered when a webapp message is received from the server-side code.
 *
 * @param {Object} webappMessageJSON The webapp message sent by the server-side code, as JSON.
 * @param {string} context The context in which the message is received.
 *
 * @constructor
 */
sync.api.Editor.WebappMessageReceived = function(webappMessageJSON, context) {
  this.type = sync.api.Editor.EventTypes.CUSTOM_MESSAGE_RECEIVED;
  this.message = new sync.api.WebappMessage(webappMessageJSON);
  this.context = context;
};


/**
 * The constants representing the context in which a webapp message is received.
 *
 * @enum {string}
 */
sync.api.Editor.WebappMessageReceived.Context = {
  /**
   * During the loading of the document.
   */
  LOAD: 'load',
  /**
   * During the save operation.
   */
  SAVE: 'save',
  /**
   * During the save as operation.
   */
  SAVE_AS: 'save',
  /**
   * While the document is edited.
   */
  EDITING: 'editing',
  /**
   * During a image request.
   */
  IMAGE: 'image'
};


/**
 * @typedef {Object} sync.api.Editor.ActionsLoadedEvent.ActionDescriptor The action descriptor.
 * @property {boolean} compatible Whether the action is compatible with webapp. If not, it will not be used in the UI.
 * @property {string=} icon16 The URL for a 16x16 icon to be used for the action.
 * @property {string=} icon20 The URL for a 24x24 icon to be used for the action. Yes, 24x24, it's called icon20 for
 * backwards compatibility reasons.
 * @property {string} id The unique ID of the action.
 * @property {string=} name The display name of the action.
 * @property {string=} tooltip The tooltip description of the action.
 * @property {string=} shortcut The shortcut of the action. Can use platform-generic modifiers (e.g. M1) similar with
 * how they work in SA.
 */

/**
 * @typedef {Object} sync.api.Editor.ActionsLoadedEvent.ActionEntry The descriptor for an action entry on the toolbar or in the context menu.
 * @property {string} id The ID of the action to render on the toolbar.
 * @property {string} type Equal to "action".
 */

/**
 * @typedef {Object} sync.api.Editor.ActionsLoadedEvent.Sep A separator.
 * @property {string} type Equal to "sep".
 */

/**
 * @typedef {Object} sync.api.Editor.ActionsLoadedEvent.ActionsListDescriptor The descriptor for a toolbar, a drop-down menu on the toolbar, or context sub-menu.
 * @property {string=} icon16 The URL for a 16x16 icon to be used to render the actions list.
 * @property {string=} icon20 The URL for a 24x24 icon to be used to render the actions list. Yes, 24x24, it's called icon20 for
 * backwards compatibility reasons.
 * @property {HTMLElement=} iconDom A DOM element that will be used to render the actions list.
 * @property {string=} name The display name of the toolbar.
 * @property {string} type Equal to "list".
 * @property {Array<sync.api.Editor.ActionsLoadedEvent.ActionsListDescriptor|sync.api.Editor.ActionsLoadedEvent.ActionEntry|sync.api.Editor.ActionsLoadedEvent.Sep>} children
 * the list entries.
 */

/**
 * @typedef {Object} sync.api.Editor.ActionsLoadedEvent.ContextMenuEntry The context menu entry descriptor.
 * @property {string=} icon The URL for a 16x16 icon to be used for the toolbar.
 * @property {string=} name The display name of the toolbar.
 * @property {string} type Equal to "list".
 * @property {Array<sync.api.Editor.ActionsLoadedEvent.ActionsListDescriptor|sync.api.Editor.ActionsLoadedEvent.ActionEntry|sync.api.Editor.ActionsLoadedEvent.Sep>} children
 * the list entries.
 */

/**
 * @typedef {Object} sync.api.Editor.ActionsLoadedEvent.ActionsConfiguration The object used to open the editor.
 * @property {Array<sync.api.Editor.ActionsLoadedEvent.ActionDescriptor>} actions An array of actions descriptors.
 * @property {Array<sync.api.Editor.ActionsLoadedEvent.ActionsListDescriptor>} toolbars An array of descriptors for
 * actions lists that will be rendered as toolbars.
 * @property {Array<sync.api.Editor.ActionsLoadedEvent.ContextMenuEntry>} contextualItems An array of descriptors for entries in
 * the context menu.
 */


/**
 * <p>Configuration of the actions that are going to be enabled for the current editor
 * was loaded. This configuration may specify some of the:</p>
 * <ul>
 * <li>the action together with their shortcuts
 * <li>the configuration of one of the toolbars
 * <li>the configuration of the context menu
 * </ul>
 *
 * <p>This event is triggered before the action are used, so changes to the configuration will
 * take effect in the UI.
 *
 * <p>The toolbar and contextmenu configurations contain only action ids. In order to change the
 * actual actions or to add more actions one can use the {@link sync.api.ActionsManager}.
 *
 * <hr/>
 * <p>
 * Example of listening for this event:
 * </p>
 * <pre>
 * goog.events.listen(editor, sync.api.Editor.EventTypes.ACTIONS_LOADED, function(e) {
 *   // e is of type sync.api.Editor.ActionsLoadedEvent
 * });
 * </pre>
 *
 * @param {sync.api.Editor.ActionsConfiguration} actionsConfiguration A JSON object that represents the actions configuration.
 *
 * @constructor
 */
sync.api.Editor.ActionsLoadedEvent = function(actionsConfiguration) {
  this.type = sync.api.Editor.EventTypes.ACTIONS_LOADED;
  this.actionsConfiguration = actionsConfiguration;
};

/**
 * This event should be triggered when the dirty status of the editor changes.
 *
 * <hr/>
 * <p>
 * Example of listening for this event:
 * </p>
 * <pre>
 * goog.events.listen(editor, sync.api.Editor.EventTypes.DIRTY_STATUS_CHANGED, function(e) {
 *   // e is of type sync.api.Editor.DirtyStatusChangedEvent
 * });
 * </pre>
 *
 * @param {boolean} isDirty If the editor has unsaved changes, isDirty should be true.
 * @constructor
 */
sync.api.Editor.DirtyStatusChangedEvent = function(isDirty) {
  this.type = sync.api.Editor.EventTypes.DIRTY_STATUS_CHANGED;
  this.isDirty = isDirty;
};