Constructor Detail

• TextView

  public TextView()

  Create an empty TextView without (yet) having an associated TextBuffer. Use setBuffer() to indicate later which TextBuffer to use.

  Since:

  4.0.9

• TextView

  public TextView(TextBuffer buffer)

  Create a TextView and display the contents of the TextBuffer.

  Since:

  4.0.9

Method Detail

• add

  public void add(Widget child,
         TextIter position)

  Load a Widget into the TextView at the given position.

  A very impressive feature of TextViews is that you can embed Widgets into them! You supply the position where you want the Widget to be anchored, and the Widget will appear in the display amidst the rest of your text. Don't forget to show() the Widget you're adding or it won't appear.

  There is an insert() method available on TextBuffer which wraps this; you may find it more convenient.

  The underlying library is somewhat convoluted about this due to the fact that more than one TextView can be displaying a given TextBuffer, but a Widget can only appear in one parent Container. GTK uses an intermediate called TextChildAnchor to bridge between TextView and TextBuffer; we take care of handling that for you.

  Since:

  4.0.9

• add

  public void add(Widget child,
         TextWindowType which,
         int x,
         int y)

  Place a child Widget into one of the optional side panels around a TextView. This is an advanced feature; see TextWindowType for a full discussion.

  The Widget child will be placed at the coordinates x,y in the [org.gnome.gdk] Window specified by which. You can get that Window by calling TextView's variant of getWindow().

  This cannot be used unless which has been initialized to have a non-zero size with setBorderWindowSize().

  WARNING
  This feature seems somewhat poorly implemented in the underlying library. While we have fully exposed it, testing showed it to be rather difficult to use reliably. Sorry we can't do better for you.

  Since:

  4.0.9

• attachSpell

  public void attachSpell()

  Create and attach a Spell object to the view to add spellchecking capability.

  The language is chosen based on the value of LANG environment variable.

  Since:

  4.0.12

• attachSpell

  public void attachSpell(String lang)

  Create and attach a Spell object to the view to add spellchecking capability in the given language.

  You're probably just as well to call attachSpell() and accept the default.

  Since:

  4.0.12

• connect

  public void connect(TextView.PopulatePopup handler)

  Hook up a handler to receive TextView.PopulatePopup signals on this TextView. This will be emitted each time the user right-clicks or presses the Menu key, and allows you to populate the popup menu according to the current circumstances - in other words, making it a context menu.

  Since:

  4.0.9

• convertBufferToWindowCoordsX

  public int convertBufferToWindowCoordsX(TextWindowType which,
                                 int X)

  Convert X from buffer co-ordinates to window co-ordinates. See convertBufferToWindowCoordsY() for a detailed discussion.

  Since:

  4.0.9

• convertBufferToWindowCoordsY

  public int convertBufferToWindowCoordsY(TextWindowType which,
                                 int Y)

  The canvas that is used to present the text in a TextView has an origin at 0,0 that is at the top left corner. and extends for as many pixels as would be necessary to present the entire TextBuffer if it were shown on an arbitrarily large screen without scrolling.

  In most cases, the text shown will require an area larger than the viewport provided by the primary area of the TextView. Even without scrollbars (which can be added by putting the TextView into a ScrolledWindow), the viewport showing the text will slide when the cursor is moved down from the start position and into the body of text. Thus you can be at a position in buffer co-ordinates that is far "greater" than the size of the [org.gnome.gdk] Window that displays it.

  Numerous methods, notably getLineY(), return a value in buffer co-ordinates. If you need to determine what position this represents on screen, you need to convert to window co-ordinates which are relative to the top left corner of the [org.gnome.gdk] Window being used to present the text on screen. This method will carry out that conversion for the vertical axis. See convertBufferToWindowCoordsX() for the corresponding horizontal conversion.

  Since:

  4.0.9

• convertWindowToBufferCoordsX

  public int convertWindowToBufferCoordsX(TextWindowType which,
                                 int x)

  Convert a horizontal position from window co-ordinates (the on screen position) to buffer co-ordinates (the pixel distance into the canvas used to describe the entire text being displayed). See convertBufferToWindowCoordsY() for a detailed discussion.

  Since:

  4.0.9

• convertWindowToBufferCoordsY

  public int convertWindowToBufferCoordsY(TextWindowType which,
                                 int y)

  Convert a vertical position from window co-ordinates to buffer co-ordinates. See convertBufferToWindowCoordsY() for a detailed discussion.

  Since:

  4.0.9

• getBuffer

  public TextBuffer getBuffer()

  Get the TextBuffer currently underlying this TextView.

  Since:

  4.0.9

• getCursorVisible

  public boolean getCursorVisible()

  Returns whether the cursor is currently visible or not.

  Since:

  4.0.9

• getEditable

  public boolean getEditable()

  Get whether the default editability of the TextView. Tags in the buffer may override this setting for some ranges of text.

  Since:

  4.0.9

• getIterAtLocation

  public TextIter getIterAtLocation(int X,
                           int Y)

  Get a TextIter corresponding to a given location in the canvas that is displayed by the TextView. X,Y are in buffer co-ordinates; if you have a position into the [org.gnome.gdk] Window then use convertWindowToBufferCoordsY() to convert.

  Since:

  4.0.9

• getLineRange

  public int getLineRange(TextIter position)

  This is the compliment of getLineY(), giving you the corresponding line height that drops from the top specified by that method.

  WARNING
  Line height values are cached by are not immediately refreshed when the underlying TextBuffer changes; see the comment titled "Line Height Calculations" in the documentation for this class for discussion of when you can safely use this method.

  Since:

  4.0.9

• getLineY

  public int getLineY(TextIter position)

  Get the y co-ordinate of the line holding the supplied position. The value is in buffer co-ordinates, and refers to the top of the line. If you need to know how high the line is, call getLineRange().

  WARNING
  The co-ordinates of the start of each line height are cached are not immediately updated when the underlying TextBuffer changes; see the comment titled "Line Height Calculations" in the documentation for this class for discussion of when you can safely use this method.

  Since:

  4.0.9

• getLocation

  public Rectangle getLocation(TextIter pointer)

  Get a Rectangle enclosing the screen position of the given TreeIter. This will be in buffer co-ordinates.

  This is very useful in a TextBuffer.NotifyCursorPosition if you need to figure out where the cursor is so as to handle presentation of some external control accordingly.

  Since:

  4.0.10

• getSpell

  public org.gnome.gtk.Spell getSpell()

  Get the Spell helper object attached to the view.

  Reasons you might need to use this are if you have to programatically change the language being used to spell check against with Spell's setLanguage(), or to force the checker to run again with its recheckAll(). You probably won't ever need either.

  Obviously there isn't much point in asking for the Spell helper object if you haven't called attachSpell() to create one yet.

  Since:

  4.0.12

• getVisibleRectangle

  public Rectangle getVisibleRectangle()

  Get the Rectangle describing what portion of the text canvas the viewport is currently showing. This is (only) relevant when scrollbars are employed.

  If you consider the text being displayed as a canvas of a fixed size, but have turned on scrolling and only have a limited portion of that canvas displayed due to the Widget being sized smaller than that canvas, then the x,y co-ordinates returned in the Rectangle represent the current offset into that canvas that the viewport is showing.

  If, for example, you only have vertical scrolling enabled,

   view.setWrapMode(WORD);
   scroll = new ScrolledWindow();
   scroll.setPolicy(NEVER, ALWAYS);
   scroll.add(view);
   

  then you can expect getVisibleRectangle() to always return Rectangles with an x offset value of 0 - the viewport is never scrolled horizontally into the text canvas.

  The width and height will, more or less, correspond to the size of the area of text actually being displayed in the TextView.

  See getLocation() if you need a Rectangle enclosing a given TextIter.

  Since:

  4.0.9

• getWindow

  public Window getWindow(TextWindowType which)

  Get the underlying resource corresponding with one of the sub elements of this TextView. See TextWindowType for a detailed discussion.

  Since:

  4.0.9

• getWrapMode

  public WrapMode getWrapMode()

  Get the line wrapping for the view.

  Since:

  4.0.9

• moveChild

  public void moveChild(Widget child,
               int x,
               int y)

  Change the co-ordinates of a child Widget in one of the optional side panels. x,y are specified in window co-ordinates.

  Since:

  4.0.9

• placeCursorOnscreen

  public void placeCursorOnscreen()

  Move the cursor (ie, the insert TextMark in the current source TextBuffer) so that is is showing somewhere in the section of text currently displayed in the viewport.

  Since:

  4.0.9

• scrollTo

  public void scrollTo(TextIter pointer)

  Scroll the viewport so that pointer is visible. This will get the location specified onto the screen with as little scroll movement as possible. If you need finer grained control, use one of the other scrollTo() variants. variant.

  Since:

  4.0.9

• scrollTo

  public void scrollTo(TextIter pointer,
              double withinMargin,
              double xalign,
              double yalign)

  Scroll the viewport so that pointer is visible, attempting to fine tune the result of the scrolling. See the scrollTo() method taking a TextMark and the same parameters for a detailed discussion of their use.

  Since:

  4.0.9

• scrollTo

  public void scrollTo(TextMark mark)

  Scroll the viewport so that mark is visible. This will have the effect of doing the minimum necessary scrolling to get the location specified by the TextMark onto the screen.

  See also the full scrollTo() which takes additional parameters which may allow you to fine tune the result of the scrolling.

  Since:

  4.0.9

• scrollTo

  public void scrollTo(TextMark mark,
              double withinMargin,
              double xalign,
              double yalign)

  Scroll the viewport so that mark is visible.

  The GTK documentation states that the the effective screen will be reduced by withinMargin. The acceptable range is 0.0 to 0.5. TODO It would be cool if someone could figure out what that actually means; the allowed range is clearly not a multiplier, so what is it?

  The alignment parameters have the same meaning as elsewhere in GTK: 0.0 for top|right, 1.0 for bottom|left.

  If you don't need to mess with margins or alignment, then just use the single arg scrollTo() method.

  WARNING
  It turns out that much of TextView's processing is done in idle callbacks. In particular, this method only works correctly if the heights of each line have been computed and cached. Since doing so can be computationally expensive, it happens some time after text is actually inserted and thus may not be available yet. In theory the scrolling will be queued up, but you may notice odd effects.

  This problem can crop up if you have newly populated a large amount of text into a TextView and want to force the viewport and cursor to be at the end of the text. One possible workaround: after doing the large insertAtCursor(), you might try the following:

   start = buffer.getIterStart();
   buffer.placeCursor(start);
   

  before calling

   end = buffer.getIterEnd();
   view.scrollTo(end);
   

  this may have the effect of causing the heights to be calculated.

  Since:

  4.0.9

• setAcceptsTab

  public void setAcceptsTab(boolean setting)

  Set the behaviour when the Tab key is pressed. The default is true, that a '\t' character will be inserted into the underlying TextBuffer. If you would rather that Tab causes the focus to change to the next Widget rather than inserting a tab, then set this to false.

  Since:

  4.0.9

• setBorderWindowSize

  public void setBorderWindowSize(TextWindowType which,
                         int size)

  Set the size (width for LEFT and RIGHT and height for TOP and BOTTOM) of the specified side panels. You only need this if using the optional side panels, and obscure, advanced, and not wholly functional feature; see TextWindowType. If you're reading this and wanting to set the padding around the TextView, you probably want setBorderWidth(), a method inherited from Container.

  Since:

  4.0.9

• setBuffer

  public void setBuffer(TextBuffer buffer)

  Set or replace the TextBuffer that is currently being displayed by this TextView.

  Since:

  4.0.9

• setCursorVisible

  public void setCursorVisible(boolean visible)

  Allows you to activate or deactivate the visible cursor. Usually used to hide the cursor when displaying text that is non-editable. The default is true, indicating the cursor will be shown.

  Since:

  4.0.9

• setEditable

  public void setEditable(boolean editable)

  Set whether the normal state of this TextView is to allow editing or not. The default for the editability property is true.

  Regardless of the default setting here, you can override this for specific regions of text with by applying TextTags with setEditable() set.

  Since:

  4.0.9

• setJustify

  public void setJustify(Justification setting)

  Tell this TextView to adopt the given justification. This is probably what you think of as "alignment".

  Since:

  4.0.14

• setMarginLeft

  public void setMarginLeft(int pixels)

  Set the padding to appear on the left side of the text. The default is 0.

  This sets the left-margin property in GTK.

  Since:

  4.0.9

• setMarginRight

  public void setMarginRight(int pixels)

  Set the padding to appear on the right side of the text. The default is 0.

  This sets the right-margin property in GTK.

  Since:

  4.0.9

• setPaddingAboveParagraph

  public void setPaddingAboveParagraph(int pixels)

  Set the padding that will be put above each paragraph of text in the TextView. The default is 0; if you change this then the first line will be offset from the top edge of the TextView.

  See also setPaddingBelowParagraph() and setPaddingInsideParagraph().

  This sets the pixels-above-lines property in GTK.

  Since:

  4.0.9

• setPaddingBelowParagraph

  public void setPaddingBelowParagraph(int pixels)

  Set the padding that will be put below each paragraph of text in the TextView. The default is 0, ie for it just to continue with normal line spacing as specified by the current font metrics.

  See also setPaddingAboveParagraph() and setPaddingInsideParagraph().

  This sets the pixels-below-lines property in GTK.

  Since:

  4.0.9

• setPaddingInsideParagraph

  public void setPaddingInsideParagraph(int pixels)

  Set the padding that will be put between each line in a paragraph if wrapping is turned on. Wrapping happens as a result of enabling setWrapMode() along with something acting to restrict the width allocated to the TextView (for example, by placing it in a ScrolledWindow). When wrapping occurs, then a single line of text in a TextBuffer will become a paragraph of multiple lines in the TextView displaying it.

  The default is 0, ie to leave the line spacing alone. If nothing is causing lines to wrap then this setting will have no effect.

  See also setPaddingAboveParagraph() and setPaddingBelowParagraph() for the spacing before and after each paragraph (wrapped or not).

  This sets the pixels-inside-wrap property in GTK.

  Since:

  4.0.9

• setWrapMode

  public void setWrapMode(WrapMode mode)

  Set the line wrapping for the view.

  Since:

  4.0.9