From 2714f044cd64087dc4d1a7ad4ec652e2e8e157ed Mon Sep 17 00:00:00 2001 From: Kenneth Russel Date: Thu, 23 Jun 2005 07:24:48 +0000 Subject: Fixed Issue 159: Document GLCanvas and lightweight interactions Added documentation about JPopupMenu and tool tip interactions with GLCanvas, making GLCanvas resize properly in more situations, and sun.awt.noerasebackground property. git-svn-id: file:///usr/local/projects/SUN/JOGL/git-svn/svn-server-sync/jogl/trunk@307 232f8b59-042b-4e1e-8c03-345bb8c30851 --- doc/userguide/index.html | 92 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 91 insertions(+), 1 deletion(-) diff --git a/doc/userguide/index.html b/doc/userguide/index.html index 03880cbd4..2f29bc1d1 100644 --- a/doc/userguide/index.html +++ b/doc/userguide/index.html @@ -15,6 +15,7 @@
  • Creating a GLDrawable
  • Writing a GLEventListener
  • Using the Composable Pipeline +
  • Heavyweight and Lightweight Issues
  • Multithreading Issues
  • Pbuffers
  • GLU @@ -89,7 +90,8 @@ can not be used. See this article on The Swing Connection for more information about mixing lightweight and -heavyweight widgets. +heavyweight widgets. See also the section on "Heavyweight and +Lightweight Issues" below.

    @@ -248,6 +250,94 @@ class MyListener implements GLEventListener {

    +

    Heavyweight and Lightweight Issues

    + +

    + +As mentioned above, JOGL supplies both a heavyweight (GLCanvas) and a +lightweight (GLJPanel) widget to be able to provide the fastest +possible performance for applications which need it as well as 100% +correct Swing integration, again for applications which need it. The +GLCanvas provides much higher performance than the GLJPanel in nearly +all situations and can be used in almost every kind of application +except those using JInternalFrames. Please see the Swing Connection +article mentioned above for details on mixing heavyweight and +lightweight widgets. A couple of common pitfalls are described here. + +

    +

    + +When using JPopupMenus or Swing tool tips in conjunction with the +GLCanvas, it is necessary to disable the use of lightweight widgets +for the popups. See the methods +ToolTipManager.setLightWeightPopupEnabled, +JPopupMenu.setLightWeightPopupEnabled, and +JPopupMenu.setDefaultLightWeightPopupEnabled. + +

    +

    + +There are occasionally problems with certain LayoutManagers and +component configurations where if a GLCanvas is placed in the middle +of a set of lightweight widgets then it may only grow and never +shrink. These issues are documented somewhat in JOGL Issue +135 and most recently in the thread "Resize +behaviour" in the JOGL forum. The root cause is behavior of the +Canvas, and in particular its ComponentPeer. The implementation of +getPreferredSize() calls getMinimumSize() and getMinimumSize() turns +around and calls Component.getSize(). This effectively means that the +Canvas will report its preferred size as being as large as the +component has ever been. For some layout managers this doesn't seem to +matter, but for others like the BoxLayout it does. See the test case +attached to Issue 135 for an example. Replacing the GLCanvas with an +ordinary Canvas yields the same behavior. + +

    +

    + +One suggestion was to override getPreferredSize() so that if a +preferred size has not been set by the user, to default to (0, +0). This works fine for some test cases but breaks all of the other +JOGL demos because they use a different LayoutManager. There appear to +be a lot of interactions between heavyweight vs. lightweight widgets +and layout managers. One experiment which was done was to override +setSize() in GLCanvas to update the preferred size. This works down +to the size specified by the user; if the window is resized any +smeller the same problem appears. If reshape() (the base routine of +setSize(), setBounds(), etc.) is changed to do the same thing, the +demo breaks in the same way it originally did. Therefore this solution +is fragile because it isn't clear which of these methods are used +internally by the AWT and for what purposes. + +

    +

    + +There are two possible solutions, both application-specific. The best +and most portable appears to be to put the GLCanvas into a JPanel and +set the JPanel's preferred size to (0, 0). The JPanel will cause this +constraint to be enforced on its contained GLCanvas. The other +workaround is to call setPreferredSize(new Dimension(0, +0)) on a newly-created GLCanvas; this method is new in 1.5. + +

    +

    + +Another issue that occasionally arises on Windows is flickering during +live resizing of a GLCanvas. This is caused by the AWT's repainting +the background of the Canvas and can not be overridden on a per-Canvas +basis, for example when subclassing Canvas into GLCanvas. The +repainting of the background of Canvases on Windows can be disabled by +specifying the system property +-Dsun.awt.noerasebackground=true. Whether to specify this +flag depends on the application and should not be done universally, +but instead on a case-by-case basis. Some more detail is in the thread +"TIP: JOGL ++ Swing flicker" in the JOGL forum. + +

    +

    Multithreading Issues

    -- cgit v1.2.3