/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 * 
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.1 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 * 
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
 * License for the specific language governing rights and limitations
 * under the License.
 * 
 * The Original Code is Komodo code.
 * 
 * The Initial Developer of the Original Code is ActiveState Software Inc.
 * Portions created by ActiveState Software Inc are Copyright (C) 2000-2007
 * ActiveState Software Inc. All Rights Reserved.
 * 
 * Contributor(s):
 *   ActiveState Software Inc
 * 
 * Alternatively, the contents of this file may be used under the terms of
 * either the GNU General Public License Version 2 or later (the "GPL"), or
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL. *
 * ***** END LICENSE BLOCK ***** */

#include "nsISupports.idl"
#include "nsISimpleEnumerator.idl"
#include "nsITreeView.idl"

interface koIDocument;
interface koIShowsProgress;
interface koIProject;
interface koIPreferenceSet;
interface koICodeIntelService;
interface koINotificationProgress;
interface koIAsyncCallback;

[scriptable, uuid(8BFCA31B-3781-4F96-A7D2-60D6D6294889)]
interface koICodeIntelCatalogsTreeView : nsITreeView {
    void init(in koICodeIntelService ciSvc,
              in koIPreferenceSet prefSet,
              in wstring prefName);
    void save();

    // Note: Here "select" means the state of the "selected" column
    // rather than a UI row selection.
    void toggleSelection(in long row_idx);

    // Note: Here "select" means the UI-selection of rows.
    boolean areUISelectedRowsRemovable();

    koIShowsProgress addPaths(
        in unsigned long count,
        [array, size_is(count)] in wstring cix_paths);
    void post_add(
        in unsigned long count,
        [array, size_is(count)] in wstring added_cix_paths);

    koIShowsProgress removeUISelectedPaths();
    void post_remove(
        in unsigned long count,
        [array, size_is(count)] in wstring removed_cix_paths);

    readonly attribute wstring sortColId;
    readonly attribute wstring sortDirection;
};


[scriptable, uuid(C5B1B0AE-9374-488B-93E5-65A4A15322A8)]
interface koICodeIntelDefinition: nsISupports {
    readonly attribute wstring lang;       // e.g. "Python", "JavaScript"
    readonly attribute wstring path;       // file it's defined in
    readonly attribute wstring name;       // last piece of the ctdl_expr
    readonly attribute long line;          // line number in file
    readonly attribute wstring ilk;        // function, scope, class...
    readonly attribute wstring citdl;      // variable type
    readonly attribute wstring doc;        // Doc string
    readonly attribute wstring signature;  // If it's a function
    readonly attribute wstring attributes; // Any attributes, eg "local"
    readonly attribute wstring returns;    // Function return type
    readonly attribute long scopestart;    // Start of scope the variable is defined in
    readonly attribute long scopeend;      // End of scope the variable is defined in
    boolean equals(in koICodeIntelDefinition other);
    AString toString();
};

[scriptable, uuid(EC0B8148-8E12-43C2-8422-724E2478D884)]
interface koICodeIntelTrigger: nsISupports {
    // Must be kept in sync with the values in 'codeintel2/common.py'
    const long TRG_FORM_CPLN = 0;
    const long TRG_FORM_CALLTIP = 1;
    const long TRG_FORM_DEFN = 2;

    readonly attribute wstring lang;    // e.g. "Python", "CSS"
    readonly attribute long form;       // TRG_FORM_CPLN or TRG_FORM_CALLTIP
    readonly attribute wstring type;    // e.g. "object-members"
    readonly attribute long pos;
    readonly attribute boolean implicit;
    readonly attribute long length;     // num chars of the trigger token
    readonly attribute long extentLength; // num bytes forward trigger covers

    readonly attribute wstring name;

    // When true, after a completion event occurs, codeintel will call
    // "trg_from_pos" again.
    attribute boolean retriggerOnCompletion;

    boolean is_same(in koICodeIntelTrigger trg);
};

// JS-implemented component to provide scintilla autocomplete/calltip UI
// handling for a view.
[scriptable, uuid(26c394d7-16e2-4e2e-b56a-efdfac368d47)]
interface koICodeIntelCompletionUIHandler : nsISupports {
    /**
     * Called by a koICodeIntelCompletionLanguageService (see
     * src/languages/ko*Language.py) to provide data for these UIs.
     */

    /**
     * Set autocomplete info for the user to choose from
     * @param completions {wstring} sorted completion strings
     * @param types {string} completion types (see
     *        koScintillaAutoCompleteController.js for a list of default ones)
     * @param trg {koICodeIntelTrigger} the trigger that caused autocompletion
     */
    void setAutoCompleteInfo([array, size_is(count)] in wstring completions,
                             [array, size_is(count)] in string types,
                             in unsigned long count,
                             in koICodeIntelTrigger trg);
    /**
     * Set calltip info, as a quick reference
     * @param calltip {AString} the calltip to display
     * @param trg {koICodeIntelTrigger} the trigger that caused the calltip
     * @param explicit {boolean} Whether the calltip was manually triggered by
     *        the user
     */
    void setCallTipInfo(in AString calltip,
                        in koICodeIntelTrigger trg,
                        in boolean explicit);
    /**
     * Set definition information
     * @param defns {koICodeIntelDefinition} array of definitions
     * @param trg {koICodeIntelTrigger} the trigger that caused the definition
     *        request
     */
    void setDefinitionsInfo(in unsigned long count,
                            [array, size_is(count)] in koICodeIntelDefinition defns,
                            in koICodeIntelTrigger trg);
    /**
     * Set CodeIntel-related status message
     * @param msg {AString} The message to display
     * @param hightlight {boolean} Whether the message should be highlighted
     */
    void setStatusMessage(in AString msg, in boolean highlight);

    /**
     * If there is an active calltip, then update it as necessary (i.e.,
     * the highlighted arg may need to change, perhaps it should be
     * canceled).
     */
    void updateCallTip();

    /**
     * Synchronously find and trigger the preceding autocomplete or calltip
     * trigger point. This searching should stop and the beginning of the
     * current statement.
     */
    void triggerPrecedingCompletion(in AString path);

    /**
     * Called when the evaluation has completed.  This will be called even if
     * nothing was found.
     */
    void done();
};

[scriptable, function, uuid(2d047c58-2d63-444b-b5c1-dd64b13b55d2)]
interface koICodeIntelGetTriggerCallback: nsISupports {
    /**
     * @param trg The trigger
     */
    void onGetTrigger([optional] in koICodeIntelTrigger trg);
};

[scriptable, function, uuid(d2f1ceed-7e80-4a99-8d81-2c190bc2cc6e)]
interface koICodeIntelGetIndexCallback : nsISupports {
    void onGetIndex([optional] in long index);
};

/**
 * koICodeIntelErrorCallback: Used to pass a richer error message to the
 * client on failure.  Otherwise the server passes a binary indication
 * to the client (e.g. passing null rather than an object or list of
 * objects).
 */
[scriptable, function, uuid(d291a7f5-4e27-41c0-b3a7-0af622a8b602)]
interface koICodeIntelErrorCallback: nsISupports {
    void onError(in AString message);
};

/**
 * Callback for get_calltip_arg_range
 * @param start The start of the arg range; -1 if the text has exited the call
 *      region.
 * @param end The end of the arg range
 */
[scriptable, function, uuid(81925d5b-4c65-4982-a9bb-f516a7c8bd11)]
interface koICodeIntelGetCallTipRangeCallback : nsISupports {
    void onGetCalltipRange(in long start, in long end);
};

[scriptable, uuid(5e3fb74c-f420-4919-a3cf-0954b1606297)]
interface koICodeIntelBuffer: nsISupports {
    readonly attribute AString path;
    readonly attribute ACString lang;

    attribute koIProject project;  // The current Komodo project.

    readonly attribute AString cpln_fillup_chars;
    readonly attribute AString cpln_stop_chars;

    /**
     * Flags for async_eval_at_trig()
     */

    /**
     * If given, no errors/warnings/statuses will be reported
     */
    const unsigned long EVAL_SILENT = 1 << 0;
    /**
     * If given, this evaluation will not first stop existing queued evals
     */
    const unsigned long EVAL_QUEUE = 1 << 1;

    /**
     * Evaluate a trigger
     * @param trg The trigger to evaluate
     * @param ui_handler The handler to report evaluation results to
     * @param flags Some combination of EVAL_* constants above
     */
    void async_eval_at_trg(in koICodeIntelTrigger trg,
                           in koICodeIntelCompletionUIHandler ui_handler,
                           [optional] in unsigned long flags);

    /**
     * Return a trigger for a given position if that position is a _likely_
     * trigger point.
     * @param pos The position at which to check for a trigger point.
     * @param implicit True if this trigger is being implicitly checked (e.g.
     *      as a side-effect of typing).
     * @param callback The callback to invoke when the trigger has been found
     *      (or not found).
     * @param errorCallback The callback to pass a richer error message
     *      to the client.
     */
    void trg_from_pos(in long pos, in boolean implicit,
                      in koICodeIntelGetTriggerCallback callback,
                      [optional] in koICodeIntelErrorCallback errorCallback);

    /**
     * Look back from the given position for a trigger point within range.
     * @param pos The position at which to begin backtracking.
     * @param curr_pos The current position; used to determine the range in
     *      which to look for triggers.
     * @param callback The callback to invoke when the trigger has been found
     *      (or not found).
     * @param errorCallback The callback to pass a richer error message
     *      to the client.
     */
    void preceding_trg_from_pos(in long pos, in long curr_pos,
                                in koICodeIntelGetTriggerCallback callback,
                                [optional] in koICodeIntelErrorCallback errorCallback);

    /**
     * Get a trigger for a given position which will provide a list of codeintel
     * definitions for thee citdl expression at the given position
     * @param pos The position to look up definitions for
     * @param callback The callback to invoke once the trigger has been
     *      constructed (or been determined to not exist)
     * @param errorCallback The callback to pass a richer error message
     *      to the client.
     */
    void defn_trg_from_pos(in long pos,
                           in koICodeIntelGetTriggerCallback callback,
                           [optional] in koICodeIntelErrorCallback errorCallback);

    /**
     * Get the range in the given calltip for the argument; i.e. what argument
     * is being entered.
     * @param trg_pos The trigger position.
     * @param calltip The full calltip text.
     * @param curr_pos The current position in the buffer
     * @param callback The callback to invoke once the calltip has been
     *      constructed (or been determined to not exist)
     * @param errorCallback The callback to pass a richer error message
     *      to the client.
     */
    void get_calltip_arg_range(in long trg_pos,
                               in AString calltip,
                               in long cur_pos,
                               in koICodeIntelGetCallTipRangeCallback callback,
                               [optional] in koICodeIntelErrorCallback errorCallback);

    /**
     * Return a styled HTML snippet for the current buffer, for debugging
     * purposes.
     * @param includeStyling Whether the CSS/JS/informational-HTML should be
     *      included
     * @param includeHTML Whether the HTML output should be wrapped into a
     *      complete HTML document
     * @param title The HTML document title to use if includeHTML is true
     * @param doTrg Whether trigger hanlding should be done; this implies
     *      doEval
     * @param doEval Whether completion evaluation should be done
     *
     * @deprecated Since Komodo 8.5.3 - Prefer to_html_async instead.  This will
     *      now pump events, which can be unsafe.
     */
    [deprecated]
    AString to_html([optional] in boolean includeStyling,
                    [optional] in boolean includeHTML,
                    [optional] in AString title,
                    [optional] in boolean doTrg,
                    [optional] in boolean doEval);
    /**
     * Flags for to_html_async
     */
    /**
     * Whether the CSS/JS/informational-HTML should be included
     */
    const unsigned long TO_HTML_INCLUDE_STYLING = 1 << 0;
    /**
     * Whether the HTML output should be wrapped into a complete HTML document
     */
    const unsigned long TO_HTML_INCLUDE_HTML    = 1 << 1;
    /**
     * Whether trigger hanlding should be done; this implies doEval
     */
    const unsigned long TO_HTML_DO_TRG  = 1 << 2;
    /**
     * Whether completion evaluation should be done
     */
    const unsigned long TO_HTML_DO_EVAL = 1 << 3;

    void to_html_async(in koIAsyncCallback callback,
                       [optional] in unsigned long flags,
                       [optional] in AString title);
};

[scriptable, function, uuid(4788a643-7f1b-4a49-9919-60076dd70869)]
interface koICodeIntelServiceGetBufCallback: nsISupports {
    void callback(in koICodeIntelBuffer buffer);
};

[scriptable, uuid(4bd3e48f-6e37-4334-994d-7787f526d700)]
interface koICodeIntelService: nsISupports {

    /**
     * Is the codeintel system enabled for this Komodo run?
     */
    readonly attribute boolean enabled;
    /**
     * Has the codeintel backend being started yet? This can be delayed if,
     * e.g. upgrading of the codeintel db is being done. The backend may go back
     * to being inactive after activating.
     */
    readonly attribute boolean isBackEndActive;

    /**
     * Add a callback for activation state changes on the codeintel service.
     * The callback will be invoked after the codeintel service database has
     * been activated, as well as when it has been disabled.  The result of the
     * callback will be:
     *      RESULT_SUCCESSFUL:  Codeintel has successfully activated.
     *      RESULT_STOPPED:     There was a recoverable error starting
     *                          codeintel.  Try again with resetBrokenDB set.
     *      RESULT_ERROR:       There was a fatal error string codeintel.
     *                          Retrying is unlikely to be useful.
     * The data in the callback may be an instance of koIErrorInfo to provide
     * more information about issues with starting codeintel.
     */
    void addActivateCallback(in koIAsyncCallback callback);
    /**
     * Remove a previously added observer.
     */
    void removeActivateCallback(in koIAsyncCallback callback);

    /**
     * Activate the codeintel service.
     *
     * @param resetBrokenDB If true, will automatically reset the database if
     *      it appears to be broken.
     */
    void activate([optional] in boolean resetBrokenDB);

    /**
     * Deactivate the codeintel service.
     */
    void deactivate();

    /**
     * Request a scan of the given koIDocument.
     *
     * @param useFileMtime {boolean} indicates if the document file's
     *      mtime should be used for the scan request. If true, this
     *      typically means that the file won't be re-scanned if the
     *      database has already scanned the file with that mtime. To
     *      force a scan of *unsaved* changes, use false.
     */
    void scan_document(in koIDocument document, in long linesAdded,
                       in boolean useFileMtime);

    /**
     * Remove a codeintel buffer given a document.
     */
    void remove_buf_from_koIDocument(in koIDocument doc);
    
    /**
     * Get a codeintel buffer given a document.
     */
    koICodeIntelBuffer buf_from_koIDocument(in koIDocument doc);

    /**
     * Check whether a given language supports code completion
     */
    boolean is_cpln_lang(in wstring lang);
    /**
     * Get the list of languages which support code completion
     */
    void get_cpln_langs(out unsigned long count,
                        [array, size_is(count)] out wstring langs);
    /**
     * Check whether a given language is a citadel language
     */
    boolean is_citadel_lang(in wstring lang);
    /**
     * Get the list of all citadel languages
     */
    void get_citadel_langs(out unsigned long count,
                           [array, size_is(count)] out wstring langs);
    /**
     * Check whether a given language is a XML-based language
     */
    boolean is_xml_lang(in wstring lang);
    /**
     * Get the list of all XML-based languages
     */
    void get_xml_langs(out unsigned long count,
                       [array, size_is(count)] out wstring langs);
};

[scriptable, uuid(aca8a5c6-7ae2-4646-8706-e1e7790ee416)]
interface koICodeIntelDBPreloader : nsISupports {
    /**
     * A notification to indicate the preloading progress
     */
    readonly attribute koINotificationProgress notification;

    /**
     * Start the preloading.  Raises NS_ERROR_IN_PROGRESS if preloading is
     * already in progress.
     */
    void start();

    /**
     * Attempt to stop any currently running preloading.  Has no effect if
     * preloading is not currently in progress.
     */
    void cancel();
};
