Interface Window

  • All Superinterfaces:
    NativeSurface, NativeSurfaceHolder, NativeWindow, ScalableSurface, SurfaceUpdatedListener, WindowClosingProtocol
    All Known Implementing Classes:
    GLWindow

    public interface Window
    extends NativeWindow, WindowClosingProtocol, ScalableSurface
    Specifying NEWT's Window functionality:
    • On- and offscreen windows
    • Keyboard and multi-pointer input
    • Native reparenting
    • Toggable fullscreen and decoration mode
    • Transparency
    • ... and more

    One use case is GLWindow, which delegates window operation to an instance of this interface while providing OpenGL functionality.

    All values of this interface are represented in window units, if not stated otherwise.

    Coordinate System

    • Screen space has it's origin in the top-left corner, and may not be at 0/0.
    • Window origin is in it's top-left corner, see NativeWindow.getX() and NativeWindow.getY().
    • Window client-area excludes insets, i.e. window decoration.
    • Window origin is relative to it's parent window if exist, or the screen position (top-level).
    See NativeWindow and Screen.

    Custom Window Icons

    Custom window icons can be defined via system property newt.window.icons, which shall contain a list of PNG icon locations from low- to high-resolution, separated by one whitespace or one comma character. The location must be resolvable via classpath, i.e. shall reference a location within the jar file. Example (our default):

       -Dnewt.window.icons="newt/data/jogamp-16x16.png,newt/data/jogamp-32x32.png"
       -Djnlp.newt.window.icons="newt/data/jogamp-16x16.png,newt/data/jogamp-32x32.png"
     
    The property can also be set programmatically, which must happen before any NEWT classes are touched:
       System.setProperty("newt.window.icons", "newt/data/jogamp-16x16.png, newt/data/jogamp-32x32.png");
     
    To disable even Jogamp's own window icons in favor of system icons, simply set a non-existing location, e.g.:
       -Dnewt.window.icons="null,null"
     

    Use of Lifecycle Heavy functions

    Some of the methods specified here are lifecycle-heavy. That is, they are able to destroy and/or reattach resources to/from the window. Because of this, the methods are not safe to be called from EDT related threads. For example, it is not safe for a method in an attached KeyListener to call setFullscreen(boolean) on a Window directly. It is safe, however, for that method to spawn a background worker thread which calls the method directly. The documentation for individual methods indicates whether or not they are lifecycle-heavy.

    • Field Detail

      • DEBUG_MOUSE_EVENT

        static final boolean DEBUG_MOUSE_EVENT
      • DEBUG_KEY_EVENT

        static final boolean DEBUG_KEY_EVENT
      • DEBUG_IMPLEMENTATION

        static final boolean DEBUG_IMPLEMENTATION
      • STATE_BIT_VISIBLE

        static final int STATE_BIT_VISIBLE
        Visibility of this instance.

        Native instance gets created at first visibility, following NEWT's lazy creation pattern.

        Changing this state is lifecycle heavy.

        Bit number 0.

        Defaults to false.

        Since:
        2.3.2
        See Also:
        getStateMask(), Constant Field Values
      • STATE_BIT_AUTOPOSITION

        static final int STATE_BIT_AUTOPOSITION
        Hinting that no custom position has been set before first visibility of this instance.

        If kept false at creation, this allows the WM to choose the top-level window position, otherwise the custom position is being enforced.

        Bit number 1.

        Defaults to true.

        Since:
        2.3.2
        See Also:
        getStateMask(), Constant Field Values
      • STATE_BIT_CHILDWIN

        static final int STATE_BIT_CHILDWIN
        Set if window is a child window, i.e. has been reparented.

        Otherwise bit is cleared, i.e. window is top-level.

        Changing this state is lifecycle heavy.

        Bit number 2.

        Defaults to false.

        Since:
        2.3.2
        See Also:
        getStateMask(), Constant Field Values
      • STATE_BIT_FOCUSED

        static final int STATE_BIT_FOCUSED
        Set if window has the input focus, otherwise cleared.

        Bit number 3.

        Defaults to false.

        Since:
        2.3.2
        See Also:
        getStateMask(), Constant Field Values
      • STATE_BIT_UNDECORATED

        static final int STATE_BIT_UNDECORATED
        Set if window has window decorations, otherwise cleared.

        Bit number 4.

        Defaults to false.

        Since:
        2.3.2
        See Also:
        getStateMask(), Constant Field Values
      • STATE_BIT_ALWAYSONTOP

        static final int STATE_BIT_ALWAYSONTOP
        Set if window is always on top, otherwise cleared.

        Bit number 5.

        Defaults to false.

        Since:
        2.3.2
        See Also:
        getStateMask(), Constant Field Values
      • STATE_BIT_ALWAYSONBOTTOM

        static final int STATE_BIT_ALWAYSONBOTTOM
        Set if window is always on bottom, otherwise cleared.

        Bit number 6.

        Defaults to false.

        Since:
        2.3.2
        See Also:
        getStateMask(), Constant Field Values
      • STATE_BIT_STICKY

        static final int STATE_BIT_STICKY
        Set if window is sticky, i.e. visible on all virtual desktop, otherwise cleared.

        Bit number 7.

        Defaults to false.

        Since:
        2.3.2
        See Also:
        getStateMask(), Constant Field Values
      • STATE_BIT_RESIZABLE

        static final int STATE_BIT_RESIZABLE
        Set if window is resizable, otherwise cleared.

        Bit number 8.

        Defaults to true.

        Since:
        2.3.2
        See Also:
        getStateMask(), Constant Field Values
      • STATE_BIT_MAXIMIZED_VERT

        static final int STATE_BIT_MAXIMIZED_VERT
        Set if window is maximized vertically, otherwise cleared.

        Bit number 9.

        Defaults to false.

        Since:
        2.3.2
        See Also:
        getStateMask(), Constant Field Values
      • STATE_BIT_MAXIMIZED_HORZ

        static final int STATE_BIT_MAXIMIZED_HORZ
        Set if window is maximized horizontally, otherwise cleared.

        Bit number 10.

        Defaults to false.

        Since:
        2.3.2
        See Also:
        getStateMask(), Constant Field Values
      • STATE_BIT_FULLSCREEN

        static final int STATE_BIT_FULLSCREEN
        Set if window is in fullscreen mode, otherwise cleared.

        Usually fullscreen mode implies STATE_BIT_UNDECORATED, however, an implementation is allowed to ignore this if unavailable.

        Bit number 11.

        Defaults to false.

        Since:
        2.3.2
        See Also:
        getStateMask(), Constant Field Values
      • STATE_BIT_POINTERVISIBLE

        static final int STATE_BIT_POINTERVISIBLE
        Set if the pointer is visible when inside the window, otherwise cleared.

        Bit number 12.

        Defaults to true.

        Since:
        2.3.2
        See Also:
        getStateMask(), Constant Field Values
      • STATE_BIT_POINTERCONFINED

        static final int STATE_BIT_POINTERCONFINED
        Set if the pointer is confined to the window, otherwise cleared.

        Bit number 13.

        Defaults to false.

        Since:
        2.3.2
        See Also:
        getStateMask(), Constant Field Values
      • REPARENT_HINT_FORCE_RECREATION

        static final int REPARENT_HINT_FORCE_RECREATION
        Reparenting hint (bitfield value): Force destroy and hence re-creating the window.
        See Also:
        Constant Field Values
      • REPARENT_HINT_BECOMES_VISIBLE

        static final int REPARENT_HINT_BECOMES_VISIBLE
        Reparenting hint (bitfield value): Claim window becomes visible after reparenting, which is important for e.g. preserving the GL-states in case window is invisible while reparenting.
        See Also:
        Constant Field Values
    • Method Detail

      • getStatePublicBitCount

        int getStatePublicBitCount()
        Number of all public state bits.
        Since:
        2.3.2
        See Also:
        getStateMask()
      • getStatePublicBitmask

        int getStatePublicBitmask()
        Bitmask covering all public state bits.
        Since:
        2.3.2
        See Also:
        getStateMask()
      • getStateMaskString

        String getStateMaskString()
        Returns a string representation of the current state mask.
        Since:
        2.3.2
      • getSupportedStateMaskString

        String getSupportedStateMaskString()
        Returns a string representation of the supported state mask.
        Since:
        2.3.2
      • isNativeValid

        boolean isNativeValid()
        Returns:
        true if the native window handle is valid and ready to operate, ie if the native window has been created via setVisible(true), otherwise false.
        See Also:
        setVisible(boolean), #destroy(boolean)
      • getScreen

        Screen getScreen()
        Returns:
        The associated Screen
      • setCapabilitiesChooser

        CapabilitiesChooser setCapabilitiesChooser​(CapabilitiesChooser chooser)
        Set the CapabilitiesChooser to help determine the native visual type.
        Parameters:
        chooser - the new CapabilitiesChooser
        Returns:
        the previous CapabilitiesChooser
      • getRequestedCapabilities

        CapabilitiesImmutable getRequestedCapabilities()
        Gets an immutable set of requested capabilities.
        Returns:
        the requested capabilities
      • getChosenCapabilities

        CapabilitiesImmutable getChosenCapabilities()
        Gets an immutable set of chosen capabilities.
        Returns:
        the chosen capabilities
      • setWindowDestroyNotifyAction

        void setWindowDestroyNotifyAction​(Runnable r)
        Set a custom action handling destruction issued by a toolkit triggered window destroy replacing the default destroy() action.

        The custom action shall call destroy() but may perform further tasks before and after.

      • setVisible

        void setVisible​(boolean wait,
                        boolean visible)
        setVisible(..) makes the window and children visible if visible is true, otherwise the window and children becomes invisible.

        Native instance gets created at first visibility, following NEWT's lazy creation pattern.

        If wait is true, method blocks until window is visible and valid, otherwise method returns immediately.

        Zero size semantics are respected, see setSize(int,int):

         if ( 0 == windowHandle && visible ) {
           this.visible = visible;
           if( 0 < width && 0 < height ) {
             createNative();
           }
         } else if ( this.visible != visible ) {
           this.visible = visible;
           setNativeSizeImpl();
         }
         

        In case this window is a child window and has a NativeWindow parent,
        setVisible(wait, true) has no effect as long the parent's is not valid yet, i.e. NativeWindow.getWindowHandle() returns null.
        setVisible(wait, true) shall be repeated when the parent becomes valid.

        This method is lifecycle heavy.

        See Also:
        STATE_BIT_VISIBLE
      • getDelegatedWindow

        Window getDelegatedWindow()
        If the implementation uses delegation, return the delegated Window instance, otherwise return this instance.
      • getPixelsPerMM

        float[] getPixelsPerMM​(float[] ppmmStore)
        Returns the pixels per millimeter of this window's NativeSurface according to the main monitor's current mode's surface resolution.

        Method takes the current surface-scale and native surface-scale into account, i.e.:

            surfacePpMM = monitorPpMM * currentSurfaceScale / nativeSurfaceScale,
            with PpMM == pixel per millimeter
         

        To convert the result to dpi, i.e. dots-per-inch, multiply both components with 25.4f.

        Parameters:
        ppmmStore - float[2] storage for the ppmm result
        Returns:
        the passed storage containing the ppmm for chaining
      • setSize

        void setSize​(int width,
                     int height)
        Sets the size of the window's client area in window units, excluding decorations.

        Zero size semantics are respected, see setVisible(boolean):

         if ( visible && 0 != windowHandle && ( 0 ≥ width || 0 ≥ height ) ) {
           setVisible(false);
         } else if ( visible && 0 == windowHandle && 0 < width && 0 < height ) {
           setVisible(true);
         } else {
           // as expected ..
         }
         

        This call is ignored if in fullscreen mode.

        Parameters:
        width - of the window's client area in window units
        height - of the window's client area in window units
        See Also:
        setSurfaceSize(int, int), setTopLevelSize(int, int), NativeWindow.getInsets()
      • setSurfaceSize

        void setSurfaceSize​(int pixelWidth,
                            int pixelHeight)
        Sets the size of the window's surface in pixel units which claims the window's client area excluding decorations.

        In multiple monitor mode, setting the window's surface size in pixel units might not be possible due to unknown scale values of the target display. Hence re-setting the pixel unit size after window creation is recommended.

        Zero size semantics are respected, see setVisible(boolean):

         if ( visible && 0 != windowHandle && ( 0 ≥ width || 0 ≥ height ) ) {
           setVisible(false);
         } else if ( visible && 0 == windowHandle && 0 < width && 0 < height ) {
           setVisible(true);
         } else {
           // as expected ..
         }
         

        This call is ignored if in fullscreen mode.

        Parameters:
        pixelWidth - of the window's client area in pixel units
        pixelHeight - of the window's client area in pixel units
        See Also:
        setSize(int, int), NativeWindow.getInsets()
      • setTopLevelSize

        void setTopLevelSize​(int width,
                             int height)
        Sets the size of the top-level window including insets (window decorations) in window units.

        Note: Insets (if supported) are available only after the window is set visible and hence has been created.

        Parameters:
        width - of the top-level window area in window units
        height - of the top-level window area in window units
        See Also:
        setSize(int, int), NativeWindow.getInsets()
      • setPosition

        void setPosition​(int x,
                         int y)
        Sets the location of the window's client area excluding insets (window decorations) in window units.
        This call is ignored if in fullscreen mode.
        Parameters:
        x - coord of the client-area's top left corner in window units
        y - coord of the client-area's top left corner in window units
        See Also:
        NativeWindow.getInsets()
      • setTopLevelPosition

        void setTopLevelPosition​(int x,
                                 int y)
        Sets the location of the top-level window inclusive insets (window decorations) in window units.

        Note: Insets (if supported) are available only after the window is set visible and hence has been created.

        This call is ignored if in fullscreen mode.
        Parameters:
        x - coord of the top-level left corner in window units
        y - coord of the top-level left corner in window units
        See Also:
        setPosition(int, int), NativeWindow.getInsets()
      • setUndecorated

        void setUndecorated​(boolean value)
      • isUndecorated

        boolean isUndecorated()
      • setAlwaysOnTop

        void setAlwaysOnTop​(boolean value)

        Operation is ignored if this instance is a child window.

      • isAlwaysOnTop

        boolean isAlwaysOnTop()
      • setAlwaysOnBottom

        void setAlwaysOnBottom​(boolean value)

        Operation is ignored if this instance is a child window.

        Since:
        2.3.2
      • isAlwaysOnBottom

        boolean isAlwaysOnBottom()
        Since:
        2.3.2
      • setResizable

        void setResizable​(boolean value)

        Operation is ignored if this instance is a child window.

        Since:
        2.3.2
      • isResizable

        boolean isResizable()
        Since:
        2.3.2
      • setSticky

        void setSticky​(boolean value)

        Operation is ignored if this instance is a child window.

        Since:
        2.3.2
      • isSticky

        boolean isSticky()
        Since:
        2.3.2
      • setMaximized

        void setMaximized​(boolean horz,
                          boolean vert)

        Operation is ignored if this instance is a child window.

        Since:
        2.3.2
      • isMaximizedVert

        boolean isMaximizedVert()
        Since:
        2.3.2
      • isMaximizedHorz

        boolean isMaximizedHorz()
        Since:
        2.3.2
      • setTitle

        void setTitle​(String title)
      • setPointerVisible

        void setPointerVisible​(boolean pointerVisible)
        Makes the pointer visible or invisible.
        Parameters:
        pointerVisible - defaults to true for platforms w/ visible pointer, otherwise defaults to true, eg. Android.
        See Also:
        confinePointer(boolean)
      • confinePointer

        void confinePointer​(boolean confine)
        Confine the pointer to this window, ie. pointer jail.

        Before jailing the mouse pointer, the window request the focus and the pointer is centered in the window.

        In combination w/ warpPointer(int, int) and maybe setPointerVisible(boolean) a simple mouse navigation can be realized.

        Parameters:
        confine - defaults to false.
      • warpPointer

        void warpPointer​(int x,
                         int y)
        Moves the pointer to x/y relative to this window's origin in pixel units.
        Parameters:
        x - relative pointer x position within this window in pixel units
        y - relative pointer y position within this window in pixel units
        See Also:
        confinePointer(boolean)
      • reparentWindow

        Window.ReparentOperation reparentWindow​(NativeWindow newParent,
                                                int x,
                                                int y,
                                                int hints)
        Change this window's parent window.

        In case the old parent is not null and a Window, this window is removed from it's list of children.
        In case the new parent is not null and a Window, this window is added to it's list of children.

        This method is lifecycle heavy.

        Parameters:
        newParent - The new parent NativeWindow. If null, this Window becomes a top level window.
        x - new top-level position in window units, use -1 for default position.
        y - new top-level position in window units, use -1 for default position.
        hints - May contain hints (bitfield values) like REPARENT_HINT_FORCE_RECREATION or REPARENT_HINT_BECOMES_VISIBLE.
        Returns:
        The issued reparent action type (strategy) as defined in Window.ReparentAction
      • isChildWindow

        boolean isChildWindow()
        Returns true if this window is a child window, i.e. has been reparented.

        Otherwise return false, i.e. this window is a top-level window.

      • setFullscreen

        boolean setFullscreen​(boolean fullscreen)
        Enable or disable fullscreen mode for this window.

        Fullscreen mode is established on the main monitor.

        This method is lifecycle heavy.

        Parameters:
        fullscreen - enable or disable fullscreen mode
        Returns:
        success
        See Also:
        setFullscreen(List), isFullscreen()
      • isFullscreen

        boolean isFullscreen()
      • requestFocus

        void requestFocus()
        Request focus for this native window

        The request is handled on this Window EDT and blocked until finished.

        See Also:
        requestFocus(boolean)
      • requestFocus

        void requestFocus​(boolean wait)
        Request focus for this native window

        The request is handled on this Window EDT.

        Parameters:
        wait - true if waiting until the request is executed, otherwise false
        See Also:
        requestFocus()
      • windowRepaint

        void windowRepaint​(int x,
                           int y,
                           int width,
                           int height)
        Trigger window repaint while passing the dirty region in pixel units.
        Parameters:
        x - dirty-region y-pos in pixel units
        y - dirty-region x-pos in pixel units
        width - dirty-region width in pixel units
        height - dirty-region height in pixel units
      • enqueueEvent

        void enqueueEvent​(boolean wait,
                          NEWTEvent event)
        Enqueues a NEWT event.
        Parameters:
        wait - Passing true will block until the event has been processed, otherwise method returns immediately.
        event - The event to enqueue.
      • runOnEDTIfAvail

        void runOnEDTIfAvail​(boolean wait,
                             Runnable task)
      • addWindowListener

        void addWindowListener​(int index,
                               WindowListener l)
                        throws IndexOutOfBoundsException
        Inserts the given WindowListener at the specified position in the list.
        Parameters:
        index - Position where the listener will be inserted. Should be within (0 <= index && index <= size()). An index value of -1 is interpreted as the end of the list, size().
        l - The listener object to be inserted
        Throws:
        IndexOutOfBoundsException - If the index is not within (0 <= index && index <= size()), or -1
      • removeWindowListener

        void removeWindowListener​(WindowListener l)
      • setKeyboardVisible

        void setKeyboardVisible​(boolean visible)
        In case the platform supports or even requires a virtual on-screen keyboard, this method shows or hide it depending on whether visible is true or false.

        One known platform where NEWT supports this feature is Android.

      • isKeyboardVisible

        boolean isKeyboardVisible()
        Return true if the virtual on-screen keyboard is visible, otherwise false.

        Currently on Android, the only supported platform right now, there is no way to reliably be notified of the current keyboard state.
        It would be best, if your code does not rely on this information.

        See Also:
        setKeyboardVisible(boolean)
      • addKeyListener

        void addKeyListener​(KeyListener l)
        Appends the given KeyListener to the end of the list.
      • addKeyListener

        void addKeyListener​(int index,
                            KeyListener l)
        Inserts the given KeyListener at the specified position in the list.
        Parameters:
        index - Position where the listener will be inserted. Should be within (0 <= index && index <= size()). An index value of -1 is interpreted as the end of the list, size().
        l - The listener object to be inserted
        Throws:
        IndexOutOfBoundsException - If the index is not within (0 <= index && index <= size()), or -1
      • removeKeyListener

        void removeKeyListener​(KeyListener l)
      • getKeyListener

        KeyListener getKeyListener​(int index)
      • addMouseListener

        void addMouseListener​(int index,
                              MouseListener l)
        Inserts the given MouseListener at the specified position in the list.
        Parameters:
        index - Position where the listener will be inserted. Should be within (0 <= index && index <= size()). An index value of -1 is interpreted as the end of the list, size().
        l - The listener object to be inserted
        Throws:
        IndexOutOfBoundsException - If the index is not within (0 <= index && index <= size()), or -1
      • setDefaultGesturesEnabled

        void setDefaultGesturesEnabled​(boolean enable)
        Enable or disable default GestureHandler. Default is enabled.
      • areDefaultGesturesEnabled

        boolean areDefaultGesturesEnabled()
        Return true if default GestureHandler are enabled.
      • addGestureHandler

        void addGestureHandler​(int index,
                               GestureHandler gh)
        Inserts the given GestureHandler at the specified position in the list.
        Parameters:
        index - Position where the listener will be inserted. Should be within (0 <= index && index <= size()). An index value of -1 is interpreted as the end of the list, size().
        l - The listener object to be inserted
        Throws:
        IndexOutOfBoundsException - If the index is not within (0 <= index && index <= size()), or -1
      • addGestureListener

        void addGestureListener​(int index,
                                GestureHandler.GestureListener gl)
        Inserts the given GestureHandler.GestureListener at the specified position in the list.
        Parameters:
        index - Position where the listener will be inserted. Should be within (0 <= index && index <= size()). An index value of -1 is interpreted as the end of the list, size().
        l - The listener object to be inserted
        Throws:
        IndexOutOfBoundsException - If the index is not within (0 <= index && index <= size()), or -1