{"record":{"id":"538767b9bd0041dd","repo":"java-native-access/jna","slug":"component-must-be-heavyweight-w","errorCode":null,"errorMessage":"Component must be heavyweight: \" + w","messagePattern":"Component must be heavyweight: \" \\+ w","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"contrib/platform/src/com/sun/jna/platform/WindowUtils.java","lineNumber":581,"sourceCode":"            }\n            w.setBackground(bg);\n        }\n\n        /** Override this method to provide bitmap masking of the given\n         * heavyweight component.\n         */\n        protected void setMask(Component c, Raster raster) {\n            throw new UnsupportedOperationException(\"Window masking is not available\");\n        }\n\n        /**\n         * Set the window mask based on the given Raster, which should\n         * be treated as a bitmap (zero/nonzero values only). A value of\n         * <code>null</code> means to remove the mask.\n         */\n        protected void setWindowMask(Component w, Raster raster) {\n            if (w.isLightweight())\n                throw new IllegalArgumentException(\"Component must be heavyweight: \" + w);\n            setMask(w, raster);\n        }\n\n        /** Set the window mask based on a {@link Shape}. */\n        public void setWindowMask(Component w, Shape mask) {\n            setWindowMask(w, toRaster(mask));\n        }\n\n        /**\n         * Set the window mask based on an Icon. All non-transparent\n         * pixels will be included in the mask.\n         */\n        public void setWindowMask(Component w, Icon mask) {\n            setWindowMask(w, toRaster(w, mask));\n        }\n\n        /**\n         * Use this method to ensure heavyweight popups are used in","sourceCodeStart":563,"sourceCodeEnd":599,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/contrib/platform/src/com/sun/jna/platform/WindowUtils.java#L563-L599","documentation":"setWindowMask requires a heavyweight component; passing a lightweight component (Swing-only, no native peer) throws IllegalArgumentException. Bitmap masking works at the native window level, which lightweight components do not have.","triggerScenarios":"Calling WindowUtils.setWindowMask on a Swing JPanel or other lightweight component, or a Window whose peer is lightweight; isLightweight() returns true for the passed component.","commonSituations":"Applying masks to JWindow/JPanel instead of the top-level Window (JFrame/JDialog/Window); headless or unusual peers causing components to be reported lightweight; JDK changes altering heaviness.","solutions":["Pass the top-level java.awt.Window (JFrame, JDialog, JWindow), not an inner Swing component","Check w.isLightweight() before calling and reject/warn early","Ensure the window is displayable/realized so its peer is heavyweight"],"exampleFix":"// before\nWindowUtils.setWindowMask(myJPanel, raster);\n// after\nWindow top = SwingUtilities.getWindowAncestor(myJPanel);\nif (top != null && !top.isLightweight()) {\n    WindowUtils.setWindowMask(top, raster);\n}","handlingStrategy":"validation","validationCode":"if (w.isLightweight()) {\n    throw new IllegalArgumentException(\"Window mask target must be heavyweight: \" + w);\n}","typeGuard":"boolean isMaskable(Component c) {\n    return !c.isLightweight() && c instanceof Window;\n}","tryCatchPattern":"try {\n    WindowUtils.setWindowMask(w, raster);\n} catch (IllegalArgumentException e) {\n    logger.warn(\"Target must be a heavyweight top-level window\");\n}","preventionTips":["Always pass the top-level Window, never a Swing child","Check isLightweight() before masking","Verify window peer heaviness on the JDKs you support"],"tags":["java","swing","windowutils","illegal-argument"],"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"}