/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

/**
 * Stores composition clauses information and caret information for synthesizing
 * composition string.
 */

[scriptable, uuid(9a7d7851-8c0a-4061-9edc-60d6693f86c9)]
interface nsICompositionStringSynthesizer : nsISupports
{
  /**
   * Set composition string or committed string.
   */
  void setString(in AString aString);

  // NOTE: These values must be same to NS_TEXTRANGE_* in TextEvents.h
  const unsigned long ATTR_RAWINPUT              = 0x02;
  const unsigned long ATTR_SELECTEDRAWTEXT       = 0x03;
  const unsigned long ATTR_CONVERTEDTEXT         = 0x04;
  const unsigned long ATTR_SELECTEDCONVERTEDTEXT = 0x05;

  /**
   * Append a clause.
   *
   * TODO: Should be able to specify custom clause style.
   */
  void appendClause(in unsigned long aLength,
                    in unsigned long aAttribute);

  /**
   * Set caret information.
   */
  void setCaret(in unsigned long aOffset,
                in unsigned long aLength);

  /**
   * Synthesize composition string with given information by dispatching
   * a proper event.
   *
   * If clauses have never been set, this dispatches a commit event.
   * If clauses are not filled all over the composition string, this throw an
   * error.
   *
   * After dispatching event, this clears all the information about the
   * composition string. So, you can reuse this instance.
   */
  bool dispatchEvent();
};