CHANGES SINCE THE PREVIOUS RELEASE This file summarizes changes made since Swing 0.7. Most bug fixes, javadoc improvements, and look-and-feel cosmetic changes are not listed here. For the latest, detailed information about Swing, be sure to check our Web site, The Swing Connection: http://java.sun.com/products/jfc/swingdoc-current/ =================== Swing API Stability =================== This release contains some minor API changes, which are detailed in the sections below. A few of these were incompatible with the Swing 0.7 API; see the "JComponent", "Action", "Keyboard Navigation", "UIManager", and "Event Package" sections. As of Swing1.0 the entire API has been frozen less a few important exceptions: - The look and feel implementation classes in the swing.plaf and subpackages of swing.plaf have not been frozen. To write a new look and feel one needs to extend the classes in the swing.plaf packages. New applications and components that do so will need to upgrade when the final version of the look and feel classes is released. We expect to do so when Swing ships with the final version of JDK1.2. - The classes in the swing.preview package are not frozen. The JColorChooser and JFileChooser classes will be revised for the next Swing release. - Serialized Swing 1.0 objects will not be compatible with future swing releases. The current serialization support is appropriate for short term storage or RMI between Swing1.0 applications. It will not be possible to load serialized Swing1.0 objects with future releases of Swing. The JDK1.2 release of Swing will be the compatibility baseline for the serialized form of Swing objects. ========== JComponent ========== Removed the get/setClientProperties() methods from the JComponent API. The clientProperty (note: singular) property is now bound. That is, putClientProperty() fires PropertyChangeEvents. Moved setOpaque() to JComponent. JComponent.isOpaque() still returns false by default, as before. JComponent subclasses that used to define setOpaque() and had made the default value of this property be true now rely on BasicXXXUI to call setOpaque(true) in installUI(). ======= JDialog ======= Support for Modality -------------------- In prior releases of Swing, creating a modal JDialog resulted in a dialog where calls to show() would block but input was still active in other windows (hence these were not really AWT "modal" dialogs). This swing "fake" modality in JDialog was implemented to get around an AWT 1.1 limitation where Windows cannot be parented directly from Dialogs. (Hence, Swing components such as JPopupMenu and JComboBox that created Window objects would not be operable when placed inside real modal dialogs because input would be blocked to those "popup" Windows). Unfortunately, not only did this JDialog workaround fail to truly block input to other windows (the real definition of "modal"), but this workaround also caused applet security exceptions since it required direct access to the system event queue. For the above reasons, we have changed JDialog to use true AWT modality for the final release. To get around the problem where swing components containing popups (JPopupMenu, JComboBox, JMenuBar) are inoperable in modal dialogs, we have constrained these components to ALWAYS use lightweight popup menus when placed inside modal dialogs. This creates the following caveats: 1. Modal dialogs containing swing popup components (JPopupMenu, JComboBox, JMenuBar) should be large enough to display the entire popup, else the popup may be clipped when shown, since it is entirely lightweight. 2. If you mix AWT heaveyweight components with swing popup components (JPopupMenu, JComboBox, JMenuBar) within a modal dialog, popups may be obscured when shown since the heavyweight components will always be on top of the lightweight popups. Note: These restrictions will be removed from the swing release which ships with JDK1.2 because in AWT 1.2, Windows and Dialogs can be created with Windows as owners (no longer restricted to Frames). This means Swing's popup components can create their popups with the modal Dialog as the parent, which will ensure proper popup operation. Additionally, we have removed the method from JDialog which implemented swing's 'fake' modality: protected void blockingShow() Note: Due to a bug in the AWT, modal dialogs can ONLY be created by passing "true" as the modal parameter in the constructor (setModal() will not work). ================= RootPaneContainer ================= Added a RootPaneContainer interface. JFrame, JDialog, JWindow, JApplet, and JInternalFrame implement this interface by delegating to getRootPane(). Also, we regularized checking and exception throwing in add() and setLayout() for all of these classes. Note that checking is disabled by the constructor and updateUI(). =========== JTabbedPane =========== In response to overwelming demand, a number of features were added to the TabbedPane for this release: o A "tabPlacement" property that allows placement of the tabs to be on the TOP, LEFT, BOTTOM, or RIGHT of the content area: public JTabbedPane(int tabPlacement) public void setTabPlacement(int tabPlacement) public int getTabPlacement() o The ability to set whether or not an individual tab is enabled or disabled: public void setEnabledAt(int index, boolean enabled) public boolean isEnabledAt(int index) o The ability to set foreground/background color on individual tabs: public void setForegroundAt(int index, Color foreground) public Color getForegroundAt(int index) public void setBackgroundAt(int index, Color foreground) public Color getBackgroundAt(int index) o The ability to get the current bounds of a particular tab: public Rectangle getBoundsAt(int index) o The ability to get the current number of tab runs being displayed in the TabbedPane: public int getTabRunCount() ======= JButton ======= Added a "defaultButton" property. L&Fs that care to will render default buttons differently. ======= Borders ======= MatteBorder: added dynamic insets based on image EtchedBorder: added raised/lowered styles ============================================ JTable and Associated Classes ============================================ The following policies resulted in changes to the JTable and its associated classes. The changes are very minor compared to the complete overhaul that the JTable API went through between 0.6.1 and 0.7 and are mainly modifications that enable the new keyboard navigation facilities to work consistently in all of the JTable's selection modes. #1. Remove the DefaultCellRenderer and replace it with a subclass of JLabel that just renders Strings and Icons. This makes sublcassing the new DefaultTableCellRenderer easier for common cases, like having differerent colored cells on different rows. It also brings it more in line (though not enough) with the renderers of the JList and JTree. Make this new default renderer indicate focus. [The old implementation DefaultCellRenderer has been moved to the pending area as a porting aid]. #2. Encourage all renderers to indicate focus. This aligns the TableCellRenderer interface with the ListCellRenderer and TreeCellRenderer interfaces. #3. Remove all transient state from UI in preparation for expansion of keyboard navigation facilities. Use the anchors in the selection models as the state required in keyboard navigation. #4. Keep setShowGrid() but add independent controls for the drawing of horizontal and vertical lines. #5. Remove the selection mode that dynamically switched between row and column based modes. This means that the anchors of the selection models can be used for keyboard navigation. This leads to a stateless UI (for #3) and a unified approach for handling mouse and keyboard events in the UI. #6. In "getSelectedRow()" and "getSelectedColumn()", return the anchor rather than the lead from the selection models. Swing and Table Packages ------------------------ DELETE (#1) swing.DefaultCellRenderer ADD (#1) swing.table.DefaultTableCellRenderer TableCellRenderer ----------------- CHANGE (#2) FROM: Component getTableCellRendererComponent(JTable table, Object value, boolean isSelected, int row, int column); TO: Component getTableCellRendererComponent(JTable table, Object value, boolean isSelected, boolean hasFocus, int row, int column); BasicTableUI ------------ Change all methods that can be overridden indirectly from protected to private for backward compatible performance tuning in subsequent releases. CHANGE (typo) FROM: public void drawRowInClipRect(int row, Rectangle rect, Graphics g) TO: protected void drawRowInClipRect(int row, Rectangle rect, Graphics g) DELETE (#3) transient protected boolean hasPress; transient protected int hitRowIndex; transient protected int hitColumnIndex; transient protected TableColumn hitColumn; transient protected boolean controlKeyDown; transient protected boolean isSelecting; transient protected int anchorRowIndex; transient protected int anchorColumnIndex; JTable ------ CHANGED (typo) FROM: protected void createDefaultRenders() TO: protected void createDefaultRenderers() CHANGED (#4) FROM: protected boolean showGrid; TO: protected boolean showHorizontalLines; protected boolean showVerticalLines; DELETE public boolean getShowGrid() ADD public void setShowHorizontalLines(boolean b) public boolean getShowHorizontalLines() public void setShowVerticalLines(boolean b) public boolean getShowVerticalLines() CHANGE (misname) FROM: public int editingRow() public int editingColumn() TO: public int getEditingRow() public int getEditingColumn() DELETE (#5) protected boolean isRowSelected Changed (implementations) (#6). public int getSelectedRow() public int getSelectedColumn() ========================== Java Look and Feel - Metal ========================== Based on developer and user feedback, we have decided to make the Metal look and feel the default cross-platform look and feel in Swing. Organic L&F, previously a part of the Swing release, will now be available separately. For more information on the new Metal L&F and on how to get Organic, please visit the Swing Connection web site: http://java.sun.com/products/jfc/swingdoc-current/ The Metal classes are in swing.jar, rather than being in a separate jar file. Metal-Specific UI Client Properties ----------------------------------- Swing supports setting client properties on components which can be used by their corresponding UI objects to display an alternate form of the component. If a property is not supported by a look and feel, it will simply be ignored and the component displayed as usual. In Metal, the components that currently support properties include: JSlider Normal (default): mySlider.putClientProperty( "JSlider.isFilled", Boolean.FALSE ); Filled: mySlider.putClientProperty( "JSlider.isFilled", Boolean.TRUE ); JToolBar Normal (default): myToolBar.putClientProperty( "JToolBar.isRollover", Boolean.FALSE ); Rollover Buttons (All regular buttons in the toolbar): myToolBar.putClientProperty( "JToolBar.isRollover", Boolean.TRUE ); JTree No Lines: myTree.putClientProperty("JTree.lineStyle", "None"); Angled Lines from Parent to Child: myTree.putClientProperty("JTree.lineStyle", "Angled"); Horizontal Lines between Root Nodes (default): myTree.putClientProperty("JTree.lineStyle", "Horizontal"); Metal Internal Frame UI ----------------------- To set the color of the 'notch' in the upper right corner underneath the title bar: myInternalFrame.getContentPane().setBackground(fillColor); To add a JScrollPane to an internal frame, do not add it to the existing content pane, use setContentPane() instead. Metal Themes ------------ Themes provide an easy way to change certain parts of a look and feel, such as colors and fonts, without creating a whole new look and feel. Currently Metal and Organic support themes. Swing 1.0 includes a demo called Metalworks that demonstrates how to create your own custom themes. =================== The Text Components =================== Major rework of the way formatting of styled text is done. The most significant difference is that now weights are used to determine best break positions. The user-level effect is that now breaks will occur on whitespace boundries unless no whitespace can be found; also, forced breaks are now handled. An additional benefit of this change is that views are reused and formatting no longer involves the view factory. This can improve performace substantially in some cases, and makes it much easier to write non-breaking views that will be contained in a container that breaks (e.g. ParagraphView). Added line-wrap support to JTextArea and fixed StyleContext deadlock problem. Styled text tab handling integration. This adds support for RTF-style tab handling. Removed a couple of methods on JTextPane that were implemented to throw an error; improved the javadoc a little. =================== Keyboard Navigation =================== Changed getKeyAccelerator/setKeyAccelerator to getMnemonic/setMnemonic respectively. Added setAccelerator(). ====== JLabel ====== Renamed displayedKeyAccelerator to displayedMnemonic. The labelFor property is now bound to the displayedMnemonic property. As a result, if the keyboard accelerator associated with the displayedMnemonic property is typed, the JLabel instance attempts to give keyboard focus to the Component identified by the labelFor property. ======= JSlider ======= Changed the default slider behavior to snap-to-ticks. ====== Action ====== In this release, get/setText and get/setIcon were collapsed into one pair of methods, get/setValue. This was done to alleviate complaints that Actions were less flexible than they could be. It is now easier to use the existing Action interface with attributes of types other than String or Icon, instead of having to extend the interface. It should be noted that the key/value pairs for all Action attributes are now in the same name space, which means that while it was previously possible to have both text and icon with the same key, these now clash. =================== AbstractAction.java =================== In this release, the key/value lookup has been implemented so that it now works to have more than one text or icon attribute (subject to the above). It should be noted that the current implementation with a HashTable will be replaced with a more lightweight version in the next release. (This will not affect the API.) The current implementation is out of line with the spec in than getValue can currently return null. Remember to test the values returned by Action.getValue before using them! ===== Menus ===== There have been several fixes to Menu bugs for this release. In addition, there have been some small changes to the APIs. Accelerators and Mnemonics -------------------------- The get/setKeyAccelerator methods have been replaced with get/setMnemonic and get/setAccelerator. Mnemonics are used to choose menu items when navigating the menu hierarchy with the keyboard. Accelerators (hot-keys) are used to invoke a menu item's actionListeners without needing to traverse the menu items with the keyboard; the menu is never brought up, but the actionListeners for the menu item are invoked. Bugs Fixed ---------- 1. Heavyweight menus now popup the first time on Solaris. This is for the most part fixed, although certain timing issues can still lead to its happening. 2. Events over non-MenuItems on lightweight PopupMenus no longer get dispatched to the underlying components. 3. Recycling heavyweight PopupMenus no longer causes problems if you use multiple JFrames. 4. BasicMenuMouse* listeners are now Serializable. Remaining Known Bugs -------------------- 1. Lightweight menus get clipped by heavyweight components in the invoking frame. This is because of the known restrictions on mixing heavyweight and lightweight components in the AWT. It is now easier to work around this, if you need to mix heavyweight and lightweight components, by calling JPopupMenu.setDefaultLightWeightPopupEnabled(false). 2. On Solaris, placement and selection of lightweight JPopupMenus may be wrong after resizing the invoking Frame to the top and/or left. 3. JPopupMenus in JApplets may display the Warning--Applet tag. ========== JPopupMenu ========== The following API changes have been made to JPopupMenu: 1. The constructor which takes an invoker has been removed, because too many people thought that this would automatically make the popup menu come up when the popup trigger was pressed over the invoker. You should replace calls to this constructor with a call to one of the other constructors, and then call setInvoker(). 2. Certain methods intended only for internal use in the Menu implementation have been made private or package private. These are: isPopupMenu(), getRootPopupMenu(). ================= JCheckBoxMenuItem ================= The get/setAction() method has been removed to be consistent with other AbstractButton subclasses. ======== JToolBar ======== In this release, we added is/setFloatable to the JToolBar API. Also, the drag-out code listens only for mouse dragged rather than mouse pressed, so that it is easier to avoid accidental drag-out. The code for dragging has been tuned so that the performance is significantly better on Unix, and somewhat better on Windows. ============= Accessibility ============= The AccessibleTable.java and AccessibleLayout.java interfaces are pending and we welcome your comments. Please send your comments on these interfaces to access@sun.com. The following properties are now defined in AccessibleContext: ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY The following properties are now defined in AccessibleText: ACCESSIBLE_TEXT_CONTENTS_PROPERTY, ACCESSIBLE_TEXT_CARET_PROPERTY Property change events for the following properties are now fired to listeners of the AccessibleContext associated with the following Swing Components: AbstractButton: ACCESSIBLE_VISIBLE_DATA_PROPERTY, ACCESSIBLE_STATE_PROPERTY JComponent: ACCESSIBLE_STATE_PROPERTY JLabel: ACCESSIBLE_VISIBLE_DATA_PROPERTY JList: ACCESSIBLE_VISIBLE_DATA_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY JPopupMenu: ACCESSIBLE_VISIBLE_DATA_PROPERTY JProgressBar: ACCESSIBLE_VISIBLE_DATA_PROPERTY, ACCESSIBLE_STATE_PROPERTY JScrollBar: ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_VALUE_PROPERTY JSlider: ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_VALUE_PROPERTY JTabbedPane: ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY JTree: ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY JTextComponent: ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_TEXT_CARET_PROPERTY, ACCESSIBLE_TEXT_CONTENTS_PROPERTY In addition, AccessibleContext will fire property change events for these properties: ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_DESCRIPTION_PROPERTY. ========= UIManager ========= Setting the L&F --------------- The default look and feel has been changed. It is now the cross platform "metal" look and feel, previously it was the system look and feel - e.g. motif on Solaris. To restore the original behavior put the following statement at the beginning of your app: UIManager.setLookAndFeel(UIManager.getSystemLookAndFeelClassName()); The getSystemLookAndFeelClassName() method returns the name of the motif or windows LookAndFeel subclass, depending on the platform. Swing Properties ---------------- Renamed the swing properties file (defined in UIManager.java) from "uimanager.properties" to "swing.properties". Renamed all of the properties in this file to be consistent with the other JDK lib/*.properties files: DefaultLookAndFeel => swing.defaultlaf AuxiliaryLookAndFeels => swing.auxiliarylaf MultiplexingLookAndFeel => swing.multiplexinglaf Added a new property called "swing.installedlafs" whose value must be a comma-separated list of L&F names. Used like this: swing.installedlafs=motif,windows swing.installedlaf.motif.name=CDE/Motif swing.installedlaf.motif.class=com.sun.java.swing.plaf.motif.MotifLookAndFeel swing.installedlaf.windows.name=Windows swing.installedlaf.windows.class=com.sun.java.swing.plaf.windows.WindowsLookAndFeel Installed L&Fs -------------- Restored some of the support for keeping track of a list of installed look and feels in UIManager. A look and feel is "installed" if it appears in the /lib/swing.properties file. The format of this file needs to be added to the UIManager class javadoc. The new UIManager methods are: public static LookAndFeelInfo[] getInstalledLookAndFeels(); public static void setInstalledLookAndFeels(LookAndFeelInfo[] infos); public static void installLookAndFeel(LookAndFeelInfo info); public static void installLookAndFeel(String name, String className); Currently these methods do not rewrite the swing.properties file. There's also a new class, UIManager.LookAndFeelInfo, that's little more than a glorified name,className struct for LookAndFeels. ============================== JFileChooser and JColorChooser ============================== JFileChooser and JColorChooser and their supporting files were moved into the swing.preview package. Their APIs are not frozen, but they may be used on an as-is, subject-to-change basic. ============= Event Package ============= Some event files that used to live outside of swing.event were moved into swing.event.