Package swingtree.style

Class TextSelectionConf

java.lang.Object
swingtree.style.TextSelectionConf
@Immutable public final class TextSelectionConf extends Object
Describes how the selected characters of a styled text look, inside the text style of a component: 

  UI.box()
  .withStyle( it -> it
      .text("body", t -> t
          .content("Hello world")
          .selection( s -> s.color(new Color(80, 140, 255, 90)).borderRadius(6) )
      )
  )
  .withTextSelection("body", selection);
The selection itself, which says which characters are selected, is not part of this configuration. It is held by the property which you pass to UIForAnySwing.withTextSelection(swingtree.UI.Layer, String, sprouts.Var). **So please note that a component without withTextSelection paints no selection at all.**

SwingTree paints the selection colour, and the border if there is one, behind the selected characters and then paints the characters on top of it, in their own colour.

  • Method Details

    • color

      public TextSelectionConf color(Color color)
      Sets the colour which SwingTree paints behind the selected characters. A partly transparent colour lets the background of the component shine through. Without this method, the colour is a partly transparent light blue.
      Parameters:
      color - The colour behind the selected characters.
      Returns:
      A new selection configuration with the given colour.

    • borderRadius

      public TextSelectionConf borderRadius(double radius)
      Rounds every corner of the area which SwingTree paints behind the selected characters, with the same radius for the convex and the concave corners. It is the same as convexRadius(radius).concaveRadius(radius), see convexRadius(double) and concaveRadius(double). With a radius of 0, which is the default, the corners are square.
      Parameters:
      radius - The radius of the quarter circle of every corner, in pixels before the UI scale is applied.
      Returns:
      A new selection configuration with the given corner radius.

    • convexRadius

      public TextSelectionConf convexRadius(double radius)
      Rounds the convex corners of the area which SwingTree paints behind the selected characters. A convex corner points out of the area, like each of the four corners of a rectangle. Without mergeLines(boolean), the area behind the selected characters of every line is a rectangle, so all of its corners are convex. With a border, the outer edge of the border has this radius at a convex corner, and the inner edge of the border has this radius minus the width of the border, or a square corner when the border is wider than the radius. With a radius of 0, which is the default, the convex corners are square.
      Parameters:
      radius - The radius of the quarter circle of every convex corner, in pixels before the UI scale is applied.
      Returns:
      A new selection configuration with the given radius for convex corners.

    • concaveRadius

      public TextSelectionConf concaveRadius(double radius)
      Rounds the concave corners of the shape which mergeLines(boolean) makes from the selected parts of several lines. A concave corner points into the shape, like the corner where the end of a short line meets the longer line below it. With a radius above 0, SwingTree fills that corner with a curve, so the outline bends from the edge of the short line into the edge of the longer line. With a border, the outer edge of the border has this radius at a concave corner, and the inner edge of the border has this radius plus the width of the border, so the border is equally wide all along the corner. Without mergeLines(true), every area is a rectangle without concave corners, and this radius changes nothing. With a radius of 0, which is the default, the concave corners are square.
      Parameters:
      radius - The radius of the quarter circle of every concave corner, in pixels before the UI scale is applied.
      Returns:
      A new selection configuration with the given radius for concave corners.

    • mergeLines

      public TextSelectionConf mergeLines(boolean merge)
      Sets whether SwingTree paints the selected parts of several lines as one shape. Without this, which is the default, SwingTree paints a separate rectangle behind the selected characters of every line, each with its own rounded corners and its own border. With mergeLines(true), the rectangles of two neighbouring lines are joined into one shape where they overlap horizontally, and the border runs only along the outline of that shape, never between two lines. Rectangles which do not touch, for example the rectangles on the two sides of an obstacle on the same line, are not joined to each other, and the shape never covers an obstacle. The corners of the shape are rounded with convexRadius(double) and concaveRadius(double).
      Parameters:
      merge - true to paint the selected parts of neighbouring lines as one shape.
      Returns:
      A new selection configuration which joins the lines or not.

    • border

      public TextSelectionConf border(double width, Color color)
      Paints a border of the given width and colour along the inner edge of every area which SwingTree paints behind the selected characters of a line. The border takes its width from the area: the outer edge of the border is where the edge of the area would be without a border, so a selection with a border is exactly as large as a selection without one. The selection colour is painted only inside the border and never under it, so a partly transparent border colour shows the background of the component behind it. How the corners of the border are rounded is described in convexRadius(double) and concaveRadius(double). A width of 0, which is the default, paints no border.
      Parameters:
      width - The width of the border, in pixels before the UI scale is applied.
      color - The colour of the border.
      Returns:
      A new selection configuration with the given border.

    • borderWidth

      public TextSelectionConf borderWidth(double width)
      Sets the width of the border which SwingTree paints along the inner edge of the selection, see border(double, Color). The border is only painted when it also has a colour, which you set with borderColor(Color).
      Parameters:
      width - The width of the border, in pixels before the UI scale is applied.
      Returns:
      A new selection configuration with the given border width.

    • borderColor

      public TextSelectionConf borderColor(Color color)
      Sets the colour of the border which SwingTree paints along the inner edge of the selection, see border(double, Color). The border is only painted when it also has a width larger than 0, which you set with borderWidth(double).
      Parameters:
      color - The colour of the border.
      Returns:
      A new selection configuration with the given border colour.

    • showCaret

      public TextSelectionConf showCaret(boolean show)
      Decides whether SwingTree paints the caret when no character is selected. The caret marks the gap where a click with the shift key held down would continue the selection. It is a thin vertical bar unless you choose another shape with caretShape(UI.CaretShape). It does not blink. By default, it is not painted, because most styled texts are labels and descriptions which nobody types into. From the moment the component loses the keyboard focus until it gets it back, SwingTree does not paint the caret either, unless you pass false to useUnfocusedLook(boolean).
      Parameters:
      show - true to paint the caret when no character is selected.
      Returns:
      A new selection configuration which paints the caret or not.

    • caretColor

      public TextSelectionConf caretColor(Color color)
      Sets the colour of the caret, which SwingTree paints when showCaret(boolean) is enabled and no character is selected. Without this method, the caret has the colour of the font of the text, or black if the font has no single colour.
      Parameters:
      color - The colour of the caret.
      Returns:
      A new selection configuration with the given caret colour.

    • caretShape

      public TextSelectionConf caretShape(UI.CaretShape shape)
      Sets the shape of the caret, which SwingTree paints when showCaret(boolean) is enabled and no character is selected. A UI.CaretShape.BAR is a vertical bar in the gap, a UI.CaretShape.BLOCK covers the character behind the gap, and a UI.CaretShape.UNDERLINE is a line under that character. Behind the last character of a line, where no character follows the gap, a block and an underline are half as wide as the line is tall. SwingTree paints the caret behind the characters, so give a block a colour in which the character on top of it stays readable, see caretColor(Color). Without this method, the caret is a UI.CaretShape.BAR.
      Parameters:
      shape - The shape of the caret.
      Returns:
      A new selection configuration with the given caret shape.

    • caretWidth

      public TextSelectionConf caretWidth(double width)
      Sets how thick the caret is, which SwingTree paints when showCaret(boolean) is enabled and no character is selected. It is the width of a UI.CaretShape.BAR, which grows to the right of the gap, and the height of an UI.CaretShape.UNDERLINE, which grows upwards from the bottom of the line. A UI.CaretShape.BLOCK is as wide as the character it covers, so this width does not change it. However thin you make it, SwingTree paints the caret at least one pixel thick on the screen. Without this method, the caret is 1 pixel thick.
      Parameters:
      width - The thickness of the caret, in pixels before the UI scale is applied.
      Returns:
      A new selection configuration with the given caret width.

    • caretRadius

      public TextSelectionConf caretRadius(double radius)
      Rounds the corners of the caret, which SwingTree paints when showCaret(boolean) is enabled and no character is selected. Every corner of the caret becomes a quarter circle with this radius, or with half the length of the shorter side of the caret when this radius is larger. So any radius of at least half of the caretWidth(double) turns a UI.CaretShape.BAR into a thin pill with round ends, and an UI.CaretShape.UNDERLINE into a flat pill. The rounding only cuts the corners off, so the caret never reaches outside of TextSelection.caretBounds(). With a radius of 0, which is the default, the corners are square: 
      
  .selection( s -> s.showCaret(true).caretWidth(3).caretRadius(1.5) )
      Parameters:
      radius - The radius of the quarter circle of every corner of the caret, in pixels before the UI scale is applied.
      Returns:
      A new selection configuration with the given corner radius for the caret.

    • unfocusedColor

      public TextSelectionConf unfocusedColor(Color color)
      Sets the colour which SwingTree paints behind the selected characters from the moment the component loses the keyboard focus until it gets it back. Many programs, like the text fields of web browsers and of macOS, grey a selection when the keyboard focus goes elsewhere, so that your users can tell at a glance where the keys they type go to: 
      
  .selection( s -> s
      .color(new Color(80, 140, 255, 90))
      .unfocusedColor(new Color(160, 160, 160, 90))
  )
      A component which never had the keyboard focus looks focused. Without this method, SwingTree takes the colour of color(Color) and removes most of its saturation while it keeps its transparency and its brightness, so the selection turns grey but stays as easy to see as before. With useUnfocusedLook(false), SwingTree never paints this colour.
      Parameters:
      color - The colour behind the selected characters after the component lost the keyboard focus.
      Returns:
      A new selection configuration with the given colour for an unfocused component.

    • unfocusedBorderColor

      public TextSelectionConf unfocusedBorderColor(Color color)
      Sets the colour of the border of the selection from the moment the component loses the keyboard focus until it gets it back, see border(double, Color) and unfocusedColor(Color). This colour only replaces the colour of a border which SwingTree paints while the component has the focus, so a selection without a border colour or without a border width gets no border from it. Without this method, SwingTree takes the colour of borderColor(Color) and removes most of its saturation while it keeps its transparency and its brightness.
      Parameters:
      color - The colour of the border after the component lost the keyboard focus.
      Returns:
      A new selection configuration with the given border colour for an unfocused component.

    • useUnfocusedLook

      public TextSelectionConf useUnfocusedLook(boolean use)
      Decides whether the selection looks different from the moment the component loses the keyboard focus until it gets it back. A component which never had the keyboard focus always looks focused. By default, which is true, SwingTree paints the selection in the colours of unfocusedColor(Color) and unfocusedBorderColor(Color) and paints no caret from the moment the component loses the keyboard focus until it gets it back. With false, the keyboard focus changes nothing that your users can see: the selection keeps the colours of color(Color) and borderColor(Color), and the caret of showCaret(boolean) stays where it is. This suits an application whose look should not change with the keyboard focus, and a test which compares pictures of the component taken while the keyboard focus is somewhere else.
      Parameters:
      use - true to grey the selection and hide the caret after the component lost the keyboard focus.
      Returns:
      A new selection configuration which changes its look with the keyboard focus or not.

    • selectWordOnDoubleClick

      public TextSelectionConf selectWordOnDoubleClick(boolean select)
      Decides whether a double click selects the word under the mouse. A word is what BreakIterator.getWordInstance() finds around the character under the mouse, which follows the word rules of many languages, so "don't" is one word. The arrow keys with Ctrl held down, see navigateWithKeyboard(boolean), jump over words by the same rules. By default, which is true, a double click selects the word. With false, the second click of a double click does what a single click does: it puts the caret into the gap nearest to the mouse.
      Parameters:
      select - true to select the word under the mouse on a double click.
      Returns:
      A new selection configuration which selects a word on a double click or not.

    • selectParagraphOnTripleClick

      public TextSelectionConf selectParagraphOnTripleClick(boolean select)
      Decides whether a triple click selects the paragraph under the mouse. A paragraph is everything between two line breaks of the text, the '\n' characters, however many painted lines it wraps over. The line breaks themselves are not selected, so a paragraph which your users copy does not end with an empty line. By default, which is true, a triple click selects the paragraph. With false, the third click of a triple click does what a single click does: it puts the caret into the gap nearest to the mouse. 
      
  .selection( s -> s.selectParagraphOnTripleClick(false) )
      Parameters:
      select - true to select the paragraph under the mouse on a triple click.
      Returns:
      A new selection configuration which selects a paragraph on a triple click or not.

    • selectWordOnLongPress

      public TextSelectionConf selectWordOnLongPress(boolean select)
      Decides whether holding the left mouse button down on a word, without moving the mouse, selects that word, like a long press of a finger on the screen of a phone. After about half a second the word under the mouse is selected. A movement of up to 5 pixels before then is allowed, because a finger never holds perfectly still. Like every size of a style, these 5 pixels are multiplied by the UI scale, so they are 10 pixels on the screen at a UI scale of 2. Moving further, releasing the button earlier, or the component losing the keyboard focus cancels it, and then a press only puts the caret, as it does without a long press. By default, which is false, holding the button down does nothing more than a click, because on a desktop your users select a word with a double click. 
      
  .selection( s -> s.selectWordOnLongPress(true) )
      Parameters:
      select - true to select the word under the mouse when the button is held down without moving.
      Returns:
      A new selection configuration which selects a word on a long press or not.

    • copyToClipboard

      public TextSelectionConf copyToClipboard(boolean copy)
      Decides whether your users can copy the selected characters. By default, which is true, Ctrl+C, or Command+C on macOS, puts the selected characters onto the clipboard of the computer, and so does the TransferHandler of the component when your code calls TransferHandler.exportToClipboard(javax.swing.JComponent, java.awt.datatransfer.Clipboard, int). With false, nothing reaches any clipboard, and whatever is on the clipboard stays there, for example for a text which your users may read and select but should type themselves. Your users can still select the characters, also everything at once with Ctrl+A or Command+A.
      Parameters:
      copy - true to let your users copy the selected characters.
      Returns:
      A new selection configuration which lets your users copy or not.

    • equals

      public boolean equals(Object other)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object