RichTextArea


1   /*
2    * Copyright 2007 Google Inc.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License"); you may not
5    * use this file except in compliance with the License. You may obtain a copy of
6    * 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, WITHOUT
12   * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13   * License for the specific language governing permissions and limitations under
14   * the License.
15   */
16  package com.google.gwt.user.client.ui;
17  
18  import com.google.gwt.core.client.GWT;
19  import com.google.gwt.user.client.DOM;
20  import com.google.gwt.user.client.Event;
21  import com.google.gwt.user.client.ui.impl.RichTextAreaImpl;
22  
23  /**
24   * A rich text editor that allows complex styling and formatting.
25   * 
26   * Because some browsers do not support rich text editing, and others support
27   * only a limited subset of functionality, there are two formatter interfaces,
28   * accessed via {@link #getBasicFormatter()} and {@link #getExtendedFormatter()}.
29   * A browser that does not support rich text editing at all will return
30   * <code>null</code> for both of these, while one that supports only the basic
31   * functionality will return <code>null</code> for the latter.
32   * 
33   * <p>
34   * <img class='gallery' SRC='RichTextArea.png'/>
35   * </p>
36   * 
37   * <h3>CSS Style Rules</h3>
38   * <ul class="css">
39   * <li>.gwt-RichTextArea { }</li>
40   * </ul>
41   */
42  public class RichTextArea extends FocusWidget implements HasHTML,
43      SourcesMouseEvents {
44  
45    /**
46     * This interface is used to access basic formatting options, when available.
47     * If the implementation supports basic formatting, then
48     * {@link RichTextArea#getBasicFormatter()} will return an instance of this
49     * class.
50     */
51    public interface BasicFormatter {
52  
53      /**
54       * Gets the background color.
55       * 
56       * @return the background color
57       */
58      String   getBackColor();
59  
60      /**
61       * Gets the foreground color.
62       * 
63       * @return the foreground color
64       */
65      String   getForeColor();
66  
67      /**
68       * Is the current region bold?
69       * 
70       * @return true if the current region is bold
71       */
72      boolean isBold();
73  
74      /**
75       * Is the current region italic?
76       * 
77       * @return true if the current region is italic
78       */
79      boolean isItalic();
80  
81      /**
82       * Is the current region subscript?
83       * 
84       * @return true if the current region is subscript
85       */
86      boolean isSubscript();
87  
88      /**
89       * Is the current region superscript?
90       * 
91       * @return true if the current region is superscript
92       */
93      boolean isSuperscript();
94  
95      /**
96       * Is the current region underlined?
97       * 
98       * @return true if the current region is underlined
99       */
100     boolean isUnderlined();
101 
102     /**
103      * Selects all the text.
104      */
105     void selectAll();
106 
107     /**
108      * Sets the background color.
109      * 
110      * @param color the new background color
111      */
112     void setBackColor(String   color);
113 
114     /**
115      * Sets the font name.
116      * 
117      * @param name the new font name
118      */
119     void setFontName(String   name);
120 
121     /**
122      * Sets the font size.
123      * 
124      * @param fontSize the new font size
125      */
126     void setFontSize(FontSize fontSize);
127 
128     /**
129      * Sets the foreground color.
130      * 
131      * @param color the new foreground color
132      */
133     void setForeColor(String   color);
134 
135     /**
136      * Sets the justification.
137      * 
138      * @param justification the new justification
139      */
140     void setJustification(Justification justification);
141 
142     /**
143      * Toggles bold.
144      */
145     void toggleBold();
146 
147     /**
148      * Toggles italic.
149      */
150     void toggleItalic();
151 
152     /**
153      * Toggles subscript.
154      */
155     void toggleSubscript();
156 
157     /**
158      * Toggles superscript.
159      */
160     void toggleSuperscript();
161 
162     /**
163      * Toggles underline.
164      */
165     void toggleUnderline();
166   }
167 
168   /**
169    * This interface is used to access full formatting options, when available.
170    * If the implementation supports full formatting, then
171    * {@link RichTextArea#getExtendedFormatter()} will return an instance of this
172    * class.
173    */
174   public interface ExtendedFormatter extends BasicFormatter {
175 
176     /**
177      * Creates a link to the supplied URL.
178      * 
179      * @param url the URL to be linked to
180      */
181     void createLink(String   url);
182 
183     /**
184      * Inserts a horizontal rule.
185      */
186     void insertHorizontalRule();
187 
188     /**
189      * Inserts an image element.
190      * 
191      * @param url the url of the image to be inserted
192      */
193     void insertImage(String   url);
194 
195     /**
196      * Starts an numbered list. Indentation will create nested items.
197      */
198     void insertOrderedList();
199 
200     /**
201      * Starts an bulleted list. Indentation will create nested items.
202      */
203     void insertUnorderedList();
204 
205     /**
206      * Is the current region strikethrough?
207      * 
208      * @return true if the current region is strikethrough
209      */
210     boolean isStrikethrough();
211 
212     /**
213      * Left indent.
214      */
215     void leftIndent();
216 
217     /**
218      * Removes all formatting on the selected text.
219      */
220     void removeFormat();
221 
222     /**
223      * Removes any link from the selected text.
224      */
225     void removeLink();
226 
227     /**
228      * Right indent.
229      */
230     void rightIndent();
231 
232     /**
233      * Toggles strikethrough.
234      */
235     void toggleStrikethrough();
236   }
237 
238   /**
239    * Font size enumeration. Represents the seven basic HTML font sizes, as
240    * defined in CSS.
241    */
242   public static class FontSize {
243 
244     /**
245      * Represents an XX-Small font.
246      */
247     public static final FontSize XX_SMALL = new FontSize(1);
248 
249     /**
250      * Represents an X-Small font.
251      */
252     public static final FontSize X_SMALL = new FontSize(2);
253 
254     /**
255      * Represents a Small font.
256      */
257     public static final FontSize SMALL = new FontSize(3);
258 
259     /**
260      * Represents a Medium font.
261      */
262     public static final FontSize MEDIUM = new FontSize(4);
263 
264     /**
265      * Represents a Large font.
266      */
267     public static final FontSize LARGE = new FontSize(5);
268 
269     /**
270      * Represents an X-Large font.
271      */
272     public static final FontSize X_LARGE = new FontSize(6);
273 
274     /**
275      * Represents an XX-Large font.
276      */
277     public static final FontSize XX_LARGE = new FontSize(7);
278 
279     private int number;
280 
281     private FontSize(int number) {
282       this.number = number;
283     }
284 
285     /**
286      * Gets the HTML font number associated with this font size.
287      * 
288      * @return an integer from 1 to 7 inclusive
289      */
290     public int getNumber() {
291       return number;
292     }
293   }
294 
295   /**
296    * Justification enumeration. The three values are <code>left</code>,
297    * <code>right</code>, <code>center</code>.
298    */
299   public static class Justification {
300 
301     /**
302      * Center justification.
303      */
304     public static final Justification CENTER = new Justification("Center");
305 
306     /**
307      * Left justification.
308      */
309     public static final Justification LEFT = new Justification("Left");
310 
311     /**
312      * Right justification.
313      */
314     public static final Justification RIGHT = new Justification("Right");
315 
316     private String   tag;
317 
318     private Justification(String   tag) {
319       this.tag = tag;
320     }
321 
322     public String   toString() {
323       return "Justify " + tag;
324     }
325   }
326 
327   private RichTextAreaImpl impl = (RichTextAreaImpl) GWT.create(RichTextAreaImpl.class);
328   private MouseListenerCollection mouseListeners;
329 
330   /**
331    * Creates a new, blank {@link RichTextArea} object with no stylesheet.
332    */
333   public RichTextArea() {
334     setElement(impl.getElement());
335     setStyleName("gwt-RichTextArea");
336   }
337 
338   public void addMouseListener(MouseListener listener) {
339     if (mouseListeners == null) {
340       mouseListeners = new MouseListenerCollection();
341     }
342     mouseListeners.add(listener);
343   }
344 
345   /**
346    * Gets the basic rich text formatting interface.
347    * 
348    * @return <code>null</code> if basic formatting is not supported
349    */
350   public BasicFormatter getBasicFormatter() {
351     if ((impl instanceof BasicFormatter) && (impl.isBasicEditingSupported())) {
352       return (BasicFormatter) impl;
353     }
354     return null;
355   }
356 
357   /**
358    * Gets the full rich text formatting interface.
359    * 
360    * @return <code>null</code> if full formatting is not supported
361    */
362   public ExtendedFormatter getExtendedFormatter() {
363     if ((impl instanceof ExtendedFormatter)
364         && (impl.isExtendedEditingSupported())) {
365       return (ExtendedFormatter) impl;
366     }
367     return null;
368   }
369 
370   public String   getHTML() {
371     return impl.getHTML();
372   }
373 
374   public String   getText() {
375     return impl.getText();
376   }
377 
378   public void onBrowserEvent(Event event) {
379     switch (DOM.eventGetType(event)) {
380       case Event.ONMOUSEDOWN:
381       case Event.ONMOUSEUP:
382       case Event.ONMOUSEMOVE:
383       case Event.ONMOUSEOVER:
384       case Event.ONMOUSEOUT:
385         if (mouseListeners != null) {
386           mouseListeners.fireMouseEvent(this, event);
387         }
388         break;
389 
390       default:
391         // ClickEvents and KeyboardEvents
392         super.onBrowserEvent(event);
393     }
394   }
395 
396   public void removeMouseListener(MouseListener listener) {
397     if (mouseListeners != null) {
398       mouseListeners.remove(listener);
399     }
400   }
401 
402   public void setFocus(boolean focused) {
403     impl.setFocus(focused);
404   }
405 
406   public void setHTML(String   html) {
407     impl.setHTML(html);
408   }
409 
410   public void setText(String   text) {
411     impl.setText(text);
412   }
413 
414   protected void onAttach() {
415     super.onAttach();
416     impl.initElement();
417     impl.hookEvents(this);
418   }
419 
420   protected void onDetach() {
421     super.onDetach();
422     impl.unhookEvents();
423   }
424 }
425
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags