DefaultFormatter


1   /*
2    * @(#)DefaultFormatter.java    1.13 04/05/05
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   package javax.swing.text;
8   
9   import java.io.Serializable  ;
10  import java.lang.reflect.*;
11  import java.text.ParseException  ;
12  import javax.swing.*;
13  import javax.swing.text.*;
14  
15  /**
16   * <code>DefaultFormatter</code> formats aribtrary objects. Formatting is done
17   * by invoking the <code>toString</code> method. In order to convert the
18   * value back to a String, your class must provide a constructor that
19   * takes a String argument. If no single argument constructor that takes a
20   * String is found, the returned value will be the String passed into
21   * <code>stringToValue</code>.
22   * <p>
23   * Instances of <code>DefaultFormatter</code> can not be used in multiple
24   * instances of <code>JFormattedTextField</code>. To obtain a copy of
25   * an already configured <code>DefaultFormatter</code>, use the
26   * <code>clone</code> method.
27   * <p>
28   * <strong>Warning:</strong>
29   * Serialized objects of this class will not be compatible with
30   * future Swing releases. The current serialization support is
31   * appropriate for short term storage or RMI between applications running
32   * the same version of Swing.  As of 1.4, support for long term storage
33   * of all JavaBeans<sup><font size="-2">TM</font></sup>
34   * has been added to the <code>java.beans</code> package.
35   * Please see {@link java.beans.XMLEncoder}.
36   *
37   * @see javax.swing.JFormattedTextField.AbstractFormatter
38   *
39   * @version 1.13 05/05/04
40   * @since 1.4
41   */
42  public class DefaultFormatter extends JFormattedTextField.AbstractFormatter
43                      implements Cloneable  , Serializable   {
44      /** Indicates if the value being edited must match the mask. */
45      private boolean allowsInvalid;
46  
47      /** If true, editing mode is in overwrite (or strikethough). */
48      private boolean overwriteMode;
49  
50      /** If true, any time a valid edit happens commitEdit is invoked. */
51      private boolean commitOnEdit;
52  
53      /** Class used to create new instances. */
54      private Class   valueClass;
55  
56      /** NavigationFilter that forwards calls back to DefaultFormatter. */
57      private NavigationFilter   navigationFilter;
58  
59      /** DocumentFilter that forwards calls back to DefaultFormatter. */
60      private DocumentFilter   documentFilter;
61  
62      /** Used during replace to track the region to replace. */
63      transient ReplaceHolder replaceHolder;
64  
65  
66      /**
67       * Creates a DefaultFormatter.
68       */
69      public DefaultFormatter() {
70          overwriteMode = true;
71          allowsInvalid = true;
72      }
73  
74      /**
75       * Installs the <code>DefaultFormatter</code> onto a particular
76       * <code>JFormattedTextField</code>.
77       * This will invoke <code>valueToString</code> to convert the
78       * current value from the <code>JFormattedTextField</code> to
79       * a String. This will then install the <code>Action</code>s from
80       * <code>getActions</code>, the <code>DocumentFilter</code>
81       * returned from <code>getDocumentFilter</code> and the
82       * <code>NavigationFilter</code> returned from
83       * <code>getNavigationFilter</code> onto the
84       * <code>JFormattedTextField</code>.
85       * <p>
86       * Subclasses will typically only need to override this if they
87       * wish to install additional listeners on the
88       * <code>JFormattedTextField</code>.
89       * <p>
90       * If there is a <code>ParseException</code> in converting the
91       * current value to a String, this will set the text to an empty
92       * String, and mark the <code>JFormattedTextField</code> as being
93       * in an invalid state.
94       * <p>
95       * While this is a public method, this is typically only useful
96       * for subclassers of <code>JFormattedTextField</code>.
97       * <code>JFormattedTextField</code> will invoke this method at
98       * the appropriate times when the value changes, or its internal
99       * state changes.
100      *
101      * @param ftf JFormattedTextField to format for, may be null indicating
102      *            uninstall from current JFormattedTextField.
103      */
104     public void install(JFormattedTextField ftf) {
105         super.install(ftf);
106         positionCursorAtInitialLocation();
107     }
108 
109     /**
110      * Sets when edits are published back to the
111      * <code>JFormattedTextField</code>. If true, <code>commitEdit</code>
112      * is invoked after every valid edit (any time the text is edited). On
113      * the other hand, if this is false than the <code>DefaultFormatter</code>
114      * does not publish edits back to the <code>JFormattedTextField</code>.
115      * As such, the only time the value of the <code>JFormattedTextField</code>
116      * will change is when <code>commitEdit</code> is invoked on
117      * <code>JFormattedTextField</code>, typically when enter is pressed
118      * or focus leaves the <code>JFormattedTextField</code>.
119      *
120      * @param commit Used to indicate when edits are commited back to the
121      *               JTextComponent
122      */
123     public void setCommitsOnValidEdit(boolean commit) {
124         commitOnEdit = commit;
125     }
126 
127     /**
128      * Returns when edits are published back to the
129      * <code>JFormattedTextField</code>.
130      *
131      * @return true if edits are commited after evey valid edit
132      */
133     public boolean getCommitsOnValidEdit() {
134         return commitOnEdit;
135     }
136 
137     /**
138      * Configures the behavior when inserting characters. If
139      * <code>overwriteMode</code> is true (the default), new characters
140      * overwrite existing characters in the model.
141      *
142      * @param overwriteMode Indicates if overwrite or overstrike mode is used
143      */
144     public void setOverwriteMode(boolean overwriteMode) {
145         this.overwriteMode = overwriteMode;
146     }
147 
148     /**
149      * Returns the behavior when inserting characters.
150      *
151      * @return true if newly inserted characters overwrite existing characters
152      */
153     public boolean getOverwriteMode() {
154         return overwriteMode;
155     }
156 
157     /**
158      * Sets whether or not the value being edited is allowed to be invalid
159      * for a length of time (that is, <code>stringToValue</code> throws
160      * a <code>ParseException</code>).
161      * It is often convenient to allow the user to temporarily input an
162      * invalid value.
163      *
164      * @param allowsInvalid Used to indicate if the edited value must always
165      *        be valid
166      */
167     public void setAllowsInvalid(boolean allowsInvalid) {
168         this.allowsInvalid = allowsInvalid;
169     }
170 
171     /**
172      * Returns whether or not the value being edited is allowed to be invalid
173      * for a length of time.
174      *
175      * @return false if the edited value must always be valid
176      */
177     public boolean getAllowsInvalid() {
178         return allowsInvalid;
179     }
180 
181     /**
182      * Sets that class that is used to create new Objects. If the 
183      * passed in class does not have a single argument constructor that
184      * takes a String, String values will be used.
185      *
186      * @param valueClass Class used to construct return value from
187      *        stringToValue
188      */
189     public void setValueClass(Class  <?> valueClass) {
190         this.valueClass = valueClass;
191     }
192 
193     /**
194      * Returns that class that is used to create new Objects.
195      *
196      * @return Class used to constuct return value from stringToValue
197      */
198     public Class  <?> getValueClass() {
199         return valueClass;
200     }
201 
202     /**
203      * Converts the passed in String into an instance of
204      * <code>getValueClass</code> by way of the constructor that
205      * takes a String argument. If <code>getValueClass</code> 
206      * returns null, the Class of the current value in the
207      * <code>JFormattedTextField</code> will be used. If this is null, a
208      * String will be returned. If the constructor thows an exception, a
209      * <code>ParseException</code> will be thrown. If there is no single
210      * argument String constructor, <code>string</code> will be returned.
211      *
212      * @throws ParseException if there is an error in the conversion
213      * @param string String to convert
214      * @return Object representation of text
215      */
216     public Object   stringToValue(String   string) throws ParseException   {
217         Class   vc = getValueClass();
218         JFormattedTextField ftf = getFormattedTextField();
219 
220         if (vc == null && ftf != null) {
221             Object   value = ftf.getValue();
222 
223             if (value != null) {
224                 vc = value.getClass();
225             }
226         }
227         if (vc != null) {
228             Constructor cons;
229 
230             try {
231                 cons = vc.getConstructor(new Class  [] { String  .class });
232 
233             } catch (NoSuchMethodException   nsme) {
234                 cons = null;
235             }
236 
237             if (cons != null) {
238                 try {
239                     return cons.newInstance(new Object  [] { string });
240                 } catch (Throwable   ex) {
241                     throw new ParseException  ("Error creating instance", 0);
242                 }
243             }
244         }
245         return string;
246     }
247 
248     /**
249      * Converts the passed in Object into a String by way of the 
250      * <code>toString</code> method.
251      *
252      * @throws ParseException if there is an error in the conversion
253      * @param value Value to convert
254      * @return String representation of value
255      */
256     public String   valueToString(Object   value) throws ParseException   {
257         if (value == null) {
258             return "";
259         }
260         return value.toString();
261     }
262 
263     /**
264      * Returns the <code>DocumentFilter</code> used to restrict the characters
265      * that can be input into the <code>JFormattedTextField</code>.
266      *
267      * @return DocumentFilter to restrict edits
268      */
269     protected DocumentFilter   getDocumentFilter() {
270         if (documentFilter == null) {
271             documentFilter = new DefaultDocumentFilter();
272         }
273         return documentFilter;
274     }
275 
276     /**
277      * Returns the <code>NavigationFilter</code> used to restrict where the
278      * cursor can be placed.
279      *
280      * @return NavigationFilter to restrict navigation
281      */
282     protected NavigationFilter   getNavigationFilter() {
283         if (navigationFilter == null) {
284             navigationFilter = new DefaultNavigationFilter();
285         }
286         return navigationFilter;
287     }
288 
289     /**
290      * Creates a copy of the DefaultFormatter.
291      *
292      * @return copy of the DefaultFormatter
293      */
294     public Object   clone() throws CloneNotSupportedException   {
295         DefaultFormatter   formatter = (DefaultFormatter  )super.clone();
296 
297         formatter.navigationFilter = null;
298         formatter.documentFilter = null;
299         formatter.replaceHolder = null;
300         return formatter;
301     }
302 
303 
304     /**
305      * Positions the cursor at the initial location.
306      */
307     void positionCursorAtInitialLocation() {
308         JFormattedTextField ftf = getFormattedTextField();
309         if (ftf != null) {
310             ftf.setCaretPosition(getInitialVisualPosition());
311         }
312     }
313 
314     /**
315      * Returns the initial location to position the cursor at. This forwards
316      * the call to <code>getNextNavigatableChar</code>.
317      */
318     int getInitialVisualPosition() {
319         return getNextNavigatableChar(0, 1);
320     }
321 
322     /**
323      * Subclasses should override this if they want cursor navigation
324      * to skip certain characters. A return value of false indicates
325      * the character at <code>offset</code> should be skipped when
326      * navigating throught the field.
327      */
328     boolean isNavigatable(int offset) {
329         return true;
330     }
331 
332     /**
333      * Returns true if the text in <code>text</code> can be inserted.  This
334      * does not mean the text will ultimately be inserted, it is used if
335      * text can trivially reject certain characters.
336      */
337     boolean isLegalInsertText(String   text) {
338         return true;
339     }
340 
341     /**
342      * Returns the next editable character starting at offset incrementing
343      * the offset by <code>direction</code>.
344      */
345     private int getNextNavigatableChar(int offset, int direction) {
346         int max = getFormattedTextField().getDocument().getLength();
347 
348         while (offset >= 0 && offset < max) {
349             if (isNavigatable(offset)) {
350                 return offset;
351             }
352             offset += direction;
353         }
354         return offset;
355     }
356 
357     /**
358      * A convenience methods to return the result of deleting
359      * <code>deleteLength</code> characters at <code>offset</code>
360      * and inserting <code>replaceString</code> at <code>offset</code>
361      * in the current text field.
362      */
363     String   getReplaceString(int offset, int deleteLength,
364                             String   replaceString) {
365         String   string = getFormattedTextField().getText();
366         String   result;
367 
368         result = string.substring(0, offset);
369         if (replaceString != null) {
370             result += replaceString;
371         }
372         if (offset + deleteLength < string.length()) {
373             result += string.substring(offset + deleteLength);
374         }
375         return result;
376     }
377 
378     /*
379      * Returns true if the operation described by <code>rh</code> will
380      * result in a legal edit.  This may set the <code>value</code>
381      * field of <code>rh</code>.
382      */
383     boolean isValidEdit(ReplaceHolder rh) {
384         if (!getAllowsInvalid()) {
385             String   newString = getReplaceString(rh.offset, rh.length, rh.text);
386 
387             try {
388                 rh.value = stringToValue(newString);
389 
390                 return true;
391             } catch (ParseException   pe) {
392                 return false;
393             }
394         }
395         return true;
396     }
397 
398     /**
399      * Invokes <code>commitEdit</code> on the JFormattedTextField.
400      */
401     void commitEdit() throws ParseException   {
402         JFormattedTextField ftf = getFormattedTextField();
403 
404         if (ftf != null) {
405             ftf.commitEdit();
406         }
407     }
408 
409     /**
410      * Pushes the value to the JFormattedTextField if the current value
411      * is valid and invokes <code>setEditValid</code> based on the
412      * validity of the value.
413      */
414     void updateValue() {
415         updateValue(null);
416     }
417 
418     /**
419      * Pushes the <code>value</code> to the editor if we are to
420      * commit on edits. If <code>value</code> is null, the current value
421      * will be obtained from the text component.
422      */
423     void updateValue(Object   value) {
424         try {
425             if (value == null) {
426                 String   string = getFormattedTextField().getText();
427 
428                 value = stringToValue(string);
429             }
430 
431             if (getCommitsOnValidEdit()) {
432                 commitEdit();
433             }
434             setEditValid(true);
435         } catch (ParseException   pe) {
436             setEditValid(false);
437         }
438     }
439 
440     /**
441      * Returns the next cursor position from offset by incrementing
442      * <code>direction</code>. This uses
443      * <code>getNextNavigatableChar</code>
444      * as well as constraining the location to the max position.
445      */
446     int getNextCursorPosition(int offset, int direction) {
447         int newOffset = getNextNavigatableChar(offset, direction);
448         int max = getFormattedTextField().getDocument().getLength();
449 
450         if (!getAllowsInvalid()) {
451             if (direction == -1 && offset == newOffset) {
452                 // Case where hit backspace and only characters before
453                 // offset are fixed.
454                 newOffset = getNextNavigatableChar(newOffset, 1);
455                 if (newOffset >= max) {
456                     newOffset = offset;
457                 }
458             }
459             else if (direction == 1 && newOffset >= max) {
460                 // Don't go beyond last editable character.
461                 newOffset = getNextNavigatableChar(max - 1, -1);
462                 if (newOffset < max) {
463                     newOffset++;
464                 }
465             }
466         }
467         return newOffset;
468     }
469 
470     /**
471      * Resets the cursor by using getNextCursorPosition.
472      */
473     void repositionCursor(int offset, int direction) {
474         getFormattedTextField().getCaret().setDot(getNextCursorPosition
475                                                   (offset, direction));
476     }
477 
478 
479     /**
480      * Finds the next navigatable character.
481      */
482     int getNextVisualPositionFrom(JTextComponent   text, int pos,
483                                   Position.Bias   bias, int direction,
484                                   Position.Bias  [] biasRet)
485                                            throws BadLocationException   {
486         int value = text.getUI().getNextVisualPositionFrom(text, pos, bias,
487                                                            direction, biasRet);
488 
489         if (value == -1) {
490             return -1;
491         }
492         if (!getAllowsInvalid() && (direction == SwingConstants.EAST ||
493                                     direction == SwingConstants.WEST)) {
494             int last = -1;
495 
496             while (!isNavigatable(value) && value != last) {
497                 last = value;
498                 value = text.getUI().getNextVisualPositionFrom(
499                               text, value, bias, direction,biasRet);
500             }
501             int max = getFormattedTextField().getDocument().getLength();
502             if (last == value || value == max) {
503                 if (value == 0) {
504                     biasRet[0] = Position.Bias.Forward;
505                     value = getInitialVisualPosition();
506                 }
507                 if (value >= max && max > 0) {
508                     // Pending: should not assume forward!
509                     biasRet[0] = Position.Bias.Forward;
510                     value = getNextNavigatableChar(max - 1, -1) + 1;
511                 }
512             }
513         }
514         return value;
515     }
516 
517     /**
518      * Returns true if the edit described by <code>rh</code> will result
519      * in a legal value.
520      */
521     boolean canReplace(ReplaceHolder rh) {
522         return isValidEdit(rh);
523     }
524 
525     /**
526      * DocumentFilter method, funnels into <code>replace</code>.
527      */
528     void replace(DocumentFilter.FilterBypass   fb, int offset,
529                      int length, String   text,
530                      AttributeSet   attrs) throws BadLocationException   {
531         ReplaceHolder rh = getReplaceHolder(fb, offset, length, text, attrs);
532 
533         replace(rh);
534     }
535 
536     /**
537      * If the edit described by <code>rh</code> is legal, this will
538      * return true, commit the edit (if necessary) and update the cursor
539      * position.  This forwards to <code>canReplace</code> and
540      * <code>isLegalInsertText</code> as necessary to determine if
541      * the edit is in fact legal.
542      * <p>
543      * All of the DocumentFilter methods funnel into here, you should
544      * generally only have to override this.
545      */
546     boolean replace(ReplaceHolder rh) throws BadLocationException   {
547         boolean valid = true;
548         int direction = 1;
549 
550         if (rh.length > 0 && (rh.text == null || rh.text.length() == 0) &&
551                (getFormattedTextField().getSelectionStart() != rh.offset ||
552                    rh.length > 1)) {
553             direction = -1;
554         }
555 
556         if (getOverwriteMode() && rh.text != null) {
557             rh.length = Math.min(Math.max(rh.length, rh.text.length()),
558                                  rh.fb.getDocument().getLength() - rh.offset);
559         }
560         if ((rh.text != null && !isLegalInsertText(rh.text)) ||
561             !canReplace(rh) ||
562             (rh.length == 0 && (rh.text == null || rh.text.length() == 0))) {
563             valid = false;
564         }
565         if (valid) {
566             int cursor = rh.cursorPosition;
567 
568             rh.fb.replace(rh.offset, rh.length, rh.text, rh.attrs);
569             if (cursor == -1) {
570                 cursor = rh.offset;
571                 if (direction == 1 && rh.text != null) {
572                     cursor = rh.offset + rh.text.length();
573                 }
574             }
575             updateValue(rh.value);
576             repositionCursor(cursor, direction);
577             return true;
578         }
579         else {
580             invalidEdit();
581         }
582         return false;
583     }
584 
585     /**
586      * NavigationFilter method, subclasses that wish finer control should
587      * override this.
588      */
589     void setDot(NavigationFilter.FilterBypass   fb, int dot, Position.Bias   bias){
590         fb.setDot(dot, bias);
591     }
592 
593     /**
594      * NavigationFilter method, subclasses that wish finer control should
595      * override this.
596      */
597     void moveDot(NavigationFilter.FilterBypass   fb, int dot,
598                  Position.Bias   bias) {
599         fb.moveDot(dot, bias);
600     }
601 
602 
603     /**
604      * Returns the ReplaceHolder to track the replace of the specified
605      * text.
606      */
607     ReplaceHolder getReplaceHolder(DocumentFilter.FilterBypass   fb, int offset,
608                                    int length, String   text,
609                                    AttributeSet   attrs) {
610         if (replaceHolder == null) {
611             replaceHolder = new ReplaceHolder();
612         }
613         replaceHolder.reset(fb, offset, length, text, attrs);
614         return replaceHolder;
615     }
616 
617 
618     /**
619      * ReplaceHolder is used to track where insert/remove/replace is
620      * going to happen.
621      */
622     static class ReplaceHolder {
623         /** The FilterBypass that was passed to the DocumentFilter method. */
624         DocumentFilter.FilterBypass   fb;
625         /** Offset where the remove/insert is going to occur. */
626         int offset;
627         /** Length of text to remove. */
628         int length;
629         /** The text to insert, may be null. */
630         String   text;
631         /** AttributeSet to attach to text, may be null. */
632         AttributeSet   attrs;
633         /** The resulting value, this may never be set. */
634         Object   value;
635         /** Position the cursor should be adjusted from.  If this is -1
636          * the cursor position will be adjusted based on the direction of
637          * the replace (-1: offset, 1: offset + text.length()), otherwise
638          * the cursor position is adusted from this position.
639          */
640         int cursorPosition;
641 
642         void reset(DocumentFilter.FilterBypass   fb, int offset, int length,
643                    String   text, AttributeSet   attrs) {
644             this.fb = fb;
645             this.offset = offset;
646             this.length = length;
647             this.text = text;
648             this.attrs = attrs;
649             this.value = null;
650             cursorPosition = -1;
651         }
652     }
653 
654 
655     /**
656      * NavigationFilter implementation that calls back to methods with
657      * same name in DefaultFormatter.
658      */
659     private class DefaultNavigationFilter extends NavigationFilter  
660                              implements Serializable   {
661         public void setDot(FilterBypass fb, int dot, Position.Bias   bias) {
662         JTextComponent   tc = DefaultFormatter.this.getFormattedTextField();
663             if (tc.composedTextExists()) {
664         // bypass the filter
665                 fb.setDot(dot, bias);
666         } else {
667                 DefaultFormatter.this.setDot(fb, dot, bias);
668         }
669         }
670 
671         public void moveDot(FilterBypass fb, int dot, Position.Bias   bias) {
672         JTextComponent   tc = DefaultFormatter.this.getFormattedTextField();
673             if (tc.composedTextExists()) {
674         // bypass the filter
675                 fb.moveDot(dot, bias);
676         } else {
677                 DefaultFormatter.this.moveDot(fb, dot, bias);
678         }
679         }
680 
681         public int getNextVisualPositionFrom(JTextComponent   text, int pos,
682                                              Position.Bias   bias,
683                                              int direction,
684                                              Position.Bias  [] biasRet)
685                                            throws BadLocationException   {
686             if (text.composedTextExists()) {
687         // forward the call to the UI directly
688         return text.getUI().getNextVisualPositionFrom(
689             text, pos, bias, direction, biasRet);
690         } else {
691         return DefaultFormatter.this.getNextVisualPositionFrom(
692             text, pos, bias, direction, biasRet);
693         }
694         }
695     }
696 
697 
698     /**
699      * DocumentFilter implementation that calls back to the replace
700      * method of DefaultFormatter.
701      */
702     private class DefaultDocumentFilter extends DocumentFilter   implements
703                              Serializable   {
704         public void remove(FilterBypass fb, int offset, int length) throws
705                               BadLocationException   {
706         JTextComponent   tc = DefaultFormatter.this.getFormattedTextField();
707         if (tc.composedTextExists()) {
708         // bypass the filter
709         fb.remove(offset, length);
710         } else {
711         DefaultFormatter.this.replace(fb, offset, length, null, null);
712         }
713         }
714 
715         public void insertString(FilterBypass fb, int offset,
716                                  String   string, AttributeSet   attr) throws
717                               BadLocationException   {
718         JTextComponent   tc = DefaultFormatter.this.getFormattedTextField();
719         if (tc.composedTextExists() || 
720         Utilities.isComposedTextAttributeDefined(attr)) {
721         // bypass the filter
722         fb.insertString(offset, string, attr);
723         } else {
724         DefaultFormatter.this.replace(fb, offset, 0, string, attr);
725         }
726         }
727 
728         public void replace(FilterBypass fb, int offset, int length,
729                                  String   text, AttributeSet   attr) throws
730                               BadLocationException   {
731         JTextComponent   tc = DefaultFormatter.this.getFormattedTextField();
732         if (tc.composedTextExists() || 
733         Utilities.isComposedTextAttributeDefined(attr)) {
734         // bypass the filter
735         fb.replace(offset, length, text, attr);
736         } else {
737         DefaultFormatter.this.replace(fb, offset, length, text, attr);
738         }
739         }
740     }
741 }
742
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags