From c5d2de6b4c976dc152c8618ab3e8e1319018dc30 Mon Sep 17 00:00:00 2001 From: Graydon Hoare Date: Thu, 27 May 2004 06:17:44 +0000 Subject: [multiple changes] 2004-05-25 David Jee * java/awt/Container.java (remove): Set component's parent to null only after we removed the component from its parent's layout manager. 2004-05-25 David Jee * gnu/java/awt/peer/gtk/GtkComponentPeer.java (GtkComponentPeer): Set bounds regardless of whether awtComponent is valid. * gnu/java/awt/peer/gtk/GtkListPeer.java (getSize): Change native method declaration. (minimumSize): Pass visible row count into getSize(). (preferredSize): Likewise. * jni/gtk-peer/gnu_java_awt_peer_gtk_GtkListPeer.c (Java_gnu_java_awt_peer_gtk_GtkListPeer_getSize): Use scroll window's natural size. Use visible row count to determine the final height value to return. 2004-05-21 Graydon Hoare * gnu/java/awt/peer/gtk/GdkGraphics2D.java (setClip): Minor correction to order of operations. * javax/swing/JScrollPane.java: Extend sketchy implementation. * javax/swing/ScrollPaneLayout.java: Likewise. * javax/swing/JViewPort.java: Likewise. * javax/swing/ViewportLayout.java: Likewise. * javax/swing/JComponent.java: Rewrite. * javax/swing/RepaintManager.java: Likewise. * javax/swing/JLayeredPane.java: Change validate() to revalidate(). * javax/swing/JList.java (setSelectedIndices): (getSelectedIndices): (getSelectedValues): New functions. (getPreferredScrollableViewportSize): Return preferred size. (getScrollableUnitIncrement): (getScrollableBlockIncrement): Initial implementations. * javax/swing/JRootPane.java: Clean up slightly. (getUI): (setUI): (updateUI): (getUIClassID): (isValidateRoot): Add overrides from JComponent. * javax/swing/JScrollBar.java: Set default orientation to VERTICAL. * javax/swing/UIManager.java (getDimension): Return the dimension. * javax/swing/plaf/basic/BasicButtonUI.java: Set component opaque. * javax/swing/plaf/basic/BasicLabelUI.java: Likewise. * javax/swing/plaf/basic/BasicMenuItemUI.java: Likewise. * javax/swing/plaf/basic/BasicProgressBarUI.java: Likewise. * javax/swing/plaf/basic/BasicSeparatorUI.java: Likewise. * javax/swing/plaf/basic/BasicSliderUI.java: Likewise. * javax/swing/plaf/basic/BasicTabbedPaneUI.java: Likewise. * javax/swing/plaf/basic/BasicRootPaneUI.java: Likewise, and set background. * javax/swing/plaf/basic/BasicListUI.java: Likewise, and improve a bit. * javax/swing/plaf/basic/BasicScrollBarUI.java: Likewise, and adjust calculations. * javax/swing/plaf/basic/BasicViewportUI.java: Likewise, and improve a bit. * javax/swing/plaf/basic/BasicLookAndFeel.java (Button.margin): Shrink. * jni/gtk-peer/gnu_java_awt_peer_gtk_GdkGlyphVector.c: Hack to set horizontal always, workaround pango. * jni/gtk-peer/gtkcairopeer.h: Change to match pattern API. * jni/gtk-peer/gnu_java_awt_peer_gtk_GdkGraphics2D.c: Synchronize more often, check cairo status after ops, handle changes to cairo pattern API, check for disposal. 2004-05-21 Olga Rodimina * javax/swing/plaf/basic/BasicMenuItemUI.java: (BasicMenuItemUI): Create propertyChangeListener. (getPath):Implemented. (installListeners): Add propertyChangeListener to menuItem. (uninstallListeners): Remove propertyChangeListener from menuItem. (update): Implemented. * javax/swing/plaf/basic/BasicMenuUI.MouseInputHandler: (mouseEntered): Take insets of popup menu into account when calculating position of popup menu. 2004-05-18 Olga Rodimina * Makefile.am: Added new file. * Makefile.in: Regenerate. * javax/swing/JMenuBar.java: Started implementation. * javax/swing/JPopupMenu.java: (setVisible): Fixed location of lightweight/mediumweight popup menu. (show): Fixed location of PopupMenu. * javax/swing/plaf/basic/BasicMenuBarUI.java: New file. UI Delegate for JMenuBar. * javax/swing/plaf/basic/BasicMenuUI.MouseInputHandler: (mouseEntered): Corrected position of the submenu. 2004-05-18 Thomas Fitzsimmons * jni/gtk-peer/gnu_java_awt_peer_gtk_GtkMenuPeer.c: Remove calls to _gtk_accel_group_attach. * jni/gtk-peer/gnu_java_awt_peer_gtk_GtkPopupMenuPeer.c: Likewise. * gnu/java/awt/peer/gtk/GtkButtonPeer.java: Give gtkSetFont package access. Don't override setFont. * gnu/java/awt/peer/gtk/GtkCheckboxPeer.java: Likewise. * gnu/java/awt/peer/gtk/GtkComponentPeer.java: Give gtkWidgetRequestFocus package access. * gnu/java/awt/peer/gtk/GtkLabelPeer.java: Don't override setFont. * gnu/java/awt/peer/gtk/GtkListPeer.java: Override gtkSetFont. Give gtkWidgetRequestFocus package access. * gnu/java/awt/peer/gtk/GtkTextAreaPeer.java: Give gtkWidgetRequestFocus package access. Don't override setFont. * gnu/java/awt/peer/gtk/GtkTextFieldPeer.java: Don't override setFont. * jni/gtk-peer/gnu_java_awt_peer_gtk_GtkButtonPeer.c (gtkSetLabel): Move call to gtk_bin_get_child into GDK critical region. (gtkSetFont): Likewise. * jni/gtk-peer/gnu_java_awt_peer_gtk_GtkListPeer.c (gtkSetFont): Implement. * jni/gtk-peer/gnu_java_awt_peer_gtk_GtkTextAreaPeer.c (gtkSetFont): Whitespace fix. * jni/gtk-peer/gnu_java_awt_peer_gtk_GtkComponentPeer.c (gtkWidgetSetUsize): Remove method. 2004-05-18 David Jee * java/awt/image/MemoryImageSource.java (newPixels(int,int,int,int,boolean)): Set only the specified rectangle of pixels. (newPixels(byte[],ColorModel,int,int)): Implement. (newPixels(int[],ColorModel,int,int)): Implement. 2004-05-18 Olga Rodimina * Makefile.am: Added new file. * Makefile.in: Regenerate. * javax/swing/JMenu.java: Started implementation. * javax/swing/JPopupMenu.java: (insert): If specified index is -1, then add component at the end. (isPopupTrigger): Reimplemented. (JPopupMenu.LightWeightPopup): setBounds of the lightWeightPopup before adding it to the layeredPane. (javax/swing/plaf/basic/BasicIconFactory.java): (getMenuArrowIcon): Implemented. * javax/swing/plaf/basic/BasicMenuItemUI.java: (getPreferredSize): Add size of the arrow icon if this menu item is instance of JMenu. (paintMenuItem): Paint arrow icon if this menu item is a submenu. * javax/swing/plaf/basic/BasicMenuUI.java: New File. UI Delegate for JMenu. 2004-05-17 Thomas Fitzsimmons * gnu/java/awt/peer/gtk/GtkComponentPeer.java (postKeyEvent): Post KEY_TYPED events. * jni/gtk-peer/gnu_java_awt_peer_gtk_GtkEvents.c (generates_key_typed_event): Remove function. 2004-05-17 Olga Rodimina * javax/swing/JRootPane.java (JRootPane.RootLayout): Reimplemented to set bounds of contentPane and menuBar. (setJMenuBar): Add menu bar to the layered pane. (createLayeredPane): Set layout of layeredPane to null. * javax/swing/JLayeredPane.java: (addImpl): Calculate index of the component in the layeredPane according to the specified position within the layer. 2004-05-17 David Jee * gnu/java/awt/peer/gtk/GtkImagePainter.java (setPixels): Change color model to the default model after converting pixels. * java/awt/image/MemoryImageSource.java (newPixels): Set only the specified rectangle of pixels. 2004-05-13 Thomas Fitzsimmons * libgcj.spec.in (lib): Add -l-java-awt -l-java-applet -l-java-beans -l-javax-accessibility -l-javax-swing. * java/awt/AWTEvent.java (toString): Print source's name rather than the source itself. 2004-05-12 Thomas Fitzsimmons * gnu/java/awt/peer/gtk/GtkToolkit.java (loadSystemColors): Make native. * jni/gtk-peer/gnu_java_awt_peer_gtk_GtkToolkit.c (gdk_color_to_java_color): New function. * jni/gtk-peer/gtkpeer.h: Add SystemColor defines. 2004-05-12 David Jee * java/awt/image/RGBImageFilter.java: Initialize origmodel as null. (makeColor): Fix pixel component order. (filterRGBPixels): Fix pixel iteration. (setPixels): Add extra checks for index color model. Convert pixels to default color model if necessary. (convertColorModelToDefault): New override method for byte pixels. (convertColorModelToDefault): For int pixels, fix pixel iteration. (makeColorbyDefaultCM): New override method for byte pixels. (makeColorbyDefaultCM): For int pixel, add color model as argument. (makeColor): Fix pixel component order. 2004-05-11 Kim Ho * javax/swing/Box.java: Comment out more parts of Box.Filler. 2004-05-11 Kim Ho * javax/swing/Box.java: Remove reference to AccessibleAWTComponent so it compiles again. 2004-05-10 Thomas Fitzsimmons * gnu/java/awt/peer/gtk/GtkListPeer.java, jni/gtk-peer/gnu_java_awt_peer_gtk_GtkListPeer.c: Update implementation of list peer to use GtkTreeView instead of deprecated GtkCList. 2004-05-07 Thomas Fitzsimmons * gnu/java/awt/peer/gtk/GtkComponentPeer.java (gtkWidgetDispatchKeyEvent): Remove keyChar parameter. (handleEvent): Remove keyChar argument to gtkWidgetDispatchKeyEvent calls. * jni/gtk-peer/gnu_java_awt_peer_gtk_GtkComponentPeer.c: Fix compiler warnings. * jni/gtk-peer/gnu_java_awt_peer_gtk_GtkEvents.c: Likewise. * jni/gtk-peer/gnu_java_awt_peer_gtk_GtkMenuPeer.c: Likewise. * jni/gtk-peer/gnu_java_awt_peer_gtk_GtkTextComponentPeer.c: Likewise. 2004-05-06 Thomas Fitzsimmons * gnu/java/awt/peer/gtk/GtkComponentPeer.java (gtkWidgetRequestFocus): Mark protected. (GtkComponentPeer): Only set the peer's bounds if its component is valid. * java/awt/Component.java (static): Set the default keyboard focus manager. (requestFocus(), requestFocus(boolean), requestFocusInWindow(), requestFocusInWindow(temporary)): Don't request focus if the component is not showing. Get tree lock before traversing component hierarchy. * java/awt/DefaultKeyboardFocusManager.java (dispatchEvent): Only set the global focus owner if it is not a Window. (processKeyEvent): Consume keystrokes associated with the focus traversal keystroke. (focusPreviousComponent, focusNextComponent, upFocusCycle, downFocusCycle): Call requestFocusInWindow instead of requestFocus. * java/awt/EventDispatchThread.java (run): Move setting of default keyboard focus manager to Component.java. * jni/gtk-peer/gnu_java_awt_peer_gtk_GtkComponentPeer.c (awt_keycode_to_keysym): New function. (gtkWidgetDispatchKeyEvent): Finish implementation. * jni/gtk-peer/gnu_java_awt_peer_gtk_GtkEvents.c (pre_event_handler): Add FIXME comment. * gnu/java/awt/peer/gtk/GtkTextAreaPeer.java, jni/gtk-peer/gnu_java_awt_peer_gtk_GtkTextAreaPeer.c (gtkWidgetRequestFocus): New method. * java/awt/TextArea.java (TextArea): Set focus traversal keys to disable Tab and Shift-Tab keystrokes. (addNotify, appendText, insertText, replaceText): Simplify peer retrieval code. * jni/gtk-peer/gnu_java_awt_peer_gtk_GtkTextComponentPeer.c (connectSignals): Remove connections to "commit" signals. Remove C++-style comments. * gnu/java/awt/peer/gtk/GtkButtonPeer.java, jni/gtk-peer/gnu_java_awt_peer_gtk_GtkButtonPeer.c (handleEvent): Activate GTK button when the space bar key is pressed. (gtkActivate): New method. 2004-05-06 David Jee * java/awt/image/CropImageFilter.java (setPixels): Implement for byte array pixels. * java/awt/image/ReplicateScaleFilter.java (setPixels): Implement for byte array pixels. (replicatePixels): Overload for byte array pixels. 2004-05-06 Kim Ho * javax/swing/Box.java: (getAccessibleContext): Return an instance of the correct class. 2004-05-05 David Jee * gnu/java/awt/peer/gtk/GdkGraphics.java (drawImage): When component is null, use SystemColor.window as the default bgcolor. * gnu/java/awt/peer/gtk/GtkImage.java (setPixels): We can avoid iterating through the pixel rows only when height is 1. * java/awt/Image.java (getScaledInstance): Partially implement. * java/awt/image/CropImageFilter.java (setProperties): Fix "filter" property. (setPixels): Implement. * java/awt/image/ReplicateScaleFilter.java (setDimensions): Use scaled dimensions. (setPixels): Implement. (replicatePixels): New method. 2004-05-05 David Jee * gnu/java/awt/peer/gtk/GtkImagePainter.java (convertPixels): If either pixels or model is null, return null. * jni/gtk-peer/gnu_java_awt_peer_gtk_GtkImagePainter.c (Java_gnu_java_awt_peer_gtk_GtkImagePainter_drawPixels): If jpixels is null, do nothing and return. 2004-05-03 Kim Ho * gnu/java/awt/peer/gtk/GtkDialogPeer.java: (getGraphics): Like GtkFramePeer, the Graphics object needs to be translate to account for window decorations. (postMouseEvent): New method. Account for translation. (postExposeEvent): ditto. * javax/swing/Box.java: Stubbed. * javax/swing/JDialog.java: Ran through jalopy to fix indentation. (JDialog): Call SwingUtilities' getOwnerFrame for null owners. (setLayout): Check isRootPaneCheckingEnabled * javax/swing/JOptionPane.java: Re-implemented. * javax/swing/SwingUtilities.java: (getOwnerFrame): Static method to grab a default owner frame for Dialogs that don't specify owners. * javax/swing/event/SwingPropertyChangeSupport.java: (firePropertyChange): Fix early exit condition. * javax/swing/plaf/basic/BasicLabelUI.java: (paint): Avoid painting text if it is null or empty. * javax/swing/plaf/basic/BasicOptionPaneUI.java: Implement. 2004-05-03 Olga Rodimina * Makefile.am: Added new file. * Makefile.in: Regenerate. * javax/swing/JPopupMenu.java: Started implementation. * javax/swing/JWindow.java (JWindow): call super() if parent for window is not specified. * javax/swing/plaf/basic/BasicPopupMenuUI.java: New File. UI Delegate for JPopupMenu. 2004-04-30 Olga Rodimina * javax/swing/JApplet.java: Indicated that JApplet implements RootPaneContainer and made method of this interface public. * javax/swing/JFrame.java: Ditto. * javax/swing/JWindow.java: Ditto. 2004-04-29 Thomas Fitzsimmons * jni/gtk-peer/gnu_java_awt_peer_gtk_GtkWindowPeer.c (nativeSetBounds): Call gdk_window_move in addition to gtk_window_move. * java/applet/Applet.java (preferredSize): Call parent's preferredSize if the applet stub is null. (minimumSize): Likewise for parent's minimumSize. 2004-04-27 Olga Rodimina * javax/swing/JMenuItem.java (createActionPropertyChangeListener): Implemented. (processMouseEvent): Ditto. (fireMenuDragMouseEntered): Ditto. (fireMenuDragMouseExited): Ditto. (fireMenuDragMouseDragged): Ditto. (fireMenuDragMouseReleased): Ditto. (menuSelectionChanged): Ditto. (getSubElements): Ditto. (getComponent): Ditto. (addMenuDragMouseListener): Ditto. (removeMenuDragMouseListener):Ditto. (addMenuKeyListener): Ditto. (removeMenuKeyListener): Ditto. * javax/swing/plaf/basic/BasicMenuItemUI.java (doClick): Imlemented. * javax/swing/plaf/basic/BasicMenuItemUI.MouseInputHandler: Don't handle mouse events here. Pass them to MenuSelectionManager. 2004-04-26 Olga Rodimina Used correct version of jalopy configuration file to fix style in the files below. 2004-04-26 Olga Rodimina * javax/swing/JCheckBoxMenuItem.java: Fixed style and removed unnecessary comments. * javax/swing/JMenuItem.java: Ditto. * javax/swing/JRadioButtonMenuItem.java: Ditto. * javax/swing/plaf/basic/BasicCheckBoxMenuItemUI.java: Ditto. * javax/swing/plaf/basic/BasicMenuItemUI.java: Ditto. * javax/swing/plaf/basic/BasicRadioButtonMenuItemUI.java: Ditto. 2004-04-23 Thomas Fitzsimmons * gnu_java_awt_peer_gtk_GtkWindowPeer.c: Change FIXME comment to C-style. * gnu_java_awt_peer_gtk_GtkWindowPeer.c: Add FIXME comment. * java/awt/ContainerOrderFocusTraversalPolicy.java (getComponentAfter): Start from current component and work up the component hierarchy until an acceptable component is found. Synchronize on tree lock. (getComponentBefore): Likewise. 2004-04-22 Thomas Fitzsimmons * gnu/java/awt/peer/gtk/GtkComponentPeer.java: Remove focus-related debugging messages. * java/awt/DefaultKeyboardFocusManager.java: Likewise. * java/awt/EventDispatchThread.java: Likewise. * java/awt/KeyboardFocusManager.java: Likewise. * java/awt/Window.java: Likewise. * jni/gtk-peer/gnu_java_awt_peer_gtk_GtkComponentPeer.c: Likewise. * jni/gtk-peer/gnu_java_awt_peer_gtk_GtkEvents.c: Likewise. * jni/gtk-peer/gnu_java_awt_peer_gtk_GtkComponentPeer.c: Change new C++-style comments to C-style comments. * jni/gtk-peer/gnu_java_awt_peer_gtk_GtkEvents.c: Likewise. * gnu/java/awt/peer/gtk/GtkComponentPeer.java, jni/gtk-peer/gnu_java_awt_peer_gtk_GtkComponentPeer.c (handleEvent): Dispatch key press and key release events to backing widget. (requestFocus): Post a FOCUS_GAINED event to the event queue. (gtkWidgetRequestFocus): New method. (gtkWidgetDispatchKeyEvent): Likewise. * java/awt/Component.java (requestFocus, requestFocus(boolean), requestFocusInWindow, requestFocusInWindow(boolean), getFocusCycleRootAncestor, nextFocus, transferFocus, transferFocusBackward, transferFocusUpCycle, hasFocus, isFocusOwner): Implement and document focus-handling methods. (setFocusTraversalKeys): Inherit focus traversal keys when keystrokes argument is null. Fix focus-handling documentation throughout class. * java/awt/Container.java (setFocusTraversalKeys, getFocusTraversalKeys, areFocusTraversalKeysSet, isFocusCycleRoot, setFocusTraversalPolicy, getFocusTraversalPolicy, isFocusTraversalPolicySet, setFocusCycleRoot, isFocusCycleRoot, transferFocusDownCycle): Implement and document focus-handling methods. (transferFocusBackward): Remove method. (readObject, writeObject): Implement and document serialization methods. * java/awt/ContainerOrderFocusTraversalPolicy.java: Implement and document. * java/awt/DefaultFocusTraversalPolicy.java: Implement and document. * java/awt/DefaultKeyboardFocusManager.java: Implement and partially document. * java/awt/EventDispatchThread.java (run): Set default keyboard focus manager. Attempt to dispatch each event to the keyboard focus manager before normal dispatch. * java/awt/KeyboardFocusManager.java: Implement and partially document. * java/awt/Window.java (Window): Set focusCycleRoot to true. (show): Focus initial component when window is shown for the first time. * jni/gtk-peer/gnu_java_awt_peer_gtk_GtkEvents.c (pre_event_handler): Replace complex key press and key release logic with simple callbacks into GtkComponentPeer. * jni/gtk-peer/gtkpeer.h: Fix FOCUS_GAINED/FOCUS_LOST reversal. 2004-04-21 Olga Rodimina * javax/swing/MenuSelectionManager.java (componentForPoint): Added new method. (defaultManager): New Method. Implemented. (getSelectedPath): Ditto. (isComponentPartOfCurrentMenu): Ditto. (processKeyEvent): Added new method. (processMouseEvent): New Method. Implemented. (setSelectedPath): Ditto. (getPath): Ditto. 2004-04-19 Kim Ho * java/awt/Container.java: (remove): Set the component's parent to null. (getComponentAt): Implement. * javax/swing/JComponent.java: (JComponent): Initialize defaultLocale (getDefaultLocale): Implement. (setDefaultLocale): ditto. * javax/swing/JSlider.java: (JSlider): Fix calculation of value. * javax/swing/JSplitPane.java: Implement. * javax/swing/plaf/basic/BasicLookAndFeel.java: Change SplitPane's default divider size. * javax/swing/plaf/basic/BasicScrollBarUI.java: (paint): Remove unused code. * javax/swing/plaf/basic/BasicSplitPaneDivider.java: Added comments and ran through jalopy. (setBasicSplitPaneUI): Get reference to hidden divider and set up one touch buttons if necessary. (setBorder): Fire propertyChangeEvent only if borders are different. (getPreferredSize): Defer to layout manager. (propertyChange): Implement. (oneTouchExpandableChanged): ditto. (createLeftOneTouchButton): Use BasicArrowButton. (createRightOneTouchButton): ditto. (moveDividerTo): New method. Moves the divider to a set location based on the last divider location. (BasicSplitPaneDivider::MouseHandler): Implement. (BasicSplitPaneDivider::OneTouchButton): Removed. (BasicSplitPaneDivider::DragController): Implement. (BasicSplitPaneDivider::VerticalDragController): ditto. (BasicSplitPaneDivider::DividerLayout): ditto. * javax/swing/plaf/basic/BasicSplitPaneUI.java: Reimplement. * javax/swing/plaf/basic/BasicTabbedPaneUI.java: (calculateLayoutInfo): Don't show component if it's null. (paintTab): Fix title paint logic. From-SVN: r82314 --- libjava/java/awt/Component.java | 571 +++++++++++++++++++++++++++------------- 1 file changed, 382 insertions(+), 189 deletions(-) (limited to 'libjava/java/awt/Component.java') diff --git a/libjava/java/awt/Component.java b/libjava/java/awt/Component.java index d52818af683..3ca2b4f7aae 100644 --- a/libjava/java/awt/Component.java +++ b/libjava/java/awt/Component.java @@ -383,18 +383,18 @@ public abstract class Component boolean focusable = true; /** - * Tracks whether this component uses default focus traversal, or has a - * different policy. + * Tracks whether this component's {@link #isFocusTraversable} + * method has been overridden. * - * @see #isFocusTraversableOverridden() * @since 1.4 */ int isFocusTraversableOverridden; /** - * The focus traversal keys, if not inherited from the parent or default - * keyboard manager. These sets will contain only AWTKeyStrokes that - * represent press and release events to use as focus control. + * The focus traversal keys, if not inherited from the parent or + * default keyboard focus manager. These sets will contain only + * AWTKeyStrokes that represent press and release events to use as + * focus control. * * @see #getFocusTraversalKeys(int) * @see #setFocusTraversalKeys(int, Set) @@ -556,6 +556,12 @@ public abstract class Component */ transient BufferStrategy bufferStrategy; + /** + * true if requestFocus was called on this component when its + * top-level ancestor was not focusable. + */ + private transient FocusEvent pendingFocusRequest = null; + /** * The system properties that affect image updating. */ @@ -566,6 +572,8 @@ public abstract class Component { incrementalDraw = Boolean.getBoolean ("awt.image.incrementalDraw"); redrawRate = Long.getLong ("awt.image.redrawrate"); + // Set the default KeyboardFocusManager. + KeyboardFocusManager.setCurrentKeyboardFocusManager (null); } // Public and protected API. @@ -2963,6 +2971,7 @@ public abstract class Component { if (focusListener == null) return; + switch (e.id) { case FocusEvent.FOCUS_GAINED: @@ -3411,13 +3420,18 @@ public abstract class Component } /** - * Sets the focus traversal keys for a given type of focus events. Normally, - * the default values should match the operating system's native choices. To - * disable a given traversal, use Collections.EMPTY_SET. The - * event dispatcher will consume PRESSED, RELEASED, and TYPED events for the - * specified key, although focus can only transfer on PRESSED or RELEASED. + * Sets the focus traversal keys for one of the three focus + * traversal directions supported by Components: {@link + * #KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS}, {@link + * #KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS}, or {@link + * #KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS}. Normally, the + * default values should match the operating system's native + * choices. To disable a given traversal, use + * Collections.EMPTY_SET. The event dispatcher will + * consume PRESSED, RELEASED, and TYPED events for the specified + * key, although focus can only transfer on PRESSED or RELEASED. * - *

The defauts are: + *

The defaults are: * * * @@ -3430,10 +3444,13 @@ public abstract class Component * *
IdentifierMeaningDefault
KeyboardFocusManager.FORWARD_TRAVERSAL_KEYSGo up a traversal cycleNone
* - *

Specifying null allows inheritance from the parent, or from the current - * KeyboardFocusManager default set. If not null, the set must contain only - * AWTKeyStrokes that are not already focus keys and are not KEY_TYPED - * events. + * If keystrokes is null, this component's focus traversal key set + * is inherited from one of its ancestors. If none of its ancestors + * has its own set of focus traversal keys, the focus traversal keys + * are set to the defaults retrieved from the current + * KeyboardFocusManager. If not null, the set must contain only + * AWTKeyStrokes that are not already focus keys and are not + * KEY_TYPED events. * * @param id one of FORWARD_TRAVERSAL_KEYS, BACKWARD_TRAVERSAL_KEYS, or * UP_CYCLE_TRAVERSAL_KEYS @@ -3448,7 +3465,24 @@ public abstract class Component public void setFocusTraversalKeys(int id, Set keystrokes) { if (keystrokes == null) - throw new IllegalArgumentException(); + { + Container parent = getParent (); + + while (parent != null) + { + if (parent.areFocusTraversalKeysSet (id)) + { + keystrokes = parent.getFocusTraversalKeys (id); + break; + } + parent = parent.getParent (); + } + + if (keystrokes == null) + keystrokes = KeyboardFocusManager.getCurrentKeyboardFocusManager (). + getDefaultFocusTraversalKeys (id); + } + Set sa; Set sb; String name; @@ -3476,50 +3510,60 @@ public abstract class Component name = "upCycleFocusTraversalKeys"; break; default: - throw new IllegalArgumentException(); + throw new IllegalArgumentException (); } - int i = keystrokes.size(); - Iterator iter = keystrokes.iterator(); + + int i = keystrokes.size (); + Iterator iter = keystrokes.iterator (); + while (--i >= 0) { - Object o = iter.next(); - if (! (o instanceof AWTKeyStroke) - || sa.contains(o) || sb.contains(o) + Object o = iter.next (); + if (!(o instanceof AWTKeyStroke) + || sa.contains (o) || sb.contains (o) || ((AWTKeyStroke) o).keyCode == KeyEvent.VK_UNDEFINED) - throw new IllegalArgumentException(); + throw new IllegalArgumentException (); } + if (focusTraversalKeys == null) focusTraversalKeys = new Set[3]; - keystrokes = Collections.unmodifiableSet(new HashSet(keystrokes)); - firePropertyChange(name, focusTraversalKeys[id], keystrokes); + + keystrokes = Collections.unmodifiableSet (new HashSet (keystrokes)); + firePropertyChange (name, focusTraversalKeys[id], keystrokes); + focusTraversalKeys[id] = keystrokes; } /** - * Returns the set of keys for a given focus traversal action, as defined - * in setFocusTraversalKeys. If not set, this is inherited from - * the parent component, which may have gotten it from the - * KeyboardFocusManager. + * Returns the set of keys for a given focus traversal action, as + * defined in setFocusTraversalKeys. If not set, this + * is inherited from the parent component, which may have gotten it + * from the KeyboardFocusManager. * - * @param id one of FORWARD_TRAVERSAL_KEYS, BACKWARD_TRAVERSAL_KEYS, or - * UP_CYCLE_TRAVERSAL_KEYS + * @param id one of FORWARD_TRAVERSAL_KEYS, BACKWARD_TRAVERSAL_KEYS, + * or UP_CYCLE_TRAVERSAL_KEYS * @throws IllegalArgumentException if id is invalid - * @see #setFocusTraversalKeys(int, Set) + * @see #setFocusTraversalKeys (int, Set) * @see KeyboardFocusManager#FORWARD_TRAVERSAL_KEYS * @see KeyboardFocusManager#BACKWARD_TRAVERSAL_KEYS * @see KeyboardFocusManager#UP_CYCLE_TRAVERSAL_KEYS * @since 1.4 */ - public Set getFocusTraversalKeys(int id) + public Set getFocusTraversalKeys (int id) { - if (id < KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS - || id > KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS) + if (id != KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS && + id != KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS && + id != KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS) throw new IllegalArgumentException(); + Set s = null; + if (focusTraversalKeys != null) s = focusTraversalKeys[id]; + if (s == null && parent != null) - s = parent.getFocusTraversalKeys(id); + s = parent.getFocusTraversalKeys (id); + return s == null ? (KeyboardFocusManager.getCurrentKeyboardFocusManager() .getDefaultFocusTraversalKeys(id)) : s; } @@ -3528,269 +3572,417 @@ public abstract class Component * Tests whether the focus traversal keys for a given action are explicitly * set or inherited. * - * @param id one of FORWARD_TRAVERSAL_KEYS, BACKWARD_TRAVERSAL_KEYS, or - * UP_CYCLE_TRAVERSAL_KEYS + * @param id one of FORWARD_TRAVERSAL_KEYS, BACKWARD_TRAVERSAL_KEYS, + * or UP_CYCLE_TRAVERSAL_KEYS * @return true if that set is explicitly specified * @throws IllegalArgumentException if id is invalid - * @see #getFocusTraversalKeys(int) + * @see #getFocusTraversalKeys (int) * @see KeyboardFocusManager#FORWARD_TRAVERSAL_KEYS * @see KeyboardFocusManager#BACKWARD_TRAVERSAL_KEYS * @see KeyboardFocusManager#UP_CYCLE_TRAVERSAL_KEYS * @since 1.4 */ - public boolean areFocusTraversalKeysSet(int id) + public boolean areFocusTraversalKeysSet (int id) { - if (id < KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS - || id > KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS) - throw new IllegalArgumentException(); + if (id != KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS && + id != KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS && + id != KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS) + throw new IllegalArgumentException (); + return focusTraversalKeys != null && focusTraversalKeys[id] != null; } /** - * Sets whether focus traversal keys are enabled, which consumes traversal - * keys and performs the focus event automatically. + * Enable or disable focus traversal keys on this Component. If + * they are, then the keyboard focus manager consumes and acts on + * key press and release events that trigger focus traversal, and + * discards the corresponding key typed events. If focus traversal + * keys are disabled, then all key events that would otherwise + * trigger focus traversal are sent to this Component. * * @param focusTraversalKeysEnabled the new value of the flag - * @see #getFocusTraversalKeysEnabled() - * @see #setFocusTraversalKeys(int, Set) - * @see #getFocusTraversalKeys(int) + * @see #getFocusTraversalKeysEnabled () + * @see #setFocusTraversalKeys (int, Set) + * @see #getFocusTraversalKeys (int) * @since 1.4 */ - public void setFocusTraversalKeysEnabled(boolean focusTraversalKeysEnabled) + public void setFocusTraversalKeysEnabled (boolean focusTraversalKeysEnabled) { - firePropertyChange("focusTraversalKeysEnabled", - this.focusTraversalKeysEnabled, - focusTraversalKeysEnabled); + firePropertyChange ("focusTraversalKeysEnabled", + this.focusTraversalKeysEnabled, + focusTraversalKeysEnabled); this.focusTraversalKeysEnabled = focusTraversalKeysEnabled; } /** - * Tests whether focus traversal keys are enabled. If they are, then focus - * traversal keys are consumed and focus events performed automatically, - * without the component seeing the keystrokes. + * Check whether or not focus traversal keys are enabled on this + * Component. If they are, then the keyboard focus manager consumes + * and acts on key press and release events that trigger focus + * traversal, and discards the corresponding key typed events. If + * focus traversal keys are disabled, then all key events that would + * otherwise trigger focus traversal are sent to this Component. * - * @return true if focus traversal is enabled - * @see #setFocusTraversalKeysEnabled(boolean) - * @see #setFocusTraversalKeys(int, Set) - * @see #getFocusTraversalKeys(int) + * @return true if focus traversal keys are enabled + * @see #setFocusTraversalKeysEnabled (boolean) + * @see #setFocusTraversalKeys (int, Set) + * @see #getFocusTraversalKeys (int) * @since 1.4 */ - public boolean getFocusTraversalKeysEnabled() + public boolean getFocusTraversalKeysEnabled () { return focusTraversalKeysEnabled; } /** - * Requests that this component be given focus. A FOCUS_GAINED - * event will be fired if and only if this request is successful. To be - * successful, the component must be displayable, visible, and focusable, - * and the top-level Window must be able to receive focus. Thus, this - * request may fail, or be delayed until the window receives focus. It is - * recommended that requestFocusInWindow be used where - * possible to be more platform-independent. + * Request that this Component be given the keyboard input focus and + * that its top-level ancestor become the focused Window. + * + * For the request to be granted, the Component must be focusable, + * displayable and showing and the top-level Window to which it + * belongs must be focusable. If the request is initially denied on + * the basis that the top-level Window is not focusable, the request + * will be remembered and granted when the Window does become + * focused. + * + * Never assume that this Component is the focus owner until it + * receives a FOCUS_GAINED event. * - * @see #requestFocusInWindow() + * The behaviour of this method is platform-dependent. + * {@link #requestFocusInWindow} should be used instead. + * + * @see #requestFocusInWindow () * @see FocusEvent - * @see #addFocusListener(FocusListener) - * @see #isFocusable() - * @see #isDisplayable() - * @see KeyboardFocusManager#clearGlobalFocusOwner() + * @see #addFocusListener (FocusListener) + * @see #isFocusable () + * @see #isDisplayable () + * @see KeyboardFocusManager#clearGlobalFocusOwner () */ - public void requestFocus() + public void requestFocus () { - // If there's no peer then this component can't get the focus. We - // treat it as a silent rejection of the request. - if (peer != null) - peer.requestFocus(); + if (isDisplayable () + && isShowing () + && isFocusable ()) + { + synchronized (getTreeLock ()) + { + // Find this Component's top-level ancestor. + Container parent = getParent (); + + while (parent != null + && !(parent instanceof Window)) + parent = parent.getParent (); + + Window toplevel = (Window) parent; + if (toplevel.isFocusableWindow ()) + { + if (peer != null) + // This call will cause a FOCUS_GAINED event to be + // posted to the system event queue if the native + // windowing system grants the focus request. + peer.requestFocus (); + else + { + // Either our peer hasn't been created yet or we're a + // lightweight component. In either case we want to + // post a FOCUS_GAINED event. + EventQueue eq = Toolkit.getDefaultToolkit ().getSystemEventQueue (); + eq.postEvent (new FocusEvent(this, FocusEvent.FOCUS_GAINED)); + } + } + else + pendingFocusRequest = new FocusEvent(this, FocusEvent.FOCUS_GAINED); + } + } } /** - * Requests that this component be given focus. A FOCUS_GAINED - * event will be fired if and only if this request is successful. To be - * successful, the component must be displayable, visible, and focusable, - * and the top-level Window must be able to receive focus. Thus, this - * request may fail, or be delayed until the window receives focus. It is - * recommended that requestFocusInWindow be used where - * possible to be more platform-independent. + * Request that this Component be given the keyboard input focus and + * that its top-level ancestor become the focused Window. + * + * For the request to be granted, the Component must be focusable, + * displayable and showing and the top-level Window to which it + * belongs must be focusable. If the request is initially denied on + * the basis that the top-level Window is not focusable, the request + * will be remembered and granted when the Window does become + * focused. + * + * Never assume that this Component is the focus owner until it + * receives a FOCUS_GAINED event. + * + * The behaviour of this method is platform-dependent. + * {@link #requestFocusInWindow} should be used instead. * - *

If the return value is false, the request is guaranteed to fail. If - * it is true, it will likely succeed unless the action is vetoed or - * something in the native windowing system intervenes. The temporary flag, - * and thus this method in general, is not designed for public use; rather - * it is a hook for lightweight components to notify their container in - * an attempt to reduce the amount of repainting necessary. + * If the return value is false, the request is guaranteed to fail. + * If the return value is true, the request will succeed unless it + * is vetoed or something in the native windowing system intervenes, + * preventing this Component's top-level ancestor from becoming + * focused. This method is meant to be called by derived + * lightweight Components that want to avoid unnecessary repainting + * when they know a given focus transfer need only be temporary. * * @param temporary true if the focus request is temporary * @return true if the request has a chance of success - * @see #requestFocusInWindow() + * @see #requestFocusInWindow () * @see FocusEvent - * @see #addFocusListener(FocusListener) - * @see #isFocusable() - * @see #isDisplayable() - * @see KeyboardFocusManager#clearGlobalFocusOwner() + * @see #addFocusListener (FocusListener) + * @see #isFocusable () + * @see #isDisplayable () + * @see KeyboardFocusManager#clearGlobalFocusOwner () * @since 1.4 */ - protected boolean requestFocus(boolean temporary) + protected boolean requestFocus (boolean temporary) { - // XXX Implement correctly. - requestFocus(); + if (isDisplayable () + && isShowing () + && isFocusable ()) + { + synchronized (getTreeLock ()) + { + // Find this Component's top-level ancestor. + Container parent = getParent (); + + while (parent != null + && !(parent instanceof Window)) + parent = parent.getParent (); + + Window toplevel = (Window) parent; + if (toplevel.isFocusableWindow ()) + { + if (peer != null) + // This call will cause a FOCUS_GAINED event to be + // posted to the system event queue if the native + // windowing system grants the focus request. + peer.requestFocus (); + else + { + // Either our peer hasn't been created yet or we're a + // lightweight component. In either case we want to + // post a FOCUS_GAINED event. + EventQueue eq = Toolkit.getDefaultToolkit ().getSystemEventQueue (); + eq.postEvent (new FocusEvent(this, FocusEvent.FOCUS_GAINED, temporary)); + } + } + else + // FIXME: need to add a focus listener to our top-level + // ancestor, so that we can post this event when it becomes + // the focused window. + pendingFocusRequest = new FocusEvent(this, FocusEvent.FOCUS_GAINED, temporary); + } + } + // Always return true. return true; } /** - * Requests that this component be given focus, if it resides in the - * top-level window which already has focus. A FOCUS_GAINED - * event will be fired if and only if this request is successful. To be - * successful, the component must be displayable, visible, and focusable, - * and the top-level Window must be focused. + * Request that this component be given the keyboard input focus, if + * its top-level ancestor is the currently focused Window. A + * FOCUS_GAINED event will be fired if and only if this + * request is successful. To be successful, the component must be + * displayable, showing, and focusable, and its ancestor top-level + * Window must be focused. * - *

If the return value is false, the request is guaranteed to fail. If - * it is true, it will likely succeed unless the action is vetoed or - * something in the native windowing system intervenes. The temporary flag, - * and thus this method in general, is not designed for public use; rather - * it is a hook for lightweight components to notify their container in - * an attempt to reduce the amount of repainting necessary. + * If the return value is false, the request is guaranteed to fail. + * If the return value is true, the request will succeed unless it + * is vetoed or something in the native windowing system intervenes, + * preventing this Component's top-level ancestor from becoming + * focused. * * @return true if the request has a chance of success - * @see #requestFocus() + * @see #requestFocus () * @see FocusEvent - * @see #addFocusListener(FocusListener) - * @see #isFocusable() - * @see #isDisplayable() - * @see KeyboardFocusManager#clearGlobalFocusOwner() + * @see #addFocusListener (FocusListener) + * @see #isFocusable () + * @see #isDisplayable () + * @see KeyboardFocusManager#clearGlobalFocusOwner () * @since 1.4 */ - public boolean requestFocusInWindow() + public boolean requestFocusInWindow () { - // XXX Implement correctly. - requestFocus(); - return true; + return requestFocusInWindow (false); } /** - * Requests that this component be given focus, if it resides in the - * top-level window which already has focus. A FOCUS_GAINED - * event will be fired if and only if this request is successful. To be - * successful, the component must be displayable, visible, and focusable, - * and the top-level Window must be focused. + * Request that this component be given the keyboard input focus, if + * its top-level ancestor is the currently focused Window. A + * FOCUS_GAINED event will be fired if and only if this + * request is successful. To be successful, the component must be + * displayable, showing, and focusable, and its ancestor top-level + * Window must be focused. * - *

If the return value is false, the request is guaranteed to fail. If - * it is true, it will likely succeed unless the action is vetoed or - * something in the native windowing system intervenes. The temporary flag, - * and thus this method in general, is not designed for public use; rather - * it is a hook for lightweight components to notify their container in - * an attempt to reduce the amount of repainting necessary. + * If the return value is false, the request is guaranteed to fail. + * If the return value is true, the request will succeed unless it + * is vetoed or something in the native windowing system intervenes, + * preventing this Component's top-level ancestor from becoming + * focused. This method is meant to be called by derived + * lightweight Components that want to avoid unnecessary repainting + * when they know a given focus transfer need only be temporary. * * @param temporary true if the focus request is temporary * @return true if the request has a chance of success - * @see #requestFocus() + * @see #requestFocus () * @see FocusEvent - * @see #addFocusListener(FocusListener) - * @see #isFocusable() - * @see #isDisplayable() - * @see KeyboardFocusManager#clearGlobalFocusOwner() + * @see #addFocusListener (FocusListener) + * @see #isFocusable () + * @see #isDisplayable () + * @see KeyboardFocusManager#clearGlobalFocusOwner () * @since 1.4 */ - protected boolean requestFocusInWindow(boolean temporary) + protected boolean requestFocusInWindow (boolean temporary) { - // XXX Implement correctly. - requestFocus(); - return true; + KeyboardFocusManager manager = KeyboardFocusManager.getCurrentKeyboardFocusManager (); + + Window focusedWindow = manager.getFocusedWindow (); + + if (isDisplayable () + && isShowing () + && isFocusable ()) + { + if (focusedWindow != null) + { + synchronized (getTreeLock ()) + { + Container parent = getParent (); + + while (parent != null + && !(parent instanceof Window)) + parent = parent.getParent (); + + Window toplevel = (Window) parent; + + // Check if top-level ancestor is currently focused window. + if (focusedWindow == toplevel) + { + if (peer != null) + // This call will cause a FOCUS_GAINED event to be + // posted to the system event queue if the native + // windowing system grants the focus request. + peer.requestFocus (); + else + { + // Either our peer hasn't been created yet or we're a + // lightweight component. In either case we want to + // post a FOCUS_GAINED event. + EventQueue eq = Toolkit.getDefaultToolkit ().getSystemEventQueue (); + eq.postEvent (new FocusEvent(this, FocusEvent.FOCUS_GAINED, temporary)); + } + } + else + return false; + } + } + + return true; + } + return false; } /** - * Transfers focus to the next component in the focus traversal order, as - * though this were the current focus owner. + * Transfers focus to the next component in the focus traversal + * order, as though this were the current focus owner. * * @see #requestFocus() * @since 1.1 */ - public void transferFocus() + public void transferFocus () { - Component next; - if (parent == null) - next = findNextFocusComponent(null); - else - next = parent.findNextFocusComponent(this); - if (next != null && next != this) - next.requestFocus(); + nextFocus (); } /** - * Returns the root container that owns the focus cycle where this component - * resides. A focus cycle root is in two cycles, one as the ancestor, and - * one as the focusable element; this call always returns the ancestor. + * Returns the root container that owns the focus cycle where this + * component resides. A focus cycle root is in two cycles, one as + * the ancestor, and one as the focusable element; this call always + * returns the ancestor. * * @return the ancestor container that owns the focus cycle * @since 1.4 */ - public Container getFocusCycleRootAncestor() + public Container getFocusCycleRootAncestor () { - // XXX Implement. - throw new Error("not implemented"); + if (this instanceof Window + && ((Container) this).isFocusCycleRoot ()) + return (Container) this; + + Container parent = getParent (); + + while (parent != null + && !parent.isFocusCycleRoot ()) + parent = parent.getParent (); + + return parent; } /** - * Tests if the container is the ancestor of the focus cycle that this - * component belongs to. + * Tests if the container is the ancestor of the focus cycle that + * this component belongs to. * * @param c the container to test * @return true if c is the focus cycle root * @since 1.4 */ - public boolean isFocusCycleRoot(Container c) + public boolean isFocusCycleRoot (Container c) { - return c == getFocusCycleRootAncestor(); + return c == getFocusCycleRootAncestor (); } /** - * AWT 1.0 focus event processor. + * AWT 1.0 focus event processor. Transfers focus to the next + * component in the focus traversal order, as though this were the + * current focus owner. * - * @deprecated use {@link #transferFocus()} instead + * @deprecated use {@link #transferFocus ()} instead */ - public void nextFocus() + public void nextFocus () { - transferFocus(); + KeyboardFocusManager manager = KeyboardFocusManager.getCurrentKeyboardFocusManager (); + + manager.focusNextComponent (this); } /** - * Transfers focus to the previous component in the focus traversal order, as - * though this were the current focus owner. + * Transfers focus to the previous component in the focus traversal + * order, as though this were the current focus owner. * - * @see #requestFocus() + * @see #requestFocus () * @since 1.4 */ - public void transferFocusBackward() + public void transferFocusBackward () { - // XXX Implement. - throw new Error("not implemented"); + KeyboardFocusManager manager = KeyboardFocusManager.getCurrentKeyboardFocusManager (); + + manager.focusPreviousComponent (this); } /** - * Transfers focus to the focus cycle root of this component. However, if - * this is a Window, the default focus owner in the window in the current - * focus cycle is focused instead. + * Transfers focus to the focus cycle root of this component. + * However, if this is a Window, the default focus owner in the + * window in the current focus cycle is focused instead. * - * @see #requestFocus() - * @see #isFocusCycleRoot() + * @see #requestFocus () + * @see #isFocusCycleRoot () * @since 1.4 */ - public void transferFocusUpCycle() + public void transferFocusUpCycle () { - // XXX Implement. - throw new Error("not implemented"); + KeyboardFocusManager manager = KeyboardFocusManager.getCurrentKeyboardFocusManager (); + + manager.upFocusCycle (this); } /** - * Tests if this component is the focus owner. Use {@link #isFocusOwner()} - * instead. + * Tests if this component is the focus owner. Use {@link + * #isFocusOwner ()} instead. * * @return true if this component owns focus * @since 1.2 */ - public boolean hasFocus() + public boolean hasFocus () { - return isFocusOwner(); + KeyboardFocusManager manager = KeyboardFocusManager.getCurrentKeyboardFocusManager (); + + Component focusOwner = manager.getFocusOwner (); + + return this == focusOwner; } /** @@ -3801,8 +3993,7 @@ public abstract class Component */ public boolean isFocusOwner() { - // XXX Implement. - throw new Error("not implemented"); + return hasFocus (); } /** @@ -4337,6 +4528,8 @@ p *

  • the set of backward traversal keys * making the request. This is overridden by Container; when called for an * ordinary component there is no child and so we always return null. * + * FIXME: is this still needed, in light of focus traversal policies? + * * @param child the component making the request * @return the next component to focus on */ @@ -4897,23 +5090,23 @@ p *
  • the set of backward traversal keys * Tests whether this component can accept focus. * * @return true if this is focus traversable - * @see #getAccessibleStateSet() + * @see #getAccessibleStateSet () * @see AccessibleState#FOCUSABLE * @see AccessibleState#FOCUSED */ - public boolean isFocusTraversable() + public boolean isFocusTraversable () { - return Component.this.isFocusTraversable(); + return Component.this.isFocusTraversable (); } /** * Requests focus for this component. * - * @see #isFocusTraversable() + * @see #isFocusTraversable () */ - public void requestFocus() + public void requestFocus () { - Component.this.requestFocus(); + Component.this.requestFocus (); } /** -- cgit v1.2.3