{"record":{"id":"1f1b34b156d98fe4","repo":"java-native-access/jna","slug":"window-must-be-a-rootpanecontainer","errorCode":null,"errorMessage":"Window must be a RootPaneContainer","messagePattern":"Window must be a RootPaneContainer","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"contrib/platform/src/com/sun/jna/platform/WindowUtils.java","lineNumber":972,"sourceCode":"                    user.UpdateLayeredWindow(hWnd, screenDC, winLoc, winSize, memDC,\n                                             srcLoc, 0, blend, WinUser.ULW_ALPHA);\n                } finally {\n                    user.ReleaseDC(null, screenDC);\n                    if (memDC != null && oldBitmap != null) {\n                        gdi.SelectObject(memDC, oldBitmap);\n                    }\n                }\n            }\n        }\n\n        /** Note that w32 does <em>not</em> paint window decorations when\n         * the window is transparent.\n         */\n        @Override\n        public void setWindowTransparent(final Window w,\n                                         final boolean transparent) {\n            if (!(w instanceof RootPaneContainer)) {\n                throw new IllegalArgumentException(\"Window must be a RootPaneContainer\");\n            }\n            if (!isWindowAlphaSupported()) {\n                throw new UnsupportedOperationException(\"Set sun.java2d.noddraw=true to enable transparent windows\");\n            }\n            boolean isTransparent = w.getBackground() != null\n                && w.getBackground().getAlpha() == 0;\n            if (transparent == isTransparent)\n                return;\n            whenDisplayable(w, new Runnable() {\n                @Override\n                public void run() {\n                    User32 user = User32.INSTANCE;\n                    HWND hWnd = getHWnd(w);\n                    int flags = user.GetWindowLong(hWnd, WinUser.GWL_EXSTYLE);\n                    JRootPane root = ((RootPaneContainer)w).getRootPane();\n                    JLayeredPane lp = root.getLayeredPane();\n                    Container content = root.getContentPane();\n                    if (content instanceof W32TransparentContentPane) {","sourceCodeStart":954,"sourceCodeEnd":990,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/contrib/platform/src/com/sun/jna/platform/WindowUtils.java#L954-L990","documentation":"setWindowTransparent requires the Window to be a RootPaneContainer (JFrame, JDialog, JWindow) because it manipulates the content pane's background alpha. Passing a plain Window, Frame, or Dialog that does not implement RootPaneContainer throws IllegalArgumentException('Window must be a RootPaneContainer').","triggerScenarios":"Calling WindowUtils.setWindowTransparent(new Window(owner), true) or passing a java.awt.Frame/Dialog instance that is not a JFrame/JDialog/JWindow.","commonSituations":"Trying to make raw AWT windows transparent; creating Window objects programmatically instead of Swing top-levels; helper code typed as java.awt.Window receiving non-Swing windows at runtime.","solutions":["Use a JFrame, JDialog, or JWindow instead of plain Window/Frame/Dialog.","Check `w instanceof RootPaneContainer` before calling and handle unsupported window types.","For non-Swing windows, use a different transparency mechanism (e.g. Java 7+ AWTUtilities/setWindowOpacity equivalents).","Cast safely after an instanceof check to access the root pane."],"exampleFix":"// before\nWindow w = new Window(owner);\nWindowUtils.setWindowTransparent(w, true); // IllegalArgumentException\n// after\nJWindow w = new JWindow(owner);\nif (w instanceof RootPaneContainer) {\n    WindowUtils.setWindowTransparent(w, true);\n}","handlingStrategy":"type-guard","validationCode":"if (!(w instanceof RootPaneContainer)) { throw new IllegalArgumentException(\"Need JFrame/JDialog/JWindow\"); }","typeGuard":"boolean isTransparencyCapable(Window w) { return w instanceof RootPaneContainer; }","tryCatchPattern":"try { WindowUtils.setWindowTransparent(w, true); } catch (IllegalArgumentException e) { // convert to JFrame/JWindow or skip }","preventionTips":["Only pass Swing top-level containers (JFrame, JDialog, JWindow)","Type helper APIs as RootPaneContainer instead of java.awt.Window","Add instanceof assertions in code that wraps WindowUtils"],"tags":["java","jna","swing","argument-validation","window-transparency"],"backgroundTag":"invalid-argument-value","analyzedSha":"d036ad9781adad4b66693e8fa7098e4ac665e0a3","analyzedAt":"2026-09-12T06:50:59.239Z","contentChangedAt":"2026-09-12T06:50:59.239Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}