src/java.desktop/share/classes/java/awt/Window.java

@@ -132,10 +132,17 @@
  * made to honor such requests.  However, in some cases the window
  * management system may ignore such requests, or modify the requested
  * geometry in order to place and size the {@code Window} in a way
  * that more closely matches the desktop settings.
  * <p>
+ * The visual appearance and behavior of top-level windows (including
+ * normal/shaped/translucent/undecorated {@code Window}s, {@code Frame}s,
+ * {@code Dialog}s) are under the control of the desktop's window management
+ * system. The visual effects as shadows, motion effects, animations,
+ * and others may not be controlled by the applications but work according to
+ * the desktop settings.
+ * <p>
  * Due to the asynchronous nature of native event handling, the results
  * returned by {@code getBounds}, {@code getLocation},
  * {@code getLocationOnScreen}, and {@code getSize} might not
  * reflect the actual geometry of the Window on screen until the last
  * request has been processed.  During the processing of subsequent