001 /* JSpinner.java -- 002 Copyright (C) 2004, 2005, 2006 Free Software Foundation, Inc. 003 004 This file is part of GNU Classpath. 005 006 GNU Classpath is free software; you can redistribute it and/or modify 007 it under the terms of the GNU General Public License as published by 008 the Free Software Foundation; either version 2, or (at your option) 009 any later version. 010 011 GNU Classpath is distributed in the hope that it will be useful, but 012 WITHOUT ANY WARRANTY; without even the implied warranty of 013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014 General Public License for more details. 015 016 You should have received a copy of the GNU General Public License 017 along with GNU Classpath; see the file COPYING. If not, write to the 018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 019 02110-1301 USA. 020 021 Linking this library statically or dynamically with other modules is 022 making a combined work based on this library. Thus, the terms and 023 conditions of the GNU General Public License cover the whole 024 combination. 025 026 As a special exception, the copyright holders of this library give you 027 permission to link this library with independent modules to produce an 028 executable, regardless of the license terms of these independent 029 modules, and to copy and distribute the resulting executable under 030 terms of your choice, provided that you also meet, for each linked 031 independent module, the terms and conditions of the license of that 032 module. An independent module is a module which is not derived from 033 or based on this library. If you modify this library, you may extend 034 this exception to your version of the library, but you are not 035 obligated to do so. If you do not wish to do so, delete this 036 exception statement from your version. */ 037 038 039 package javax.swing; 040 041 import java.awt.Component; 042 import java.awt.Container; 043 import java.awt.Dimension; 044 import java.awt.Insets; 045 import java.awt.LayoutManager; 046 import java.beans.PropertyChangeEvent; 047 import java.beans.PropertyChangeListener; 048 import java.text.DateFormat; 049 import java.text.DecimalFormat; 050 import java.text.NumberFormat; 051 import java.text.ParseException; 052 import java.text.SimpleDateFormat; 053 054 import javax.swing.event.ChangeEvent; 055 import javax.swing.event.ChangeListener; 056 import javax.swing.plaf.SpinnerUI; 057 import javax.swing.text.DateFormatter; 058 import javax.swing.text.DefaultFormatterFactory; 059 import javax.swing.text.NumberFormatter; 060 061 /** 062 * A <code>JSpinner</code> is a component that displays a single value from 063 * a sequence of values, and provides a convenient means for selecting the 064 * previous and next values in the sequence. Typically the spinner displays 065 * a numeric value, but it is possible to display dates or arbitrary items 066 * from a list. 067 * 068 * @author Ka-Hing Cheung 069 * 070 * @since 1.4 071 */ 072 public class JSpinner extends JComponent 073 { 074 /** 075 * The base class for the editor used by the {@link JSpinner} component. 076 * The editor is in fact a panel containing a {@link JFormattedTextField} 077 * component. 078 */ 079 public static class DefaultEditor 080 extends JPanel 081 implements ChangeListener, PropertyChangeListener, LayoutManager 082 { 083 /** The spinner that the editor is allocated to. */ 084 private JSpinner spinner; 085 086 /** The JFormattedTextField that backs the editor. */ 087 JFormattedTextField ftf; 088 089 /** 090 * For compatability with Sun's JDK 1.4.2 rev. 5 091 */ 092 private static final long serialVersionUID = -5317788736173368172L; 093 094 /** 095 * Creates a new <code>DefaultEditor</code> object. The editor is 096 * registered with the spinner as a {@link ChangeListener} here. 097 * 098 * @param spinner the <code>JSpinner</code> associated with this editor 099 */ 100 public DefaultEditor(JSpinner spinner) 101 { 102 super(); 103 setLayout(this); 104 this.spinner = spinner; 105 ftf = new JFormattedTextField(); 106 add(ftf); 107 ftf.setValue(spinner.getValue()); 108 ftf.addPropertyChangeListener(this); 109 if (getComponentOrientation().isLeftToRight()) 110 ftf.setHorizontalAlignment(JTextField.RIGHT); 111 else 112 ftf.setHorizontalAlignment(JTextField.LEFT); 113 spinner.addChangeListener(this); 114 } 115 116 /** 117 * Returns the <code>JSpinner</code> component that the editor is assigned 118 * to. 119 * 120 * @return The spinner that the editor is assigned to. 121 */ 122 public JSpinner getSpinner() 123 { 124 return spinner; 125 } 126 127 /** 128 * DOCUMENT ME! 129 */ 130 public void commitEdit() throws ParseException 131 { 132 // TODO: Implement this properly. 133 } 134 135 /** 136 * Removes the editor from the {@link ChangeListener} list maintained by 137 * the specified <code>spinner</code>. 138 * 139 * @param spinner the spinner (<code>null</code> not permitted). 140 */ 141 public void dismiss(JSpinner spinner) 142 { 143 spinner.removeChangeListener(this); 144 } 145 146 /** 147 * Returns the text field used to display and edit the current value in 148 * the spinner. 149 * 150 * @return The text field. 151 */ 152 public JFormattedTextField getTextField() 153 { 154 return ftf; 155 } 156 157 /** 158 * Sets the bounds for the child components in this container. In this 159 * case, the text field is the only component to be laid out. 160 * 161 * @param parent the parent container. 162 */ 163 public void layoutContainer(Container parent) 164 { 165 Insets insets = getInsets(); 166 Dimension size = getSize(); 167 ftf.setBounds(insets.left, insets.top, 168 size.width - insets.left - insets.right, 169 size.height - insets.top - insets.bottom); 170 } 171 172 /** 173 * Calculates the minimum size for this component. In this case, the 174 * text field is the only subcomponent, so the return value is the minimum 175 * size of the text field plus the insets of this component. 176 * 177 * @param parent the parent container. 178 * 179 * @return The minimum size. 180 */ 181 public Dimension minimumLayoutSize(Container parent) 182 { 183 Insets insets = getInsets(); 184 Dimension minSize = ftf.getMinimumSize(); 185 return new Dimension(minSize.width + insets.left + insets.right, 186 minSize.height + insets.top + insets.bottom); 187 } 188 189 /** 190 * Calculates the preferred size for this component. In this case, the 191 * text field is the only subcomponent, so the return value is the 192 * preferred size of the text field plus the insets of this component. 193 * 194 * @param parent the parent container. 195 * 196 * @return The preferred size. 197 */ 198 public Dimension preferredLayoutSize(Container parent) 199 { 200 Insets insets = getInsets(); 201 Dimension prefSize = ftf.getPreferredSize(); 202 return new Dimension(prefSize.width + insets.left + insets.right, 203 prefSize.height + insets.top + insets.bottom); 204 } 205 206 /** 207 * Receives notification of property changes. If the text field's 'value' 208 * property changes, the spinner's model is updated accordingly. 209 * 210 * @param event the event. 211 */ 212 public void propertyChange(PropertyChangeEvent event) 213 { 214 if (event.getSource() == ftf) 215 { 216 if (event.getPropertyName().equals("value")) 217 spinner.getModel().setValue(event.getNewValue()); 218 } 219 } 220 221 /** 222 * Receives notification of changes in the state of the {@link JSpinner} 223 * that the editor belongs to - the content of the text field is updated 224 * accordingly. 225 * 226 * @param event the change event. 227 */ 228 public void stateChanged(ChangeEvent event) 229 { 230 ftf.setValue(spinner.getValue()); 231 } 232 233 /** 234 * This method does nothing. It is required by the {@link LayoutManager} 235 * interface, but since this component has a single child, there is no 236 * need to use this method. 237 * 238 * @param child the child component to remove. 239 */ 240 public void removeLayoutComponent(Component child) 241 { 242 // Nothing to do here. 243 } 244 245 /** 246 * This method does nothing. It is required by the {@link LayoutManager} 247 * interface, but since this component has a single child, there is no 248 * need to use this method. 249 * 250 * @param name the name. 251 * @param child the child component to add. 252 */ 253 public void addLayoutComponent(String name, Component child) 254 { 255 // Nothing to do here. 256 } 257 } 258 259 /** 260 * A panel containing a {@link JFormattedTextField} that is configured for 261 * displaying and editing numbers. The panel is used as a subcomponent of 262 * a {@link JSpinner}. 263 * 264 * @see JSpinner#createEditor(SpinnerModel) 265 */ 266 public static class NumberEditor extends DefaultEditor 267 { 268 /** 269 * For compatability with Sun's JDK 270 */ 271 private static final long serialVersionUID = 3791956183098282942L; 272 273 /** 274 * Creates a new <code>NumberEditor</code> object for the specified 275 * <code>spinner</code>. The editor is registered with the spinner as a 276 * {@link ChangeListener}. 277 * 278 * @param spinner the component the editor will be used with. 279 */ 280 public NumberEditor(JSpinner spinner) 281 { 282 super(spinner); 283 NumberEditorFormatter nef = new NumberEditorFormatter(); 284 nef.setMinimum(getModel().getMinimum()); 285 nef.setMaximum(getModel().getMaximum()); 286 ftf.setFormatterFactory(new DefaultFormatterFactory(nef)); 287 } 288 289 /** 290 * Creates a new <code>NumberEditor</code> object. 291 * 292 * @param spinner the spinner. 293 * @param decimalFormatPattern the number format pattern. 294 */ 295 public NumberEditor(JSpinner spinner, String decimalFormatPattern) 296 { 297 super(spinner); 298 NumberEditorFormatter nef 299 = new NumberEditorFormatter(decimalFormatPattern); 300 nef.setMinimum(getModel().getMinimum()); 301 nef.setMaximum(getModel().getMaximum()); 302 ftf.setFormatterFactory(new DefaultFormatterFactory(nef)); 303 } 304 305 /** 306 * Returns the format used by the text field. 307 * 308 * @return The format used by the text field. 309 */ 310 public DecimalFormat getFormat() 311 { 312 NumberFormatter formatter = (NumberFormatter) ftf.getFormatter(); 313 return (DecimalFormat) formatter.getFormat(); 314 } 315 316 /** 317 * Returns the model used by the editor's {@link JSpinner} component, 318 * cast to a {@link SpinnerNumberModel}. 319 * 320 * @return The model. 321 */ 322 public SpinnerNumberModel getModel() 323 { 324 return (SpinnerNumberModel) getSpinner().getModel(); 325 } 326 } 327 328 static class NumberEditorFormatter 329 extends NumberFormatter 330 { 331 public NumberEditorFormatter() 332 { 333 super(NumberFormat.getInstance()); 334 } 335 public NumberEditorFormatter(String decimalFormatPattern) 336 { 337 super(new DecimalFormat(decimalFormatPattern)); 338 } 339 } 340 341 /** 342 * A <code>JSpinner</code> editor used for the {@link SpinnerListModel}. 343 * This editor uses a <code>JFormattedTextField</code> to edit the values 344 * of the spinner. 345 * 346 * @author Roman Kennke (kennke@aicas.com) 347 */ 348 public static class ListEditor extends DefaultEditor 349 { 350 /** 351 * Creates a new instance of <code>ListEditor</code>. 352 * 353 * @param spinner the spinner for which this editor is used 354 */ 355 public ListEditor(JSpinner spinner) 356 { 357 super(spinner); 358 } 359 360 /** 361 * Returns the spinner's model cast as a {@link SpinnerListModel}. 362 * 363 * @return The spinner's model. 364 */ 365 public SpinnerListModel getModel() 366 { 367 return (SpinnerListModel) getSpinner().getModel(); 368 } 369 } 370 371 /** 372 * An editor class for a <code>JSpinner</code> that is used 373 * for displaying and editing dates (e.g. that uses 374 * <code>SpinnerDateModel</code> as model). 375 * 376 * The editor uses a {@link JTextField} with the value 377 * displayed by a {@link DateFormatter} instance. 378 */ 379 public static class DateEditor extends DefaultEditor 380 { 381 382 /** The serialVersionUID. */ 383 private static final long serialVersionUID = -4279356973770397815L; 384 385 /** 386 * Creates a new instance of DateEditor for the specified 387 * <code>JSpinner</code>. 388 * 389 * @param spinner the <code>JSpinner</code> for which to 390 * create a <code>DateEditor</code> instance 391 */ 392 public DateEditor(JSpinner spinner) 393 { 394 super(spinner); 395 DateEditorFormatter nef = new DateEditorFormatter(); 396 nef.setMinimum(getModel().getStart()); 397 nef.setMaximum(getModel().getEnd()); 398 ftf.setFormatterFactory(new DefaultFormatterFactory(nef)); 399 } 400 401 /** 402 * Creates a new instance of DateEditor for the specified 403 * <code>JSpinner</code> using the specified date format 404 * pattern. 405 * 406 * @param spinner the <code>JSpinner</code> for which to 407 * create a <code>DateEditor</code> instance 408 * @param dateFormatPattern the date format to use 409 * 410 * @see SimpleDateFormat#SimpleDateFormat(String) 411 */ 412 public DateEditor(JSpinner spinner, String dateFormatPattern) 413 { 414 super(spinner); 415 DateEditorFormatter nef = new DateEditorFormatter(dateFormatPattern); 416 nef.setMinimum(getModel().getStart()); 417 nef.setMaximum(getModel().getEnd()); 418 ftf.setFormatterFactory(new DefaultFormatterFactory(nef)); 419 } 420 421 /** 422 * Returns the <code>SimpleDateFormat</code> instance that is used to 423 * format the date value. 424 * 425 * @return the <code>SimpleDateFormat</code> instance that is used to 426 * format the date value 427 */ 428 public SimpleDateFormat getFormat() 429 { 430 DateFormatter formatter = (DateFormatter) ftf.getFormatter(); 431 return (SimpleDateFormat) formatter.getFormat(); 432 } 433 434 /** 435 * Returns the {@link SpinnerDateModel} that is edited by this editor. 436 * 437 * @return the <code>SpinnerDateModel</code> that is edited by this editor 438 */ 439 public SpinnerDateModel getModel() 440 { 441 return (SpinnerDateModel) getSpinner().getModel(); 442 } 443 } 444 445 static class DateEditorFormatter 446 extends DateFormatter 447 { 448 public DateEditorFormatter() 449 { 450 super(DateFormat.getInstance()); 451 } 452 public DateEditorFormatter(String dateFormatPattern) 453 { 454 super(new SimpleDateFormat(dateFormatPattern)); 455 } 456 } 457 458 /** 459 * A listener that forwards {@link ChangeEvent} notifications from the model 460 * to the {@link JSpinner}'s listeners. 461 */ 462 class ModelListener implements ChangeListener 463 { 464 /** 465 * Creates a new listener. 466 */ 467 public ModelListener() 468 { 469 // nothing to do here 470 } 471 472 /** 473 * Receives notification from the model that its state has changed. 474 * 475 * @param event the event (ignored). 476 */ 477 public void stateChanged(ChangeEvent event) 478 { 479 fireStateChanged(); 480 } 481 } 482 483 /** 484 * The model that defines the current value and permitted values for the 485 * spinner. 486 */ 487 private SpinnerModel model; 488 489 /** The current editor. */ 490 private JComponent editor; 491 492 private static final long serialVersionUID = 3412663575706551720L; 493 494 /** 495 * Creates a new <code>JSpinner</code> with default instance of 496 * {@link SpinnerNumberModel} (that is, a model with value 0, step size 1, 497 * and no upper or lower limit). 498 * 499 * @see javax.swing.SpinnerNumberModel 500 */ 501 public JSpinner() 502 { 503 this(new SpinnerNumberModel()); 504 } 505 506 /** 507 * Creates a new <code>JSpinner with the specified model. The 508 * {@link #createEditor(SpinnerModel)} method is used to create an editor 509 * that is suitable for the model. 510 * 511 * @param model the model (<code>null</code> not permitted). 512 * 513 * @throws NullPointerException if <code>model</code> is <code>null</code>. 514 */ 515 public JSpinner(SpinnerModel model) 516 { 517 this.model = model; 518 this.editor = createEditor(model); 519 model.addChangeListener(new ModelListener()); 520 updateUI(); 521 } 522 523 /** 524 * If the editor is <code>JSpinner.DefaultEditor</code>, then forwards the 525 * call to it, otherwise do nothing. 526 * 527 * @throws ParseException DOCUMENT ME! 528 */ 529 public void commitEdit() throws ParseException 530 { 531 if (editor instanceof DefaultEditor) 532 ((DefaultEditor) editor).commitEdit(); 533 } 534 535 /** 536 * Gets the current editor 537 * 538 * @return the current editor 539 * 540 * @see #setEditor 541 */ 542 public JComponent getEditor() 543 { 544 return editor; 545 } 546 547 /** 548 * Changes the current editor to the new editor. The old editor is 549 * removed from the spinner's {@link ChangeEvent} list. 550 * 551 * @param editor the new editor (<code>null</code> not permitted. 552 * 553 * @throws IllegalArgumentException if <code>editor</code> is 554 * <code>null</code>. 555 * 556 * @see #getEditor 557 */ 558 public void setEditor(JComponent editor) 559 { 560 if (editor == null) 561 throw new IllegalArgumentException("editor may not be null"); 562 563 JComponent oldEditor = this.editor; 564 if (oldEditor instanceof DefaultEditor) 565 ((DefaultEditor) oldEditor).dismiss(this); 566 else if (oldEditor instanceof ChangeListener) 567 removeChangeListener((ChangeListener) oldEditor); 568 569 this.editor = editor; 570 firePropertyChange("editor", oldEditor, editor); 571 } 572 573 /** 574 * Returns the model used by the {@link JSpinner} component. 575 * 576 * @return The model. 577 * 578 * @see #setModel(SpinnerModel) 579 */ 580 public SpinnerModel getModel() 581 { 582 return model; 583 } 584 585 /** 586 * Sets a new underlying model. 587 * 588 * @param newModel the new model to set 589 * 590 * @exception IllegalArgumentException if newModel is <code>null</code> 591 */ 592 public void setModel(SpinnerModel newModel) 593 { 594 if (newModel == null) 595 throw new IllegalArgumentException(); 596 597 if (model == newModel) 598 return; 599 600 SpinnerModel oldModel = model; 601 model = newModel; 602 firePropertyChange("model", oldModel, newModel); 603 setEditor(createEditor(model)); 604 } 605 606 /** 607 * Gets the next value without changing the current value. 608 * 609 * @return the next value 610 * 611 * @see javax.swing.SpinnerModel#getNextValue 612 */ 613 public Object getNextValue() 614 { 615 return model.getNextValue(); 616 } 617 618 /** 619 * Gets the previous value without changing the current value. 620 * 621 * @return the previous value 622 * 623 * @see javax.swing.SpinnerModel#getPreviousValue 624 */ 625 public Object getPreviousValue() 626 { 627 return model.getPreviousValue(); 628 } 629 630 /** 631 * Gets the <code>SpinnerUI</code> that handles this spinner 632 * 633 * @return the <code>SpinnerUI</code> 634 */ 635 public SpinnerUI getUI() 636 { 637 return (SpinnerUI) ui; 638 } 639 640 /** 641 * Gets the current value of the spinner, according to the underly model, 642 * not the UI. 643 * 644 * @return the current value 645 * 646 * @see javax.swing.SpinnerModel#getValue 647 */ 648 public Object getValue() 649 { 650 return model.getValue(); 651 } 652 653 /** 654 * Sets the value in the model. 655 * 656 * @param value the new value. 657 */ 658 public void setValue(Object value) 659 { 660 model.setValue(value); 661 } 662 663 /** 664 * Returns the ID that identifies which look and feel class will be 665 * the UI delegate for this spinner. 666 * 667 * @return <code>"SpinnerUI"</code>. 668 */ 669 public String getUIClassID() 670 { 671 return "SpinnerUI"; 672 } 673 674 /** 675 * This method resets the spinner's UI delegate to the default UI for the 676 * current look and feel. 677 */ 678 public void updateUI() 679 { 680 setUI((SpinnerUI) UIManager.getUI(this)); 681 } 682 683 /** 684 * Sets the UI delegate for the component. 685 * 686 * @param ui The spinner's UI delegate. 687 */ 688 public void setUI(SpinnerUI ui) 689 { 690 super.setUI(ui); 691 } 692 693 /** 694 * Adds a <code>ChangeListener</code> 695 * 696 * @param listener the listener to add 697 */ 698 public void addChangeListener(ChangeListener listener) 699 { 700 listenerList.add(ChangeListener.class, listener); 701 } 702 703 /** 704 * Remove a particular listener 705 * 706 * @param listener the listener to remove 707 */ 708 public void removeChangeListener(ChangeListener listener) 709 { 710 listenerList.remove(ChangeListener.class, listener); 711 } 712 713 /** 714 * Gets all the <code>ChangeListener</code>s 715 * 716 * @return all the <code>ChangeListener</code>s 717 */ 718 public ChangeListener[] getChangeListeners() 719 { 720 return (ChangeListener[]) listenerList.getListeners(ChangeListener.class); 721 } 722 723 /** 724 * Fires a <code>ChangeEvent</code> to all the <code>ChangeListener</code>s 725 * added to this <code>JSpinner</code> 726 */ 727 protected void fireStateChanged() 728 { 729 ChangeEvent evt = new ChangeEvent(this); 730 ChangeListener[] listeners = getChangeListeners(); 731 732 for (int i = 0; i < listeners.length; ++i) 733 listeners[i].stateChanged(evt); 734 } 735 736 /** 737 * Creates an editor that is appropriate for the specified <code>model</code>. 738 * 739 * @param model the model. 740 * 741 * @return The editor. 742 */ 743 protected JComponent createEditor(SpinnerModel model) 744 { 745 if (model instanceof SpinnerDateModel) 746 return new DateEditor(this); 747 else if (model instanceof SpinnerNumberModel) 748 return new NumberEditor(this); 749 else if (model instanceof SpinnerListModel) 750 return new ListEditor(this); 751 else 752 return new DefaultEditor(this); 753 } 754 }