{"record":{"id":"5e8ee0deb38e5ba0","repo":"java-native-access/jna","slug":"window-masking-is-not-available","errorCode":null,"errorMessage":"Window masking is not available","messagePattern":"Window masking is not available","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"warning","filePath":"contrib/platform/src/com/sun/jna/platform/WindowUtils.java","lineNumber":571,"sourceCode":"                    lp.putClientProperty(TRANSPARENT_OLD_OPAQUE, null);\n                    root.setOpaque(Boolean.TRUE.equals(root.getClientProperty(TRANSPARENT_OLD_OPAQUE)));\n                    root.putClientProperty(TRANSPARENT_OLD_OPAQUE, null);\n                    if (content != null) {\n                        content.setOpaque(Boolean.TRUE.equals(content.getClientProperty(TRANSPARENT_OLD_OPAQUE)));\n                        content.putClientProperty(TRANSPARENT_OLD_OPAQUE, null);\n                    }\n                    bg = (Color)root.getClientProperty(TRANSPARENT_OLD_BG);\n                    root.putClientProperty(TRANSPARENT_OLD_BG, null);\n                }\n            }\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","sourceCodeStart":553,"sourceCodeEnd":589,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/contrib/platform/src/com/sun/jna/platform/WindowUtils.java#L553-L589","documentation":"WindowUtils' base Provider.setMask throws UnsupportedOperationException because the default implementation provides no bitmap masking. Platform subclasses must override setMask; hitting this throw means the running platform's provider does not support window masking (translucent/shaped windows).","triggerScenarios":"Calling setWindowMask(Component, Raster) (or Shape variant) with a WComponentPeer/Provider instance whose setMask was not overridden — i.e. on a platform lacking masking support in this library.","commonSituations":"Using WindowUtils on Linux/window managers without the needed X11 extension, or newer JDKs where the native peer hack no longer works; custom Provider subclasses that forgot to override setMask.","solutions":["Override setMask(Component, Raster) in your Provider subclass with platform-native masking","Verify the platform/JDK combination supports the required native peer (com.sun classes with proper JVM flags)","Wrap mask calls in try-catch for UnsupportedOperationException and fall back to undecorated full-opacity windows"],"exampleFix":"// before\nWindowUtils.setWindowMask(window, shapeRaster);\n// after\ntry {\n    WindowUtils.setWindowMask(window, shapeRaster);\n} catch (UnsupportedOperationException e) {\n    logger.warn(\"Window masking unavailable on this platform\", e);\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    WindowUtils.setWindowMask(window, raster);\n} catch (UnsupportedOperationException e) {\n    logger.warn(\"Window masking unsupported on this platform\");\n}","preventionTips":["Test masking on every target platform/JDK combination","Override setMask in custom Provider subclasses","Provide a no-mask UI fallback for unsupported platforms"],"tags":["java","windowutils","masking","unsupported"],"backgroundTag":"method-not-implemented","analyzedSha":"d036ad9781adad4b66693e8fa7098e4ac665e0a3","analyzedAt":"2026-09-12T06:50:59.239Z","contentChangedAt":"2026-09-12T06:50:59.239Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}