Fix Doxygen warnings due to documenting overloaded functions together.

[wxWidgets.git] / src / stc / stc.interface.h.in

/////////////////////////////////////////////////////////////////////////////
// Name:        stc/stc.h
// Purpose:     interface of wxStyledTextCtrl
// Author:      wxWidgets team
// Licence:     wxWindows licence
/////////////////////////////////////////////////////////////////////////////

/*
    IMPORTANT: This file is generated by src/stc/gen_iface.py from
               src/stc/stc.interface.h.in.  Do not edit the file in 
               interface/wx/stc or your changes will be lost.
*/


// STC constants {{{

%(VALUES)s

//}}}

// Commands that can be bound to keystrokes {{{

%(CMDS)s

//}}}




/**
    @class wxStyledTextCtrl

    A wxWidgets implementation of the Scintilla source code editing component.

    As well as features found in standard text editing components, Scintilla
    includes features especially useful when editing and debugging source code.
    These include support for syntax styling, error indicators, code completion
    and call tips.

    The selection margin can contain markers like those used in debuggers to indicate
    breakpoints and the current line. Styling choices are more open than with many
    editors, allowing the use of proportional fonts, bold and italics, multiple
    foreground and background colours and multiple fonts.

    wxStyledTextCtrl is a 1 to 1 mapping of "raw" scintilla interface, whose
    documentation can be found in the Scintilla website (http://www.scintilla.org/).

    @beginEventEmissionTable{wxStyledTextEvent}
    @event{EVT_STC_CHANGE(id, fn)}
        TOWRITE
    @event{EVT_STC_STYLENEEDED(id, fn)}
        TOWRITE
    @event{EVT_STC_CHARADDED(id, fn)}
        TOWRITE
    @event{EVT_STC_SAVEPOINTREACHED(id, fn)}
        TOWRITE
    @event{EVT_STC_SAVEPOINTLEFT(id, fn)}
        TOWRITE
    @event{EVT_STC_ROMODIFYATTEMPT(id, fn)}
        TOWRITE
    @event{EVT_STC_KEY(id, fn)}
        TOWRITE
    @event{EVT_STC_DOUBLECLICK(id, fn)}
        TOWRITE
    @event{EVT_STC_UPDATEUI(id, fn)}
        TOWRITE
    @event{EVT_STC_MODIFIED(id, fn)}
        TOWRITE
    @event{EVT_STC_MACRORECORD(id, fn)}
        TOWRITE
    @event{EVT_STC_MARGINCLICK(id, fn)}
        TOWRITE
    @event{EVT_STC_NEEDSHOWN(id, fn)}
        TOWRITE
    @event{EVT_STC_PAINTED(id, fn)}
        TOWRITE
    @event{EVT_STC_USERLISTSELECTION(id, fn)}
        TOWRITE
    @event{EVT_STC_URIDROPPED(id, fn)}
        TOWRITE
    @event{EVT_STC_DWELLSTART(id, fn)}
        TOWRITE
    @event{EVT_STC_DWELLEND(id, fn)}
        TOWRITE
    @event{EVT_STC_START_DRAG(id, fn)}
        TOWRITE
    @event{EVT_STC_DRAG_OVER(id, fn)}
        TOWRITE
    @event{EVT_STC_DO_DROP(id, fn)}
        TOWRITE
    @event{EVT_STC_ZOOM(id, fn)}
        TOWRITE
    @event{EVT_STC_HOTSPOT_CLICK(id, fn)}
        TOWRITE
    @event{EVT_STC_HOTSPOT_DCLICK(id, fn)}
        TOWRITE
    @event{EVT_STC_CALLTIP_CLICK(id, fn)}
        TOWRITE
    @event{EVT_STC_AUTOCOMP_SELECTION(id, fn)}
        TOWRITE
    @event{EVT_STC_INDICATOR_CLICK(id, fn)}
        TOWRITE
    @event{EVT_STC_INDICATOR_RELEASE(id, fn)}
        TOWRITE
    @event{EVT_STC_AUTOCOMP_CANCELLED(id, fn)}
        TOWRITE
    @event{EVT_STC_AUTOCOMP_CHAR_DELETED(id, fn)}
        TOWRITE
    @event{EVT_STC_HOTSPOT_RELEASE_CLICK(id, fn)}
        TOWRITE
    @endEventTable

    @library{wxbase}
    @category{stc}

    @see wxStyledTextEvent
*/

class wxStyledTextCtrl : public wxControl, public wxTextEntry
{
public:

    /**
        Ctor.
    */
    wxStyledTextCtrl(wxWindow *parent, wxWindowID id=wxID_ANY,
                     const wxPoint& pos = wxDefaultPosition,
                     const wxSize& size = wxDefaultSize, long style = 0,
                     const wxString& name = wxSTCNameStr);
    /**
        Default ctor.
    */
    wxStyledTextCtrl();
    
    
    /**
        Destructor.
    */
    ~wxStyledTextCtrl();

    /**
        Create the UI elements for a STC that was created with the default ctor. (For 2-phase create.)
    */
    bool Create(wxWindow *parent, wxWindowID id=wxID_ANY,
                const wxPoint& pos = wxDefaultPosition,
                const wxSize& size = wxDefaultSize, long style = 0,
                const wxString& name = wxSTCNameStr);


    // **** Generated methods {{{

%(METHOD_IDEFS)s

    //}}}



    // **** Manually declared methods


    /**
       Returns the line number of the line with the caret.
    */
    int GetCurrentLine();

    /**
       Extract style settings from a spec-string which is composed of one or
       more of the following comma separated elements:
    
          bold                    turns on bold
          italic                  turns on italics
          fore:[name or #RRGGBB]  sets the foreground colour
          back:[name or #RRGGBB]  sets the background colour
          face:[facename]         sets the font face name to use
          size:[num]              sets the font size in points
          eol                     turns on eol filling
          underline               turns on underlining
    */
    void StyleSetSpec(int styleNum, const wxString& spec);


    /**
       Get the font of a style.
    */
    wxFont StyleGetFont(int style);


    /**
       Set style size, face, bold, italic, and underline attributes from
       a wxFont's attributes.
    */
    void StyleSetFont(int styleNum, wxFont& font);



    /**
       Set all font style attributes at once.
    */
    void StyleSetFontAttr(int styleNum, int size,
                          const wxString& faceName,
                          bool bold, bool italic,
                          bool underline,
                          wxFontEncoding encoding=wxFONTENCODING_DEFAULT);


    /**
       Set the character set of the font in a style.  Converts the Scintilla
       character set values to a wxFontEncoding.
    */
    void StyleSetCharacterSet(int style, int characterSet);

    /**
       Set the font encoding to be used by a style.
    */
    void StyleSetFontEncoding(int style, wxFontEncoding encoding);


    /**
       Perform one of the operations defined by the wxSTC_CMD_* constants.
    */
    void CmdKeyExecute(int cmd);


    /**
       Set the left and right margin in the edit area, measured in pixels.
    */
    void SetMargins(int left, int right);


    /**
       Retrieve the point in the window where a position is displayed.
    */
    wxPoint PointFromPosition(int pos);


    /**
       Scroll enough to make the given line visible
    */
    void ScrollToLine(int line);


    /**
       Scroll enough to make the given column visible
    */
    void ScrollToColumn(int column);


    /**
       Send a message to Scintilla
    */
    wxIntPtr SendMsg(int msg, wxUIntPtr wp=0, wxIntPtr lp=0) const;


    /**
       Set the vertical scrollbar to use instead of the ont that's built-in.
    */
    void SetVScrollBar(wxScrollBar* bar);


    /**
       Set the horizontal scrollbar to use instead of the ont that's built-in.
    */
    void SetHScrollBar(wxScrollBar* bar);

    /**
       Can be used to prevent the EVT_CHAR handler from adding the char
    */
    bool GetLastKeydownProcessed();
    void SetLastKeydownProcessed(bool val);

    /**
       Write the contents of the editor to filename
    */
    bool SaveFile(const wxString& filename);

    /**
       Load the contents of filename into the editor
    */
    bool LoadFile(const wxString& filename);

    /**
       Allow for simulating a DnD DragOver
    */
    wxDragResult DoDragOver(wxCoord x, wxCoord y, wxDragResult defaultRes);

    /**
       Allow for simulating a DnD DropText
    */
    bool DoDropText(long x, long y, const wxString& data);

    /**
       Clear annotations from the given line.
    */
    void AnnotationClearLine(int line);


    /**
       Add text to the document at current position.
    */
    void AddTextRaw(const char* text, int length=-1);

    /**
       Insert string at a position.
    */
    void InsertTextRaw(int pos, const char* text);

    /**
       Retrieve the text of the line containing the caret.
       Returns the index of the caret on the line.
    */
    wxCharBuffer GetCurLineRaw(int* linePos=NULL);

    /**
       Retrieve the contents of a line.
    */
    wxCharBuffer GetLineRaw(int line);

    /**
       Retrieve the selected text.
    */
    wxCharBuffer GetSelectedTextRaw();

    /**
       Retrieve a range of text.
    */
    wxCharBuffer GetTextRangeRaw(int startPos, int endPos);

    /**
       Replace the contents of the document with the argument text.
    */
    void SetTextRaw(const char* text);

    /**
       Retrieve all the text in the document.
    */
    wxCharBuffer GetTextRaw();

    /**
       Append a string to the end of the document without changing the selection.
    */
    void AppendTextRaw(const char* text, int length=-1);


    static wxVersionInfo GetLibraryVersionInfo();



    // wxTextEntryBase pure virtual methods
    // ----------------------------------------------

    virtual void WriteText(const wxString& text);
    virtual void Remove(long from, long to);
    virtual void Replace(long from, long to, const wxString& text);

    virtual void SetInsertionPoint(long pos);
    virtual long GetInsertionPoint() const;
    virtual long GetLastPosition() const;

    virtual void SetSelection(long from, long to);
    virtual void SelectNone();
    virtual void GetSelection(long *from, long *to) const;

    virtual bool IsEditable() const;
    virtual void SetEditable(bool editable);

    // wxTextAreaBase pure virtual methods
    // ---------------------------------------------

    virtual int GetLineLength(long n) const;
    virtual wxString GetLineText(long n) const;
    virtual int GetNumberOfLines() const;

    virtual bool IsModified() const;
    virtual void MarkDirty();
    virtual void DiscardEdits();

    virtual bool SetStyle(long start, long end, const wxTextAttr& style);
    virtual bool GetStyle(long position, wxTextAttr& style);
    virtual bool SetDefaultStyle(const wxTextAttr& style);
    
    virtual long XYToPosition(long x, long y) const;
    virtual bool PositionToXY(long pos, long *x, long *y) const;
    
    virtual void ShowPosition(long pos);

    virtual wxTextCtrlHitTestResult HitTest(const wxPoint& pt, long *pos) const;
    virtual wxTextCtrlHitTestResult HitTest(const wxPoint& pt,
                                            wxTextCoord *col,
                                            wxTextCoord *row) const;
};

//----------------------------------------------------------------------

/**
    @class wxStyledTextEvent

    The type of events sent from wxStyledTextCtrl.

    @todo list styled text ctrl events.

    @library{stc}
    @category{events,stc}
*/

class wxStyledTextEvent : public wxCommandEvent {
public:
    wxStyledTextEvent(wxEventType commandType=0, int id=0);
    wxStyledTextEvent(const wxStyledTextEvent& event);
    ~wxStyledTextEvent();

    void SetPosition(int pos);
    void SetKey(int k);
    void SetModifiers(int m);
    void SetModificationType(int t);
    void SetText(const wxString& t);
    void SetLength(int len);
    void SetLinesAdded(int num);
    void SetLine(int val);
    void SetFoldLevelNow(int val);
    void SetFoldLevelPrev(int val);
    void SetMargin(int val);
    void SetMessage(int val);
    void SetWParam(int val);
    void SetLParam(int val);
    void SetListType(int val);
    void SetX(int val);
    void SetY(int val);
    void SetToken(int val);
    void SetAnnotationLinesAdded(int val);
    void SetUpdated(int val);
    void SetDragText(const wxString& val);
    void SetDragFlags(int flags);
    void SetDragResult(wxDragResult val);

    int  GetPosition() const;
    int  GetKey()  const;
    int  GetModifiers() const;
    int  GetModificationType() const;
    wxString GetText() const;
    int  GetLength() const;
    int  GetLinesAdded() const;
    int  GetLine() const;
    int  GetFoldLevelNow() const;
    int  GetFoldLevelPrev() const;
    int  GetMargin() const;
    int  GetMessage() const;
    int  GetWParam() const;
    int  GetLParam() const;
    int  GetListType() const;
    int  GetX() const;
    int  GetY() const;
    int  GetToken() const;
    int  GetAnnotationsLinesAdded() const;
    int  GetUpdated() const;
    
    wxString GetDragText();
    int GetDragFlags();
    wxDragResult GetDragResult();

    bool GetShift() const;
    bool GetControl() const;
    bool GetAlt() const;
};



const wxEventType wxEVT_STC_CHANGE;
const wxEventType wxEVT_STC_STYLENEEDED;
const wxEventType wxEVT_STC_CHARADDED;
const wxEventType wxEVT_STC_SAVEPOINTREACHED;
const wxEventType wxEVT_STC_SAVEPOINTLEFT;
const wxEventType wxEVT_STC_ROMODIFYATTEMPT;
const wxEventType wxEVT_STC_KEY;
const wxEventType wxEVT_STC_DOUBLECLICK;
const wxEventType wxEVT_STC_UPDATEUI;
const wxEventType wxEVT_STC_MODIFIED;
const wxEventType wxEVT_STC_MACRORECORD;
const wxEventType wxEVT_STC_MARGINCLICK;
const wxEventType wxEVT_STC_NEEDSHOWN;
const wxEventType wxEVT_STC_PAINTED;
const wxEventType wxEVT_STC_USERLISTSELECTION;
const wxEventType wxEVT_STC_URIDROPPED;
const wxEventType wxEVT_STC_DWELLSTART;
const wxEventType wxEVT_STC_DWELLEND;
const wxEventType wxEVT_STC_START_DRAG;
const wxEventType wxEVT_STC_DRAG_OVER;
const wxEventType wxEVT_STC_DO_DROP;
const wxEventType wxEVT_STC_ZOOM;
const wxEventType wxEVT_STC_HOTSPOT_CLICK;
const wxEventType wxEVT_STC_HOTSPOT_DCLICK;
const wxEventType wxEVT_STC_CALLTIP_CLICK;
const wxEventType wxEVT_STC_AUTOCOMP_SELECTION;
const wxEventType wxEVT_STC_INDICATOR_CLICK;
const wxEventType wxEVT_STC_INDICATOR_RELEASE;
const wxEventType wxEVT_STC_AUTOCOMP_CANCELLED;
const wxEventType wxEVT_STC_AUTOCOMP_CHAR_DELETED;
const wxEventType wxEVT_STC_HOTSPOT_RELEASE_CLICK;