juce/source/src/gui/components/code_editor/juce_CodeEditorComponent.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_CODEEDITORCOMPONENT_JUCEHEADER__
  27 #define __JUCE_CODEEDITORCOMPONENT_JUCEHEADER__
  28
  29 #include "../juce_Component.h"
  30 #include "../layout/juce_ScrollBar.h"
  31 #include "../keyboard/juce_TextInputTarget.h"
  32 #include "../keyboard/juce_CaretComponent.h"
  33 #include "juce_CodeDocument.h"
  34 #include "juce_CodeTokeniser.h"
  35
  36
  37 //==============================================================================
  38 /**
  39     A text editor component designed specifically for source code.
  40
  41     This is designed to handle syntax highlighting and fast editing of very large
  42     files.
  43 */
  44 class JUCE_API  CodeEditorComponent   : public Component,
  45                                         public TextInputTarget,
  46                                         public Timer,
  47                                         public ScrollBar::Listener,
  48                                         public CodeDocument::Listener,
  49                                         public AsyncUpdater
  50 {
  51 public:
  52     //==============================================================================
  53     /** Creates an editor for a document.
  54
  55         The tokeniser object is optional - pass 0 to disable syntax highlighting.
  56         The object that you pass in is not owned or deleted by the editor - you must
  57         make sure that it doesn't get deleted while this component is still using it.
  58
  59         @see CodeDocument
  60     */
  61     CodeEditorComponent (CodeDocument& document,
  62                          CodeTokeniser* codeTokeniser);
  63
  64     /** Destructor. */
  65     ~CodeEditorComponent();
  66
  67     //==============================================================================
  68     /** Returns the code document that this component is editing. */
  69     CodeDocument& getDocument() const noexcept          { return document; }
  70
  71     /** Loads the given content into the document.
  72         This will completely reset the CodeDocument object, clear its undo history,
  73         and fill it with this text.
  74     */
  75     void loadContent (const String& newContent);
  76
  77     //==============================================================================
  78     /** Returns the standard character width. */
  79     float getCharWidth() const noexcept                         { return charWidth; }
  80
  81     /** Returns the height of a line of text, in pixels. */
  82     int getLineHeight() const noexcept                          { return lineHeight; }
  83
  84     /** Returns the number of whole lines visible on the screen,
  85         This doesn't include a cut-off line that might be visible at the bottom if the
  86         component's height isn't an exact multiple of the line-height.
  87     */
  88     int getNumLinesOnScreen() const noexcept                    { return linesOnScreen; }
  89
  90     /** Returns the number of whole columns visible on the screen.
  91         This doesn't include any cut-off columns at the right-hand edge.
  92     */
  93     int getNumColumnsOnScreen() const noexcept                  { return columnsOnScreen; }
  94
  95     /** Returns the current caret position. */
  96     const CodeDocument::Position getCaretPos() const            { return caretPos; }
  97
  98     /** Returns the position of the caret, relative to the editor's origin. */
  99     const Rectangle<int> getCaretRectangle();
 100
 101     /** Moves the caret.
 102         If selecting is true, the section of the document between the current
 103         caret position and the new one will become selected. If false, any currently
 104         selected region will be deselected.
 105     */
 106     void moveCaretTo (const CodeDocument::Position& newPos, bool selecting);
 107
 108     /** Returns the on-screen position of a character in the document.
 109         The rectangle returned is relative to this component's top-left origin.
 110     */
 111     const Rectangle<int> getCharacterBounds (const CodeDocument::Position& pos) const;
 112
 113     /** Finds the character at a given on-screen position.
 114         The co-ordinates are relative to this component's top-left origin.
 115     */
 116     const CodeDocument::Position getPositionAt (int x, int y);
 117
 118     //==============================================================================
 119     bool moveCaretLeft (bool moveInWholeWordSteps, bool selecting);
 120     bool moveCaretRight (bool moveInWholeWordSteps, bool selecting);
 121     bool moveCaretUp (bool selecting);
 122     bool moveCaretDown (bool selecting);
 123     bool scrollDown();
 124     bool scrollUp();
 125     bool pageUp (bool selecting);
 126     bool pageDown (bool selecting);
 127     bool moveCaretToTop (bool selecting);
 128     bool moveCaretToStartOfLine (bool selecting);
 129     bool moveCaretToEnd (bool selecting);
 130     bool moveCaretToEndOfLine (bool selecting);
 131     bool deleteBackwards (bool moveInWholeWordSteps);
 132     bool deleteForwards (bool moveInWholeWordSteps);
 133     bool copyToClipboard();
 134     bool cutToClipboard();
 135     bool pasteFromClipboard();
 136     bool undo();
 137     bool redo();
 138
 139     bool selectAll();
 140     void deselectAll();
 141
 142     void scrollToLine (int newFirstLineOnScreen);
 143     void scrollBy (int deltaLines);
 144     void scrollToColumn (int newFirstColumnOnScreen);
 145     void scrollToKeepCaretOnScreen();
 146
 147     void insertTextAtCaret (const String& textToInsert);
 148     void insertTabAtCaret();
 149
 150     //==============================================================================
 151     const Range<int> getHighlightedRegion() const;
 152     void setHighlightedRegion (const Range<int>& newRange);
 153     const String getTextInRange (const Range<int>& range) const;
 154
 155     //==============================================================================
 156     /** Changes the current tab settings.
 157         This lets you change the tab size and whether pressing the tab key inserts a
 158         tab character, or its equivalent number of spaces.
 159     */
 160     void setTabSize (int numSpacesPerTab, bool insertSpacesInsteadOfTabCharacters);
 161
 162     /** Returns the current number of spaces per tab.
 163         @see setTabSize
 164     */
 165     int getTabSize() const noexcept                     { return spacesPerTab; }
 166
 167     /** Returns true if the tab key will insert spaces instead of actual tab characters.
 168         @see setTabSize
 169     */
 170     bool areSpacesInsertedForTabs() const               { return useSpacesForTabs; }
 171
 172     /** Changes the font.
 173         Make sure you only use a fixed-width font, or this component will look pretty nasty!
 174     */
 175     void setFont (const Font& newFont);
 176
 177     /** Returns the font that the editor is using. */
 178     const Font& getFont() const noexcept                { return font; }
 179
 180     /** Resets the syntax highlighting colours to the default ones provided by the
 181         code tokeniser.
 182         @see CodeTokeniser::getDefaultColour
 183     */
 184     void resetToDefaultColours();
 185
 186     /** Changes one of the syntax highlighting colours.
 187         The token type values are dependent on the tokeniser being used - use
 188         CodeTokeniser::getTokenTypes() to get a list of the token types.
 189         @see getColourForTokenType
 190     */
 191     void setColourForTokenType (int tokenType, const Colour& colour);
 192
 193     /** Returns one of the syntax highlighting colours.
 194         The token type values are dependent on the tokeniser being used - use
 195         CodeTokeniser::getTokenTypes() to get a list of the token types.
 196         @see setColourForTokenType
 197     */
 198     const Colour getColourForTokenType (int tokenType) const;
 199
 200     //==============================================================================
 201     /** A set of colour IDs to use to change the colour of various aspects of the editor.
 202
 203         These constants can be used either via the Component::setColour(), or LookAndFeel::setColour()
 204         methods.
 205
 206         @see Component::setColour, Component::findColour, LookAndFeel::setColour, LookAndFeel::findColour
 207     */
 208     enum ColourIds
 209     {
 210         backgroundColourId          = 0x1004500,  /**< A colour to use to fill the editor's background. */
 211         highlightColourId           = 0x1004502,  /**< The colour to use for the highlighted background under
 212                                                        selected text. */
 213         defaultTextColourId         = 0x1004503   /**< The colour to use for text when no syntax colouring is
 214                                                        enabled. */
 215     };
 216
 217     //==============================================================================
 218     /** Changes the size of the scrollbars. */
 219     void setScrollbarThickness (int thickness);
 220
 221     /** Returns the thickness of the scrollbars. */
 222     int getScrollbarThickness() const noexcept          { return scrollbarThickness; }
 223
 224     //==============================================================================
 225     /** @internal */
 226     void resized();
 227     /** @internal */
 228     void paint (Graphics& g);
 229     /** @internal */
 230     bool keyPressed (const KeyPress& key);
 231     /** @internal */
 232     void mouseDown (const MouseEvent& e);
 233     /** @internal */
 234     void mouseDrag (const MouseEvent& e);
 235     /** @internal */
 236     void mouseUp (const MouseEvent& e);
 237     /** @internal */
 238     void mouseDoubleClick (const MouseEvent& e);
 239     /** @internal */
 240     void mouseWheelMove (const MouseEvent& e, float wheelIncrementX, float wheelIncrementY);
 241     /** @internal */
 242     void focusGained (FocusChangeType cause);
 243     /** @internal */
 244     void focusLost (FocusChangeType cause);
 245     /** @internal */
 246     void timerCallback();
 247     /** @internal */
 248     void scrollBarMoved (ScrollBar* scrollBarThatHasMoved, double newRangeStart);
 249     /** @internal */
 250     void handleAsyncUpdate();
 251     /** @internal */
 252     void codeDocumentChanged (const CodeDocument::Position& affectedTextStart,
 253                               const CodeDocument::Position& affectedTextEnd);
 254     /** @internal */
 255     bool isTextInputActive() const;
 256     /** @internal */
 257     void setTemporaryUnderlining (const Array <Range<int> >&);
 258
 259 private:
 260     //==============================================================================
 261     CodeDocument& document;
 262
 263     Font font;
 264     int firstLineOnScreen, gutter, spacesPerTab;
 265     float charWidth;
 266     int lineHeight, linesOnScreen, columnsOnScreen;
 267     int scrollbarThickness, columnToTryToMaintain;
 268     bool useSpacesForTabs;
 269     double xOffset;
 270
 271     CodeDocument::Position caretPos;
 272     CodeDocument::Position selectionStart, selectionEnd;
 273
 274     ScopedPointer<CaretComponent> caret;
 275     ScrollBar verticalScrollBar, horizontalScrollBar;
 276
 277     enum DragType
 278     {
 279         notDragging,
 280         draggingSelectionStart,
 281         draggingSelectionEnd
 282     };
 283
 284     DragType dragType;
 285
 286     //==============================================================================
 287     CodeTokeniser* codeTokeniser;
 288     Array <Colour> coloursForTokenCategories;
 289
 290     class CodeEditorLine;
 291     OwnedArray <CodeEditorLine> lines;
 292     void rebuildLineTokens();
 293
 294     OwnedArray <CodeDocument::Iterator> cachedIterators;
 295     void clearCachedIterators (int firstLineToBeInvalid);
 296     void updateCachedIterators (int maxLineNum);
 297     void getIteratorForPosition (int position, CodeDocument::Iterator& result);
 298     void moveLineDelta (int delta, bool selecting);
 299
 300     //==============================================================================
 301     void updateCaretPosition();
 302     void updateScrollBars();
 303     void scrollToLineInternal (int line);
 304     void scrollToColumnInternal (double column);
 305     void newTransaction();
 306     void cut();
 307
 308     int indexToColumn (int line, int index) const noexcept;
 309     int columnToIndex (int line, int column) const noexcept;
 310
 311     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (CodeEditorComponent);
 312 };
 313
 314
 315 #endif   // __JUCE_CODEEDITORCOMPONENT_JUCEHEADER__