Skip to content

Latest commit

 

History

History
230 lines (174 loc) · 9.27 KB

2015-05-17-options.md

File metadata and controls

230 lines (174 loc) · 9.27 KB
Raw
layout title category date order disqus
page
Options
doc
2015-05-17 10:37:00 -0700
5
1
  • TOC {:toc}

RequestBuilder options

Most options in Glide can be applied directly on the [RequestBuilder][1] object returned by Glide.with()

Available options include (among others):

  • Placeholders
  • Transformations
  • Caching Strategies
  • Component specific options, like encode quality, or decode Bitmap configurations.

For example, to apply a [CenterCrop][3] [Transformation][4], you'd use the following:

Glide.with(fragment)
    .load(url)
    .centerCrop()
    .into(imageView);

RequestOptions

If you'd like to share options consistently in loads across different parts of your app, you can also instantiate a new RequestOptions object and pass it in to each load with the [apply()][2] method.

RequestOptions cropOptions = new RequestOptions().centerCrop(context);
...
Glide.with(fragment)
    .load(url)
    .apply(cropOptions)
    .into(imageView);

[apply()][2] can be called multiple times, so RequestOptions can be composed. If two RequestOptions objects contain conflicting settings, the last RequestOptions applied to the load will win.

TransitionOptions

[TransitionOptions][5] determine what will happen when your requested load completes.

Use TransitionOptions to apply:

  • View fade in
  • Cross fade from the placeholder
  • No transition

Without a transition, your image will pop into place, immediately replacing the previous image. To avoid the sudden change, you can fade in your view, or cross fade between Drawables using TransitionOptions.

For example, to apply a cross fade:

import static com.bumptech.glide.load.resource.drawable.DrawableTransitionOptions.withCrossFade;

Glide.with(fragment)
    .load(url)
    .transition(withCrossFade())
    .into(view);

Unlike RequestOptions, TransitionOptions are type specific and are tied to the type of resource you ask Glide to load.

As a result, if you request a Bitmap, you will need to use [BitmapTransitionOptions][6], rather than [DrawableTransitionOptions][7]. As a result, if you request a Bitmap, you may need to do a simple fade in, rather than a cross fade.

RequestBuilder

[RequestBuilder][8] is the backbone of the request in Glide and is responsible for bringing your options together with your requested url or model to start a new load.

Use RequestBuilder to specify:

  • The type of resource you want to load (Bitmap, Drawable etc)
  • The url/model you want to load the resource from
  • The view you want to load the resource into
  • Any RequestOption object(s) you want to apply
  • Any TransitionOption object(s) you want to apply
  • Any [thumbnail()][9] you want to load.

You obtain a RequestBuilder by calling Glide.with() and then one of the as methods:

RequestBuilder<Drawable> requestBuilder = Glide.with(fragment).asDrawable();

Or by calling Glide.with() and then load():

RequestBuilder<Drawable> requestBuilder = Glide.with(fragment).load(url);

Picking a resource type

RequestBuilders are specific to the type of resource they will load. By default you get a Drawable RequestBuilder. You can change the requested type using as... methods. For example, if you call asBitmap() you will get a Bitmap RequestBuilder instead:

RequestBuilder<Bitmap> requestBuilder = Glide.with(fragment).asBitmap();

Applying RequestOptions

As mentioned above, you apply RequestOptions with the [apply()][2] method and TransitionOptions with the [transition()][10] method:

RequestBuilder<Drawable> requestBuilder = Glide.with(fragment).asDrawable();
requestBuilder.apply(requestOptions);
requestBuilder.transition(transitionOptions);

RequestBuilders can also be re-used to start multiple loads:

RequestBuilder<Drawable> requestBuilder =
    Glide.with(fragment)
      .asDrawable()
      .apply(requestOptions);

for (int i = 0; i < numViews; i++) {
   ImageView view = viewGroup.getChildAt(i);
   String url = urls.get(i);
   requestBuilder.load(url).into(view);
}

Thumbnail requests

Glide's [thumbnail()][9] API allows you to specify a [RequestBuilder][8] to start in parallel with your main request. The [thumbnail()][9] will be displayed while the primary request is loading. If the primary request completes before the thumbnail request, the image from the thumbnail request will not be shown. The [thumbnail()][9] API allows you easily and quickly load low resolution versions of your images while your full quality equivalents load, reducing the amount of time users spend staring at loading indicators.

The [thumbnail()][9] API is useful for both local and remote images, especially once the lower resolution thumbnails are in Glide's disk cache where they can be loaded very quickly.

The [thumbnail()][9] API is relatively simple to use:

Glide.with(fragment)
  .load(url)
  .thumbnail(
    Glide.with(fragment)
      .load(thumbnailUrl))
  .into(imageView);

This will work well if your thumbnailUrl points to a lower resolution image than your primary url. A number of image loading APIs offer ways for you to specify the size of the image you want in your URL, which works particularly well with the [thumbnail()][9] API.

If you're just loading a local image, or you only have a single remote URL, you can still benefit from the thumbnail API by using Glide's [override()][17] or [sizeMultiplier()][18] APIs to force Glide to load a lower resolution image in the thumbnail request:

int thumbnailSize = ...;
Glide.with(fragment)
  .load(localUri)
  .thumbnail(
    Glide.with(fragment)
      .load(localUri)
      .override(thumbnailSize))
  .into(view);

There's a [thumbnail()][19] convenience method that just takes a sizeMultiplier if you just want to load the same model at some percentage of your View or Target's size:

Glide.with(fragment)
  .load(localUri)
  .thumbnail(/*sizeMultiplier=*/ 0.25f)
  .into(imageView);

Starting a new request on failure.

Starting in Glide 4.3.0, you can now easily specify a [RequestBuilder][8] to use to start a new load if your main request fails using the [error()][20] API. For example, to load fallbackUrl if your request for primaryUrl fails:

Glide.with(fragment)
  .load(primaryUrl)
  .error(
      Glide.with(fragment)
        .load(fallbackUrl))
  .into(imageView);

The [error][20] [RequestBuilder][8] will not be started if the main request completes successfully. If you specify both a [thumbnail()][9] and an [error()][20] [RequestBuilder][8], the error [RequestBuilder][8] will be started if the primary request fails, even if the thumbnail request succeeds.

Component Options

The [Option][11] class is a generic way of adding parameters to Glide's components, including [ModelLoaders][12], [ResourceDecoders][13], [ResourceEncoders][14], [Encoders][15] etc. Some of Glide's built in components contain Options and Options can be added to custom components as well"

Glide.with(context)
  .load(url)
  .option(MyCustomModelLoader.TIMEOUT_MS, 1000L)
  .into(imageView);

You can also create a new RequestOptions object:

RequestOptions options = 
    new RequestOptions()
      .set(MyCustomModelLoader.TIMEOUT_MS, 1000L);

Glide.with(context)
  .load(url)
  .apply(options)
  .into(imageView);

[1]: {{ site.baseurl }}/javadocs/400/com/bumptech/glide/request/RequestOptions.html [2]: {{ site.baseurl }}/javadocs/400/com/bumptech/glide/RequestBuilder.html#apply-com.bumptech.glide.request.RequestOptions- [3]: {{ site.baseurl }}/javadocs/400/com/bumptech/glide/load/resource/bitmap/CenterCrop.html [4]: {{ site.baseurl }}/javadocs/400/com/bumptech/glide/load/Transformation.html [5]: {{ site.baseurl }}/javadocs/400/com/bumptech/glide/TransitionOptions.html [6]: {{ site.baseurl }}/javadocs/400/com/bumptech/glide/load/resource/bitmap/BitmapTransitionOptions.html [7]: {{ site.baseurl }}/javadocs/400/com/bumptech/glide/load/resource/drawable/DrawableTransitionOptions.html [8]: {{ site.baseurl }}/javadocs/400/com/bumptech/glide/RequestBuilder.html [9]: {{ site.baseurl }}/javadocs/400/com/bumptech/glide/RequestBuilder.html#thumbnail-com.bumptech.glide.RequestBuilder- [10]: {{ site.baseurl }}/javadocs/400/com/bumptech/glide/RequestBuilder.html#transition-com.bumptech.glide.TransitionOptions- [11]: {{ site.baseurl }}/javadocs/400/com/bumptech/glide/load/Option.html [12]: {{ site.baseurl }}/javadocs/400/com/bumptech/glide/load/model/ModelLoader.html [13]: {{ site.baseurl }}/javadocs/400/com/bumptech/glide/load/ResourceDecoder.html [14]: {{ site.baseurl }}/javadocs/400/com/bumptech/glide/load/ResourceEncoder.html [15]: {{ site.baseurl }}/javadocs/400/com/bumptech/glide/load/Encoder.html [16]: {{ site.baseurl }}/doc/generatedapi.html [17]: {{ site.baseurl }}/javadocs/430/com/bumptech/glide/request/RequestOptions.html#override-int-int- [18]: {{ site.baseurl }}/javadocs/420/com/bumptech/glide/request/RequestOptions.html#sizeMultiplier-float- [19]: {{ site.baseurl }}/javadocs/430/com/bumptech/glide/RequestBuilder.html#thumbnail-float- [20]: {{ site.baseurl }}/javadocs/430/com/bumptech/glide/RequestBuilder.html#error-com.bumptech.glide.RequestBuilder-