• Home
• org.fxmisc.richtext
• richtextfx
• 0.10.1
• source code
• Selection.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

org.fxmisc.richtext.Selection Maven / Gradle / Ivy

package org.fxmisc.richtext;

import javafx.beans.value.ObservableValue;
import javafx.geometry.Bounds;
import javafx.scene.control.IndexRange;
import org.fxmisc.richtext.model.StyledDocument;

import java.text.BreakIterator;
import java.util.Optional;

/**
 * An object for encapsulating a selection in a given area.
 *
 * 

 *     "Position" refers to the place in-between characters. In other words, every {@code "|"} in
 *     {@code "|t|e|x|t|"} is a valid position. There are two kinds of positions used here:
 *     

 *         

 *             {@link #getStartPosition()}/{@link #getEndPosition()}, which refers to a position somewhere in the
 *             entire area's content. It's bounds are {@code 0 <= x <= area.getLength()}.
 *         
 *         

 *             {@link #getStartColumnPosition()}/{@link #getEndColumnPosition()}, which refers to a position
 *             somewhere in the current paragraph. It's bounds are {@code 0 <= x <= area.getParagraphLength(index)}.
 *         
 *     
 *
 * Note: when parameter names are "position" without the "column" prefix, they refer to the position in the entire area.
 *
 * 

 *     For type safety, {@link #getSelectedDocument()} requires the same generic types from {@link StyledDocument}.
 *     This means that one must write a lot of boilerplate for the generics:
 *     {@code Selection, StyledText>, Collection> selection}.
 *     However, this is only necessary if one is using {@link #getSelectedDocument()} or
 *     {@link #selectedDocumentProperty()}. If you are not going to use the "selectedDocument" getter or property,
 *     then just write the much simpler {@code Selection selection}.
 * 
 *
 * @see CaretSelectionBind
 * @see Caret
 *
 * @param  type for {@link StyledDocument}'s paragraph style; only necessary when using the "selectedDocument"
 *            getter or property
 * @param  type for {@link StyledDocument}'s segment type; only necessary when using the "selectedDocument"
 *            getter or property
 * @param  type for {@link StyledDocument}'s segment style; only necessary when using the "selectedDocument"
 *            getter or property
 */
public interface Selection {

    /**
     * Specifies whether to update the start/end value of a selection to the left (towards 0) or right (away from 0)
     */
    public static enum Direction {
        LEFT,
        RIGHT
    }

    /* ********************************************************************** *
     *                                                                        *
     * Observables                                                            *
     *                                                                        *
     * Observables are "dynamic" (i.e. changing) characteristics of this      *
     * control. They are not directly settable by the client code, but change *
     * in response to user input and/or API actions.                          *
     *                                                                        *
     * ********************************************************************** */

    /**
     * The start and end positions in the area as an {@link IndexRange}.
     */
    ObservableValue rangeProperty();
    IndexRange getRange();

    /**
     * The length of the selection
     */
    ObservableValue lengthProperty();
    int getLength();

    /**
     * The number of paragraphs the selection spans
     */
    ObservableValue paragraphSpanProperty();
    int getParagraphSpan();

    ObservableValue> selectedDocumentProperty();
    StyledDocument getSelectedDocument();

    ObservableValue selectedTextProperty();
    String getSelectedText();


    ObservableValue startPositionProperty();
    int getStartPosition();

    ObservableValue startParagraphIndexProperty();
    int getStartParagraphIndex();

    ObservableValue startColumnPositionProperty();
    int getStartColumnPosition();


    ObservableValue endPositionProperty();
    int getEndPosition();

    ObservableValue endParagraphIndexProperty();
    int getEndParagraphIndex();

    ObservableValue endColumnPositionProperty();
    int getEndColumnPosition();


    /**
     * The selectionBoundsProperty of the selection in the Screen's coordinate system if something is selected and visible in the
     * viewport, or {@link Optional#empty()} if selection is not visible in the viewport.
     */
    ObservableValue> selectionBoundsProperty();
    Optional getSelectionBounds();

    boolean isBeingUpdated();
    ObservableValue beingUpdatedProperty();

    /* ********************************************************************** *
     *                                                                        *
     * Actions                                                                *
     *                                                                        *
     * Actions change the state of this control. They typically cause a       *
     * change of one or more observables and/or produce an event.             *
     *                                                                        *
     * ********************************************************************** */

    /**
     * Selects the given range.
     *
     * 
Caution: see {@link TextEditingArea#getAbsolutePosition(int, int)} to
     * know how the column index argument can affect the returned position.
     */
    void selectRange(int startParagraphIndex, int startColPosition, int endParagraphIndex, int endColPosition);

    /**
     * Selects the given range.
     */
    void selectRange(int startPosition, int endPosition);

    void updateStartBy(int amount, Direction direction);

    void updateEndBy(int amount, Direction direction);

    void updateStartTo(int position);

    void updateStartTo(int paragraphIndex, int columnPosition);

    void updateStartByBreaksForward(int numOfBreaks, BreakIterator breakIterator);

    void updateStartByBreaksBackward(int numOfBreaks, BreakIterator breakIterator);

    void updateEndTo(int position);

    void updateEndTo(int paragraphIndex, int columnPosition);

    void updateEndByBreaksForward(int numOfBreaks, BreakIterator breakIterator);

    void updateEndByBreaksBackward(int numOfBreaks, BreakIterator breakIterator);

    void selectAll();

    void selectParagraph(int paragraphIndex);

    void selectWord(int wordPositionInArea);

    /**
     * Clears the selection via {@code selectRange(getStartPosition(), getStartPosition())}.
     */
    default void deselect() {
        selectRange(getStartPosition(), getStartPosition());
    }

    /**
     * Configures a {@link SelectionPath} that will be used to render a portion or all of this selection
     * on a single paragraph. When the selection is a multi-paragraph selection, one path will be used
     * to render that portion of the selection on a paragraph.
     */
    void configureSelectionPath(SelectionPath path);

    /**
     * Disposes the selection and prevents memory leaks
     */
    void dispose();

    /**
     * Gets the name of this selection. Each selection in an area must have a unique name.
     */
    String getSelectionName();

    /**
     * Gets the area with which this selection is associated
     */
    GenericStyledArea getArea();

}