1 /*
2 * Copyright 2006-2016 The JGUIraffe Team.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License")
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package net.sf.jguiraffe.gui.builder.components.model;
17
18 import net.sf.jguiraffe.gui.forms.ComponentHandler;
19
20 /**
21 * <p>
22 * A specialized {@code ComponentHandler} implementation for text components.
23 * </p>
24 * <p>
25 * This handler class provides some extended functionality specific for text
26 * input components. Examples of this functionality include methods for querying
27 * or manipulating the text field's selection or support for clipboard
28 * operations. Using this handler interface applications gain more control of
29 * text components.
30 * </p>
31 *
32 * @author Oliver Heger
33 * @version $Id: TextHandler.java 205 2012-01-29 18:29:57Z oheger $
34 */
35 public interface TextHandler extends ComponentHandler<String>
36 {
37 /**
38 * Returns a flag whether the text component has a non-empty selection. If
39 * this method returns <b>true</b>, other methods can be called that operate
40 * on the selection.
41 *
42 * @return a flag whether a selection exists
43 */
44 boolean hasSelection();
45
46 /**
47 * Returns the start index of the current selection in the text field. The
48 * value returned by this method is only meaningful if
49 * {@link #hasSelection()} returns <b>true</b>.
50 *
51 * @return the start index of the selection
52 */
53 int getSelectionStart();
54
55 /**
56 * Returns the end index of the current selection in the text field. The
57 * value returned by this method is only meaningful if
58 * {@link #hasSelection()} returns <b>true</b>.
59 *
60 * @return the end index of the selection
61 */
62 int getSelectionEnd();
63
64 /**
65 * Sets the selection of the text field. The parameters passed to this
66 * method are the start index and the end index of the selection. Indices
67 * are 0-based and are related to the characters stored in the text field.
68 *
69 * @param start the start index of the selection
70 * @param end the end index of the selection
71 */
72 void select(int start, int end);
73
74 /**
75 * Selects all text contained in the text component.
76 */
77 void selectAll();
78
79 /**
80 * Clears the selection of the text component. This does not affect the text
81 * stored in the component. Only the selection is reset.
82 */
83 void clearSelection();
84
85 /**
86 * Returns the currently selected text. The result of this method is only
87 * meaningful if a selection exists, i.e. if {@link #hasSelection()} returns
88 * <b>true</b>.
89 *
90 * @return the selected text
91 */
92 String getSelectedText();
93
94 /**
95 * Replaces the text currently selected by the specified string. If no
96 * selection exists, the specified text is inserted at the current caret
97 * position. If there is a selection, but the replacement text is
98 * <b>null</b> or empty, the selected text is removed.
99 *
100 * @param text the replacement text
101 */
102 void replaceSelectedText(String text);
103
104 /**
105 * Copies the currently selected text to the system clipboard. This is the
106 * standard edit copy action.
107 */
108 void copy();
109
110 /**
111 * Cuts the currently selected text and copies it into the system clipboard.
112 * This is the standard edit cut action.
113 */
114 void cut();
115
116 /**
117 * Pastes the content of the system clipboard into this text component. This
118 * is the standard edit paste action.
119 */
120 void paste();
121 }