changeset 1785:e5267f8c80af

Automated merge with ssh://jfxsrc.us.oracle.com//javafx/8.0/MASTER/jfx/rt
author kcr
date Wed, 26 Sep 2012 17:45:12 -0700
parents 174647284655 a30e7be8621e
children 7ee6a11abbbf
files
diffstat 2 files changed, 62 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- a/javafx-ui-common/src/com/sun/javafx/embed/EmbeddedStageInterface.java	Tue Sep 25 13:06:21 2012 -0700
+++ b/javafx-ui-common/src/com/sun/javafx/embed/EmbeddedStageInterface.java	Wed Sep 26 17:45:12 2012 -0700
@@ -46,4 +46,9 @@
      * traversed forward in the focus chain in embedding app. 
      */
     public void setFocused(boolean focused, int focusCause);
+
+    /*
+     * FOCUS_UNGRAB notification.
+     */
+    public void focusUngrab();
 }
--- a/javafx-ui-common/src/com/sun/javafx/embed/HostInterface.java	Tue Sep 25 13:06:21 2012 -0700
+++ b/javafx-ui-common/src/com/sun/javafx/embed/HostInterface.java	Wed Sep 26 17:45:12 2012 -0700
@@ -82,4 +82,61 @@
      * Called by embedded FX scene when its cursor is changed.
      */
     public void setCursor(CursorFrame cursorFrame);
+
+    /**
+     * Grabs focus on this window.
+     *
+     * All mouse clicks that occur in this window's client area or client-areas
+     * of any of its unfocusable owned windows are delivered as usual. Whenever
+     * a click occurs on another app's window (not related via the ownership
+     * relation with this one, or a focusable owned window), or on non-client
+     * area of any window (titlebar, etc.), or any third-party app's window, or
+     * native OS GUI (e.g. a taskbar), the grab is automatically reset, and the
+     * window that held the grab receives the FOCUS_UNGRAB event.
+     *
+     * Note that for this functionality to work correctly, the window must have
+     * a focus upon calling this method. All owned popup windows that should be
+     * operable during the grabbed focus state (e.g. nested popup menus) must
+     * be unfocusable (see {@link #setFocusable}). Clicking a focusable owned
+     * window will reset the grab due to a focus transfer.
+     *
+     * The click that occurs in another window and causes resetting of the grab
+     * may or may not be delivered to that other window depending on the native
+     * OS behavior.
+     *
+     * If any of the application's windows already holds the grab, it is reset
+     * prior to grabbing the focus for this window. The method may be called
+     * multiple times for one window. Subsequent calls do not affect the grab
+     * status unless it is reset between the calls, in which case the focus
+     * is grabbed again.
+     *
+     * Note that grabbing the focus on an application window may prevent
+     * delivering certain events to other applications until the grab is reset.
+     * Therefore, if the application has finished showing popup windows based
+     * on a user action (e.g. clicking a menu item), and doesn't require the
+     * grab any more, it should call the {@link #ungrabFocus} method. The
+     * FOCUS_UNGRAB event signals that the grab has been reset.
+     *
+     * A user event handler associated with a menu item must be invoked after
+     * resetting the grab. Otherwise, if a developer debugs the application and
+     * has installed a breakpoint in the event handler, the debugger may become
+     * unoperable due to events blocking for other applications on some
+     * platforms.
+     *
+     * @return {@code true} if the operation is successful
+     * @throws IllegalStateException if the window isn't focused currently
+     */
+    public boolean grabFocus();
+
+    /**
+     * Manually ungrabs focus grabbed on this window previously.
+     *
+     * This method resets the grab, and forces sending of the FOCUS_UNGRAB
+     * event. It should be used when popup windows (such as menus) should be
+     * dismissed manually, e.g. when a user clicks a menu item which usually
+     * causes the menus to hide.
+     *
+     * @see #grabFocus
+     */
+    public void ungrabFocus();
 }