frameworks/base/docs/html/resources/articles/listview-backgrounds.jd

   1 page.title=ListView Backgrounds: An Optimization
   2 @jd:body
   3
   4 <p>{@link android.widget.ListView} is one of Android's most widely used widgets.
   5 It is rather easy to use, very flexible, and incredibly powerful.
   6 <code>ListView</code> can also be difficult to understand at times.</p>
   7
   8 <p>One of the most common issues with <code>ListView</code> happens when you try
   9 to use a custom background. By default, like many Android widgets,
  10 <code>ListView</code> has a transparent background which means that you can see
  11 through the default window's background, a very dark gray
  12 (<code>#FF191919</code> with the current <code>dark</code> theme.) Additionally,
  13 <code>ListView</code> enables the <em>fading edges</em> by default, as you can
  14 see at the top of the following screenshot &mdash; the first text item gradually
  15 fades to black. This technique is used throughout the system to indicate that
  16 the container can be scrolled.</p>
  17
  18 <div style="text-align: center;"><img src="images/list_fade_1.png" alt="Android's default ListView"></div>
  19
  20 <p>The fade effect is implemented using a combination of
  21 {@link android.graphics.Canvas#saveLayerAlpha(float, float, float, float, int, int) Canvas.saveLayerAlpha()}
  22 and the {@link android.graphics.PorterDuff.Mode#DST_OUT Porter-Duff Destination Out blending mode}. </p>
  23
  24 <p>Unfortunately, things start to get ugly when you try to use a custom
  25 background on the <code>ListView</code> or when you change the window's
  26 background. The following two screenshots show what happens in an application
  27 when you change the window's background. The left image shows what the list
  28 looks like by default and the right image shows what the list looks like during
  29 a scroll initiated with a touch gesture:</p>
  30
  31 <div style="text-align: center;">
  32 <img style="margin-right: 12px;" src="images/list_fade_2.png" alt="Dark fade">
  33 <img src="images/list_fade_3.png" alt="Dark list"></div>
  34
  35 <p>This rendering issue is caused by an optimization of the Android framework
  36 enabled by default on all instances of <code>ListView</code>. I mentioned
  37 earlier that the fade effect is implemented using a Porter-Duff blending mode.
  38 This implementation works really well but is unfortunately very costly and can
  39 bring down drawing performance by quite a bit as it requires to capture a
  40 portion of the rendering in an offscreen bitmap and then requires extra blending
  41 (which implies readbacks from memory.)</p>
  42
  43 <p>Since <code>ListView</code> is most of the time displayed on a solid
  44 background, there is no reason to go down that expensive route. That's why we
  45 introduced an optimization called the "cache color hint." The cache color hint
  46 is an RGB color set by default to the window's background color, that is #191919
  47 in Android's dark theme. When this hint is set, <code>ListView</code> (actually,
  48 its base class <code>View</code>) knows it will draw on a solid background and
  49 therefore replaces th expensive <code>saveLayerAlpha()/Porter-Duff</code>
  50 rendering with a simple gradient. This gradient goes from fully transparent to
  51 the cache color hint value and this is exactly what you see on the image above,
  52 with the dark gradient at the bottom of the list. However, this still does not
  53 explain why the entire list turns black during a scroll.</p>
  54
  55 <p>As mentioned before, <code>ListView</code> has a transparent/translucent
  56 background by default, and so all default widgets in the Android UI toolkit.
  57 This implies that when <code>ListView</code> redraws its children, it has to
  58 blend the children with the window's background. Once again, this requires
  59 costly readbacks from memory that are particularly painful during a scroll or a
  60 fling when drawing happens dozen of times per second. </p>
  61
  62 <p>To improve drawing performance during scrolling operations, the Android
  63 framework reuses the cache color hint. When this hint is set, the framework
  64 copies each child of the list in a <code>Bitmap</code> filled with the hint
  65 value (assuming that another optimization, called <em>scrolling cache</em>, is
  66 not turned off). <code>ListView</code> then blits these bitmaps directly on
  67 screen and because these bitmaps are known to be opaque, no blending is
  68 required. Also, since the default cache color hint is <code>#191919</code>, you
  69 get a dark background behind each item during a scroll.</p>
  70
  71 <p>To fix this issue, all you have to do is either disable the cache color hint
  72 optimization, if you use a non-solid color background, or set the hint to the
  73 appropriate solid color value. You can do this from code (see
  74 {@link android.widget.AbsListView#setCacheColorHint(int)}) or preferably from
  75 XML, by using the <code>android:cacheColorHint</code> attribute. To disable the
  76 optimization, simply use the transparent color <code>#00000000</code>. The
  77 following screenshot shows a list with
  78 <code>android:cacheColorHint="#00000000"</code> set in the XML layout file:</p>
  79
  80 <div style="text-align: center;"><img src="images/list_fade_4.png" alt="Fade on a custom background"></div>
  81
  82 <p>As you can see, the fade works perfectly against the custom wooden
  83 background. The cache color hint feature is interesting because it
  84 shows how optimizations can make your life more difficult in
  85 some situations. In this particular case, however, the benefit of the
  86 default behavior outweighs the added complexity..</p>