Android Fresco图片处理库用法API英文原文文档2-1(Facebook开源Android图片库)
2015-04-13 14:28
801 查看
这是英文文档的第二部分(1):DRAWEE GUIDE
由于第二部分内容多一些,所以分为2个文章发。方便大家查看。
Drawees have very extensive customization facilities. The best way to customize your Drawee is to do so in the XML.
Here is an example that sets nearly all possible options:
You must declare both
Without both of these two, the view will not be able to lay the image out correctly.
Drawees do not support the
The reason for this is that the content's size changes. The size of your downloaded image can be different from your placeholder - and the failure and retry images, if any, can be still different.
Use of
This is the one time you should use
You can force a DraweeView to be laid out in a particular aspect ratio. If you want a width:height ratio of 4:3, for instance, do this:
Then specify your aspect ratio in Java:
The easy to way is to call
For more advanced requirements, use a controller builder.
For most apps, specify the parameters of their hierarchy in XML provides all the customization
they need. In some cases, though, you may need to go further.
We create an instance of the builder and then set it to the view:
Do not call
intended to be used more than once. Use
it.
Some attributes of the hierarchy can be changed while the application is running.
You would first need to get it from the View:
Then you could modify the placeholder, either with a resource id:
or a full-fledged Drawable:
You can change the scale type:
If you have chosen scale type
You can add a color filter to the image:
All of the rounding related params, except the rounding method, can be modified.
You get a
Definitions
Actual
Placeholder
Failure
Retry
Progress Bar
Backgrounds
Overlays
Pressed State Overlay
This page outlines the different image branches that can be displayed in a Drawee, and how they are set.
Except for the actual image, all of them can be set by an XML attribute. The value in XML must be either an Android drawable or color resource.
They can also be set by a method in the GenericDraweeHierarchyBuilder class,
if setting programmatically. In code, the value can either be from resources or be a
custom subclass ofDrawable.
Some of the items can even be changed on the fly after the hierarchy has been built. These have a method in the GenericDraweeHierarchy class.
Several of the drawables can be scaled.
The actual image is the target; everything else is either an alternative or a decoration. This is specified using a URI, which can point to an image over the Internet, a local file, a resource, or a content provider.
This is a property of the controller, not the hierarchy. It therefore is not set by any of the methods used by the other Drawee components.
Instead, use the
a controller programmatically.
In addition to the scale type, the hierarchy exposes other methods only for the actual image. These are:
the focus point (used for the focusCrop scale
type only)
a color filter
Default scale type:
The placeholder is shown in the Drawee when it first appears on screen. After you have called
load an image, the placeholder continues to be shown until the image has loaded.
In the case of a progressive JPEG, the placeholder only stays until your image has reached the quality threshold, whether the default, or one set by your app.
XML attribute:
Hierarchy builder method:
Hierarchy method:
Default value: a transparent ColorDrawable
Default scale type:
The failure image appears if there is an error loading your image. The most common cause of this is an invalid URI, or lack of connection to the network.
XML attribute:
Hierarchy builder method:
Default value: The placeholder image
Default scale type:
The retry image appears instead of the failure image if you have set your controller to enable the tap-to-retry feature.
You must build your own Controller to do this. Then add the following line
The image pipeline will then attempt to retry an image if the user taps on it. Up to four attempts are allowed before the failure image is shown instead.
XML attribute:
Hierarchy builder method:
Default value: The placeholder image
Default scale type:
If specified, the progress bar image is shown as an overlay over the Drawee until the final image is set.
Currently the progress bar remains the same throughout the image load; actually changing in response to progress is not yet supported.
XML attribute:
Hierarchy builder method:
Default value: None
Default scale type:
Background drawables are drawn first, "under" the rest of the hierarchy.
Only one can be specified in XML, but in code more than one can be set. In that case, the first one in the list is drawn first, at the bottom.
Background images don't support scale-types and are scaled to the Drawee size.
XML attribute:
Hierarchy builder method:
Default value: None
Default scale type: N/A
Overlay drawables are drawn last, "over" the rest of the hierarchy.
Only one can be specified in XML, but in code more than one can be set. In that case, the first one in the list is drawn first, at the bottom.
Overlay images don't support scale-types and are scaled to the Drawee size.
XML attribute:
Hierarchy builder method:
Default value: None
Default scale type: N/A
The pressed state overlay is a special overlay shown only when the user presses the screen area of the Drawee. For example, if the Drawee is showing a button, this overlay could have the button change color when
pressed.
The pressed state overlay doesn't support scale-types.
XML attribute:
Hierarchy builder method:
Default value: None
Default scale type: N/A
You can specify a different scale type for each of the different drawables in your Drawee.
The
These are mostly the same as those supported by the Android ImageView class.
The one unsupported type is
better.
Actual, placeholder, retry, and failure images can all be set in XML, using attributes
like
code using theGenericDraweeHierarchyBuilder class.
Even after your hierarchy is built, the actual image scale type can be modified on the fly using GenericDraweeHierarchy.
However, do not use the
These have no effect on Drawees.
Android, and Fresco, offer a
This is very useful, but the trouble is the cropping doesn't always happen where you need it. If, for instance, you want to crop to someone's face in the bottom right corner of the image,
do the wrong thing.
By specifying a focus point, you can say which part of the image should be centered in the view. If you specify the focus point to be at the top of the image, such as (0.5f, 0f), we guarantee that, no matter what, this point will be visible and centered in
the view as much as possible.
Focus points are specified in a relative coordinate system. That is, (0f, 0f) is the top-left corner, and (1f, 1f) is the bottom-right corner. Relative coordinates allow focus points to be scale-invariant, which is highly useful.
A focus point of (0.5f, 0.5f) is equivalent to a scale type of
To use focus points, you must first set the right scale type in your XML:
In your Java code, you must programmatically set the correct focus point for your image:
If you are using Drawables that make use of Android's tile mode, you need to use the
Not every image is a rectangle. Apps frequently need images that appear with softer, rounded corners, or as circles. Drawee supports a variety of scenarios, all without the memory overhead of copying bitmaps.
Images can be rounded in two shapes:
As a circle - set
As a rectangle, but with rounded corners. Set
Rectangles support having each of the four corners have a different radius, but this must be specified in Java code rather than XML.
Images can be rounded with two different methods:
image and the placeholder. Other branches, like failure and retry images, are not rounded.
Furthermore, this rounding method doesn't support animations.
and of the same solid color. Use
effect.
The
When constructing a hierarchy, you can pass an instance of RoundingParams to
your
You can also change most of the rounding parameters on the fly:
The one exception to this is that the
由于第二部分内容多一些,所以分为2个文章发。方便大家查看。
Using Drawees in XML
Drawees have very extensive customization facilities. The best way to customize your Drawee is to do so in the XML.Here is an example that sets nearly all possible options:
<com.facebook.drawee.view.SimpleDraweeView android:id="@+id/my_image_view" android:layout_width="20dp" android:layout_height="20dp" fresco:fadeDuration="300" fresco:actualImageScaleType="focusCrop" fresco:placeholderImage="@color/wait_color" fresco:placeholderImageScaleType="fitCenter" fresco:failureImage="@drawable/error" fresco:failureImageScaleType="centerInside" fresco:retryImage="@drawable/retrying" fresco:retryImageScaleType="centerCrop" fresco:progressBarImage="@drawable/progress_bar" fresco:progressBarImageScaleType="centerInside" fresco:progressBarAutoRotateInterval="1000" fresco:backgroundImage="@color/blue" fresco:overlayImage="@drawable/watermark" fresco:pressedStateOverlayImage="@color/red" fresco:roundAsCircle="false" fresco:roundedCornerRadius="1dp" fresco:roundTopLeft="true" fresco:roundTopRight="false" fresco:roundBottomLeft="false" fresco:roundBottomRight="true" fresco:roundWithOverlayColor="@color/corner_color" fresco:roundingBorderWidth="2dp" fresco:roundingBorderColor="@color/border_color" />
Height and width mandatory
You must declare both android:layout_widthand
android:layout_height.
Without both of these two, the view will not be able to lay the image out correctly.
wrap_content
Drawees do not support the wrap_contentvalue for the
layout_widthand
layout_heightattributes.
The reason for this is that the content's size changes. The size of your downloaded image can be different from your placeholder - and the failure and retry images, if any, can be still different.
Use of
wrap_contentwould force Android to do another layout pass when your image comes in - and for the layout to change before users' eyes, creating a jarring effect.
Fixing the aspect ratio
This is the one time you should use wrap_content.
You can force a DraweeView to be laid out in a particular aspect ratio. If you want a width:height ratio of 4:3, for instance, do this:
<com.facebook.drawee.view.SimpleDraweeView android:id="@+id/my_image_view" android:layout_width="20dp" android:layout_height="wrap_content" <!-- other attributes -->
Then specify your aspect ratio in Java:
mSimpleDraweeView.setAspectRatio(1.33f);
Using Drawees in Code
Change the image
The easy to way is to callmSimpleDraweeView.setImageURI(uri);
For more advanced requirements, use a controller builder.
Customizing the hierarchy
For most apps, specify the parameters of their hierarchy in XML provides all the customizationthey need. In some cases, though, you may need to go further.
We create an instance of the builder and then set it to the view:
List<Drawable> backgroundsList; List<Drawable> overlaysList; GenericDraweeHierarchyBuilder builder = new GenericDraweeHierarchyBuilder(getResources()); GenericDraweeHierarchy hierarchy = builder .setFadeDuration(300) .setPlaceholderImage(new MyCustomDrawable()) .setBackgrounds(backgroundList) .setOverlays(overlaysList) .build(); mSimpleDraweeView.setHierarchy(hierarchy);
Do not call
setHierarchymore than once on the same view, even if the view is recycled. The hierarchy is expensive to create and is
intended to be used more than once. Use
setControlleror
setImageURIto change the image shown in
it.
Modifying the hierarchy in-place
Some attributes of the hierarchy can be changed while the application is running.You would first need to get it from the View:
GenericDraweeHierarchy hierarchy = mSimpleDraweeView.getHierarchy();
Change the placeholder
Then you could modify the placeholder, either with a resource id:hierarchy.setPlaceholderImage(R.drawable.placeholderId);
or a full-fledged Drawable:
Drawable drawable; // create your drawable hierarchy.setPlaceholderImage(drawable);
Change the image display
You can change the scale type:hierarchy.setActualImageScaleType(ScalingUtils.ScaleType.CENTER_INSIDE);
If you have chosen scale type
focusCrop,you'll need to set a focus point:
hierarchy.setActualImageFocusPoint(point);
You can add a color filter to the image:
ColorFilter filter; // create your filter hierarchy.setActualImageColorFilter(filter);
Rounding
All of the rounding related params, except the rounding method, can be modified.You get a
RoundingParamsobject from the hierarchy, modify it, and set it back again:
RoundingParams roundingParams = hierarchy.getRoundingParams(); roundingParams.setCornersRadius(10); hierarchy.setRoundingParams(roundingParams);
Drawee Image Branches
Contents
DefinitionsActual
Placeholder
Failure
Retry
Progress Bar
Backgrounds
Overlays
Pressed State Overlay
Definitions
This page outlines the different image branches that can be displayed in a Drawee, and how they are set.Except for the actual image, all of them can be set by an XML attribute. The value in XML must be either an Android drawable or color resource.
They can also be set by a method in the GenericDraweeHierarchyBuilder class,
if setting programmatically. In code, the value can either be from resources or be a
custom subclass ofDrawable.
Some of the items can even be changed on the fly after the hierarchy has been built. These have a method in the GenericDraweeHierarchy class.
Several of the drawables can be scaled.
Actual
The actual image is the target; everything else is either an alternative or a decoration. This is specified using a URI, which can point to an image over the Internet, a local file, a resource, or a content provider.This is a property of the controller, not the hierarchy. It therefore is not set by any of the methods used by the other Drawee components.
Instead, use the
setImageURImethod or set
a controller programmatically.
In addition to the scale type, the hierarchy exposes other methods only for the actual image. These are:
the focus point (used for the focusCrop scale
type only)
a color filter
Default scale type:
centerCrop
Placeholder
The placeholder is shown in the Drawee when it first appears on screen. After you have called setControlleror
setImageURIto
load an image, the placeholder continues to be shown until the image has loaded.
In the case of a progressive JPEG, the placeholder only stays until your image has reached the quality threshold, whether the default, or one set by your app.
XML attribute:
placeholderImage
Hierarchy builder method:
setPlaceholderImage
Hierarchy method:
setPlaceholderImage
Default value: a transparent ColorDrawable
Default scale type:
centerInside
Failure
The failure image appears if there is an error loading your image. The most common cause of this is an invalid URI, or lack of connection to the network.XML attribute:
failureImage
Hierarchy builder method:
setFailureImage
Default value: The placeholder image
Default scale type:
centerInside
Retry
The retry image appears instead of the failure image if you have set your controller to enable the tap-to-retry feature.You must build your own Controller to do this. Then add the following line
.setTapToRetryEnabled(true)
The image pipeline will then attempt to retry an image if the user taps on it. Up to four attempts are allowed before the failure image is shown instead.
XML attribute:
retryImage
Hierarchy builder method:
setRetryImage
Default value: The placeholder image
Default scale type:
centerInside
Progress Bar
If specified, the progress bar image is shown as an overlay over the Drawee until the final image is set.Currently the progress bar remains the same throughout the image load; actually changing in response to progress is not yet supported.
XML attribute:
progressBarImage
Hierarchy builder method:
setProgressBarImage
Default value: None
Default scale type:
centerInside
Backgrounds
Background drawables are drawn first, "under" the rest of the hierarchy.Only one can be specified in XML, but in code more than one can be set. In that case, the first one in the list is drawn first, at the bottom.
Background images don't support scale-types and are scaled to the Drawee size.
XML attribute:
backgroundImage
Hierarchy builder method:
setBackground,
setBackgrounds
Default value: None
Default scale type: N/A
Overlays
Overlay drawables are drawn last, "over" the rest of the hierarchy.Only one can be specified in XML, but in code more than one can be set. In that case, the first one in the list is drawn first, at the bottom.
Overlay images don't support scale-types and are scaled to the Drawee size.
XML attribute:
overlayImage
Hierarchy builder method:
setOverlay,
setOverlays
Default value: None
Default scale type: N/A
Pressed State Overlay
The pressed state overlay is a special overlay shown only when the user presses the screen area of the Drawee. For example, if the Drawee is showing a button, this overlay could have the button change color whenpressed.
The pressed state overlay doesn't support scale-types.
XML attribute:
pressedStateOverlayImage
Hierarchy builder method:
setPressedStateOverlay
Default value: None
Default scale type: N/A
Scaling
You can specify a different scale type for each of the different drawables in your Drawee.The
Available scale types
Scale Type | Explanation |
---|---|
center | Center the image in the view, but perform no scaling. |
centerCrop | Scales the image so that both dimensions will be greater than or equal to the corresponding dimension of the parent. One of width or height will fit exactly. The image is centered within parent's bounds. |
focusCrop | Same as centerCrop, but based around a caller-specified focus point instead of the center. |
centerInside | Downscales the image so that it fits entirely inside the parent. Unlike fitCenter,no upscaling will be performed. Aspect ratio is preserved. The image is centered within parent's bounds. |
fitCenter | Scales the image so that it fits entirely inside the parent. One of width or height will fit exactly. Aspect ratio is preserved. The image is centered within the parent's bounds. |
fitStart | Scales the image so that it fits entirely inside the parent. One of width or height will fit exactly. Aspect ratio is preserved. The image is aligned to the top-left corner of the parent. |
fitEnd | Scales the image so that it fits entirely inside the parent. One of width or height will fit exactly. Aspect ratio is preserved. The image is aligned to the bottom-right corner of the parent. |
fitXY | Scales width and height independently, so that the image matches the parent exactly. Aspect ratio is not preserved. |
none | Used for Android's tile mode. |
The one unsupported type is
matrix.In its place, Fresco offers
focusCrop,which will usually work
better.
How to set
Actual, placeholder, retry, and failure images can all be set in XML, using attributeslike
fresco:actualImageScaleType. You can also set them in
code using theGenericDraweeHierarchyBuilder class.
Even after your hierarchy is built, the actual image scale type can be modified on the fly using GenericDraweeHierarchy.
However, do not use the
android:scaleTypeattribute, nor the
.setScaleTypemethod.
These have no effect on Drawees.
focusCrop
Android, and Fresco, offer a centerCropscale type, which will fill the entire viewing area while preserving the aspect ratio of the image, cropping as necessary.
This is very useful, but the trouble is the cropping doesn't always happen where you need it. If, for instance, you want to crop to someone's face in the bottom right corner of the image,
centerCropwill
do the wrong thing.
By specifying a focus point, you can say which part of the image should be centered in the view. If you specify the focus point to be at the top of the image, such as (0.5f, 0f), we guarantee that, no matter what, this point will be visible and centered in
the view as much as possible.
Focus points are specified in a relative coordinate system. That is, (0f, 0f) is the top-left corner, and (1f, 1f) is the bottom-right corner. Relative coordinates allow focus points to be scale-invariant, which is highly useful.
A focus point of (0.5f, 0.5f) is equivalent to a scale type of
centerCrop.
To use focus points, you must first set the right scale type in your XML:
fresco:actualImageScaleType="focusCrop"
In your Java code, you must programmatically set the correct focus point for your image:
PointF focusPoint; // your app populates the focus point mSimpleDraweeView .getHierarchy() .setActualImageFocusPoint(focusPoint);
none#
If you are using Drawables that make use of Android's tile mode, you need to use the nonescale type for this to work correctly.
Rounded Corners and Circles
Not every image is a rectangle. Apps frequently need images that appear with softer, rounded corners, or as circles. Drawee supports a variety of scenarios, all without the memory overhead of copying bitmaps.
What
Images can be rounded in two shapes:As a circle - set
roundAsCircleto true.
As a rectangle, but with rounded corners. Set
roundedCornerRadiusto some value.
Rectangles support having each of the four corners have a different radius, but this must be specified in Java code rather than XML.
How
Images can be rounded with two different methods:BITMAP_ONLY- Uses a shader to draw the bitmap with rounded corners. This is the default rounding method. This works only on the actual
image and the placeholder. Other branches, like failure and retry images, are not rounded.
Furthermore, this rounding method doesn't support animations.
OVERLAY_COLOR- Draws rounded corners by overlaying a solid color, specified by the caller. The Drawee's background should be static
and of the same solid color. Use
roundWithOverlayColorin XML, or
setOverlayColorin code, for this
effect.
In XML
The SimpleDraweeViewclass will forward several attributes over to
RoundingParams:
<com.facebook.drawee.view.SimpleDraweeView ... fresco:roundedCornerRadius="5dp" fresco:roundBottomLeft="false" fresco:roundBottomRight="false" fresco:roundWithOverlayColor="@color/blue" fresco:roundingBorderWidth="1dp" fresco:roundingBorderColor="@color/red"
In code#
When constructing a hierarchy, you can pass an instance of RoundingParams toyour
GenericDraweeHierarchyBuilder:
RoundingParams roundingParams = RoundingParams.fromCornersRadius(7f); roundingParams.setOverlayColor(R.color.green); // alternatively use fromCornersRadii or asCircle genericDraweeHierarchyBuilder .setRoundingParams(roundingParams);
You can also change most of the rounding parameters on the fly:
RoundingParams roundingParams = mSimpleDraweeView.getHierarchy().getRoundingParams(); roundingParams.setBorder(R.color.red, 1.0); roundingParams.setRoundAsCircle(true); mSimpleDraweeView.getHierarchy().setRoundingParams(roundingParams);
The one exception to this is that the
RoundingMethodcannot be changed when changing dynamically. Attempting to do so will throw an
IllegalStateException.
相关文章推荐
- Android Fresco图片处理库用法API英文原文文档2-2(Facebook开源Android图片库)
- Android Fresco图片处理库用法API英文原文文档3(Facebook开源Android图片库)
- Android Fresco图片处理库用法API英文原文文档4(Facebook开源Android图片库)
- Android Fresco图片处理库用法API英文原文文档4(Facebook开源Android图片库)
- Android Fresco图片处理库用法API英文原文文档2-1(Facebook开源Android图片库)
- Android Fresco图片处理库用法API英文原文文档2-2(Facebook开源Android图片库)
- Android Fresco图片处理库用法API英文原文文档1(Facebook开源Android图片库)
- Android Fresco图片处理库用法API英文原文文档3(Facebook开源Android图片库)
- Android Fresco图片处理库用法API英文原文文档1(Facebook开源Android图片库)
- Facebook android 图片处理库 Fresco
- fresco Facebook开源的一款图片处理库
- ANDROID中使用开源框架FRESCO处理图片
- Facebook推出强大Android图片库Fresco 自动释放内存 图片缓存 内存益处
- Android中使用开源框架Fresco处理图片
- Fresco文档:Facebook出品的Android图片
- ANDROID中使用开源框架FRESCO处理图片
- Android使用开源框架Fresco处理图片
- Fresco(Facebook开源的android项目)图片缓存框架的eclipse整合与使用探索(较详细配置说明)
- Android Fresco (Facebook开源的图片加载管理库)
- fresco--facebook推出的一款强大的android图片处理库