📝 Rewrite the wiki and optimize the code

Kururu-Q · Sep 17, 2017 · c4452e7 · c4452e7
1 parent 5518f69
commit c4452e7
Show file tree

Hide file tree

Showing 51 changed files with 774 additions and 552 deletions.
diff --git a/README.md b/README.md
@@ -134,10 +134,10 @@ sketchImageView.displayImage("http://t.cn/RShdS1f");
 * [使用 ImageShaper 在绘制时改变图片的形状][image_shaper]
 * [使用 ImageProcessor 在解码后改变图片][image_processor]
 * [使用 ImageDisplayer 以动画的方式显示图片][image_displayer]
-* [使用 MaxSize 限制读取到内存的图片大小][max_size]
+* [使用 MaxSize 读取合适尺寸的缩略图，节省内存][max_size]
 * [使用 Resize 精确修改图片的尺寸][resize]
 * [使用 StateImage 设置占位图片和状态图片][state_image]
-* [监听开始加载、成功、失败以及下载进度事件][listener]
+* [监听准备加载、成功、失败以及下载进度事件][listener]
 
 提升用户体验：
 * [使用 TransitionImageDisplayer 以自然过渡渐的变方式显示图片][transition_image_displayer]
@@ -159,12 +159,11 @@ sketchImageView.displayImage("http://t.cn/RShdS1f");
 * [在内存中缓存 Bitmap 提升显示速度][memory_cache]
 * [在磁盘上缓存图片原文件，避免重复下载][disk_cache]
 * [发送 HTTP 请求][http_stack]
-* [取消显示图片][cancel_request]
+* [取消请求][cancel_request]
 * [监控 Sketch 的异常][error_tracker]
 * [日志][log]
 * [延迟并统一配置 Sketch][initializer]
 * [配置混淆（Proguard）][proguard_config]
-* [其它知识点][other]
 
 ### 特别感谢
 
@@ -256,7 +255,6 @@ sketchImageView.displayImage("http://t.cn/RShdS1f");
 [log]: docs/wiki/log.md
 [initializer]: docs/wiki/initializer.md
 [proguard_config]: docs/wiki/proguard_config.md
-[other]: docs/wiki/other.md
 [options_filter]: docs/wiki/options_filter.md
 
 [koral--]: https://github.com/koral--

diff --git a/README_EN.md b/README_EN.md
@@ -134,10 +134,10 @@ Basic functions:
 * [Use ImageShaper to change the shape of a picture when drawing][image_shaper]
 * [Use ImageProcessor to change the picture after decoding][image_processor]
 * [Use ImageDisplayer to display images in an animated manner][image_displayer]
-* [Use MaxSize to limit the size of the image to read to memory][max_size]
+* [Use MaxSize to read thumbnails of the right size to save memory][max_size]
 * [Use Resize to precisely modify the size of the image][resize]
 * [Use StateImage to set the placeholder picture and status picture][state_image]
-* [Listen to start loading, success, failure, and download progress events][listener]
+* [Listen to ready load, success, failure, and download progress events][listener]
 
 To further enhance the user experience:
 * [Use the TransitionImageDisplayer to display the image in a natural transition gradient][transition_image_displayer]
@@ -159,12 +159,11 @@ More:
 * [Cache Bitmap in memory to increase the display speed][memory_cache]
 * [Cache the original file on the disk, to avoid duplication of the download][disk_cache]
 * [Send HTTP request][http_stack]
-* [Cancel display image][cancel_request]
+* [Cancel request][cancel_request]
 * [Monitor Sketch's exception][error_tracker]
 * [Log][log]
 * [Delay and configure Sketch][initializer]
 * [Config proguard][proguard_config]
-* [Other knowledge points][other]
 
 ### Thanks
 
@@ -256,7 +255,6 @@ More:
 [log]: docs/wiki/log.md
 [initializer]: docs/wiki/initializer.md
 [proguard_config]: docs/wiki/proguard_config.md
-[other]: docs/wiki/other.md
 [options_filter]: docs/wiki/options_filter.md
 
 [koral--]: https://github.com/koral--

diff --git a/docs/logs/log_2.5.0_p2_temp.md b/docs/logs/log_2.5.0_p2_temp.md
@@ -3,6 +3,16 @@ bug 修复版
 bugs：
 * :bug: 修复 2.5.0-p1版本改出来的 无法显示 content chunked 的图片
 
+变更：
+* :hammer: Listener.onStartLoad() 方法名字改为 onReadyLoad()
+
+删除：
+* :fire: 删除 RequestLevelFrom ，因此取消原因中不再区分 REQUEST_LEVEL_IS_LOCAL 和 REQUEST_LEVEL_IS_MEMORY
+* :fire: 删除 CancelCause.REQUEST_LEVEL_IS_LOCAL 和 REQUEST_LEVEL_IS_MEMORY
+* :fire: 删除 SketchUtils.makeRequestKey(String, UriModel, DownloadOptions) 方法，makeRequestKey(String, UriModel, String) 方法代替之
+* :fire: 删除 SketchUtils.makeRequestKey(String, String) 方法，makeRequestKey(String, UriModel, String) 方法代替之
+* :fire: 删除 SketchUtils.makeStateImageMemoryCacheKey(String, DownloadOptions) 方法，makeRequestKey(String, UriModel, String) 方法代替之
+
 新功能：
 * :sparkles: 新增 OptionsFilter 可统一过滤修改 Options  
 

diff --git a/docs/wiki/bitmap_pool.md b/docs/wiki/bitmap_pool.md
@@ -12,53 +12,90 @@
 
 #### 在 BitmapFactory 中使用
 \>= 3.0 && <= 4.3
->* 只能是 jpeg 或 png图片
->* Options.inSampleSize 只能是1`（默认是0，即使不需要缩小也必须改成1）`
->* inBitmap 的宽高必须和新图片的宽高一样`（宽==宽&&高==高）`
->* inBitmap 的 config 必须同新的 Options.inPreferredConfig 一样
->* inBitmap.isMutable() == true
+* 只能是 jpeg 或 png图片
+* Options.inSampleSize 只能是1`（默认是0，即使不需要缩小也必须改成1）`
+* inBitmap 的宽高必须和新图片的宽高一样`（宽==宽&&高==高）`
+* inBitmap 的 config 必须同新的 Options.inPreferredConfig 一样
+* inBitmap.isMutable() == true
 
 \>= 4.4
->* inBitmap 的字节数大于等于新图片除以 inSampleSize 后所占的字节数即可
->* inBitmap 的 config 同新的 Options.inPreferredConfig  最好一样，如果不一样将以 inBitmap 的 config 为准
->* inBitmap.isMutable() == true
+* inBitmap 的字节数大于等于新图片除以 inSampleSize 后所占的字节数即可
+* inBitmap 的 config 同新的 Options.inPreferredConfig  最好一样，如果不一样将以 inBitmap 的 config 为准
+* inBitmap.isMutable() == true
 
 #### 在 BitmapRegionDecoder 中使用
 
 \>= 4.1
->* inBitmap 的字节数大于等于新图片除以 inSampleSize 后所占的字节数即可
->* inBitmap 的 config 同新的 Options.inPreferredConfig 最好一样，如果不一样将以 inBitmap 的 config 为准
->* inBitmap.isMutable() == true
+* inBitmap 的字节数大于等于新图片除以 inSampleSize 后所占的字节数即可
+* inBitmap 的 config 同新的 Options.inPreferredConfig 最好一样，如果不一样将以 inBitmap 的 config 为准
+* inBitmap.isMutable() == true
 
 `如果 inBitmap 不为空的时候解码失败或 inBitmap 不满足使用条件都将抛出 IllegalArgumentException 异常`
 
 ### BitmapPool
 
-BitmapPool 用来存储已经不再使用的 Bitmap，Sketch 在解码之前会根据 width、height、Bitmap.Config 从 BitmapPool 中寻找可复用的 Bitmap 并设置给 Options.inBitmap
+[BitmapPool] 用来存储已经不再使用的 Bitmap，Sketch 在解码之前会根据 width、height、Bitmap.Config 从 BitmapPool 中寻找可复用的 Bitmap 并设置给 Options.inBitmap
 
-BitmapPool 的默认实现是 [LruBitmapPool]（`来自 Glide`），默认最大容量是 3 个屏幕大小
+[BitmapPool] 的默认实现是 [LruBitmapPool]（`来自 Glide`）
 
-#### 使用 BitmapPool
+#### 最大容量
 
-你可以通过 Configuration 拿到 BitmapPool，如下：
+默认最大容量是 3 个屏幕像素数：
 
 ```java
-Context context = ...;
-BitmapPool bitmapPool = Sketch.with(context).getConfiguration().getBitmapPool();
+final DisplayMetrics displayMetrics = context.getResources().getDisplayMetrics();
+final int screenSize = displayMetrics.widthPixels * displayMetrics.heightPixels * 4;
+
+final int bitmapPoolMaxSize = screenSize * 3;
 ```
 
-然后根据宽、高、Bitmap.Config 寻找可复用的 Bitmap
+由于最大容量一旦创建就不能修改，因此想要修改的话就只能重新创建 [BitmapPool]
 
 ```java
+// 最大容量为 APP 最大可用内存的十分之一
+int newBitmapPoolMaxSize = (int) (Runtime.getRuntime().maxMemory() / 10);
+Sketch.with(context).getConfiguration().setBitmapPool(new LruBitmapPool(context, newBitmapPoolMaxSize));
+```
+
+#### 使用 BitmapPool
+
+Sketch 默认开启了 BitmapPool，但如果你有编辑 Bitmap 的需求也可以通过 [BitmapPool] 寻找可复用的 Bitmap，如下：
+
+```java
+BitmapPool bitmapPool = Sketch.with(context).getConfiguration().getBitmapPool();
+
+// 根据宽、高、Bitmap.Config 寻找可复用的 Bitmap
 Bitmap bitmap = bitmapPool.get(100, 100, Bitmap.Config.ARGB_8888);
 ```
 
-Bitmap 使用完毕后通过 BitmapPoolUtils.freeBitmapToPool(Bitmap, BitmapPool) 方法回收 Bitmap
+Bitmap 使用完毕后通过 [BitmapPoolUtils].freeBitmapToPool(Bitmap, BitmapPool) 方法回收 Bitmap
 
 ```java
 BitmapPoolUtils.freeBitmapToPool(bitmap, bitmapPool);
 ```
 
-BitmapPoolUtils 会先尝试将 Bitmap 放进 BitmapPool 中，如果 BitmapPool 已经满了或 Bitmap 不可复用的话就会执行 recycle() 回收掉 Bitmap
+[BitmapPoolUtils] 会先尝试将 Bitmap 放进 [BitmapPool] 中，如果 [BitmapPool] 已经满了或 Bitmap 不可复用的话就会执行 recycle() 回收掉 Bitmap
+
+#### 开关 BitmapPool
+
+```java
+BitmapPool bitmapPool = Sketch.with(context).getConfiguration().getBitmapPool();
+
+// 禁用 BitmapPool
+bitmapPool.setDisabled(true);
+
+// 恢复 BitmapPool
+bitmapPool.setDisabled(false);
+```
+
+### 释放缓存
+
+bitmap 的释放是全自动的，使用者无需关心，总结一下会在如下时机自动释放：
+
+* 达到最大容量时自动释放较旧的 bitmap
+* 设备可用内存较低触发了 Application 的 onLowMemory() 方法
+* 系统整理内存触发了 Application 的 onTrimMemory(int) 方法
 
+[BitmapPool]: ../../sketch/src/main/java/me/xiaopan/sketch/cache/BitmapPool.java
 [LruBitmapPool]: ../../sketch/src/main/java/me/xiaopan/sketch/cache/LruBitmapPool.java
+[BitmapPoolUtils]: ../../sketch/src/main/java/me/xiaopan/sketch/cache/BitmapPoolUtils.java
diff --git a/docs/wiki/cache_processed_image_in_disk.md b/docs/wiki/cache_processed_image_in_disk.md
@@ -1,27 +1,28 @@
 # 使用 cacheProcessedImageInDisk 属性缓存需要复杂处理的图片，提升显示速度
 
-一张图片要经过读取（或缩略图模式读取）和ImageProcessor处理才能显示在页面上，这两步通常也是整个显示过程中最耗时的，为了加快显示速度，减少用户等待时间我们可以将最终经过inSampleSize缩小的、缩略图模式读取的或ImageProcessor处理过的图片缓存在磁盘中，下次就可以直接读取
+一张图片要经过读取（或缩略图模式读取）和 ImageProcessor 处理才能显示在页面上，这两步通常也是整个显示过程中最耗时的，为了加快显示速度，减少用户等待时间我们可以将最终经过 inSampleSize 缩小的、缩略图模式读取的或 [ImageProcessor] 处理过的图片缓存在磁盘中，下次就可以读取后直接使用
 
-#### 如何开启：
+### 如何开启：
 
 ```java
 DisplayOptions displayOptions = new DisplayOptions();
 
 displayOptions.setCacheProcessedImageInDisk(true);
 ```
 
-#### 使用条件
+### 使用条件
 
 并不是你只要开启了就一定会将最终的图片缓存在磁盘缓存中，还需要满足以下任一条件：
->* 有maxSize并且最终计算得出的inSampleSize大于等于8
->* 有resize
->* 有ImageProcessor，并且确实生成了一张新的图片
->* thumbnailMode为true并且resize不为null
+* 有 maxSize 并且最终计算得出的 inSampleSize 大于等于 8
+* 有 resize
+* 有 ImageProcessor，并且确实生成了一张新的图片
+* thumbnailMode 为 true 并且 resize 不为 null
 
-#### 存在的问题
+### 存在的问题
 
-由于Android天然存在的BUG，导致读到内存里的图片，再保存到磁盘后图片会发生轻微的色彩变化（通常是发黄），因此在使用此功能时还是要慎重考虑此因素带来的影响
+由于 Android 天然存在的 BUG，导致读到内存里的图片，再保存到磁盘后图片会发生轻微的色彩变化（通常是发黄并丢失一些细节），因此在使用此功能时还是要慎重考虑此因素带来的影响，参考文章 [Android 中 decode JPG 时建议使用 inPreferQualityOverSpeed][reference_article]
 
-参考文章：http://www.cnblogs.com/zhucai/p/inPreferQualityOverSpeed.html
+`此功能读取图片时已强制设置 inPreferQualityOverSpeed 为 true`
 
-`此功能读取图片时已强制设置inPreferQualityOverSpeed为true`
+[ImageProcessor]:../../sketch/src/main/java/me/xiaopan/sketch/process/ImageProcessor.java
+[reference_article]: http://www.cnblogs.com/zhucai/p/inPreferQualityOverSpeed.html
diff --git a/docs/wiki/cancel_request.md b/docs/wiki/cancel_request.md
@@ -1,14 +1,32 @@
-# 取消显示图片
+# 取消请求
 
-Sketch会自动取消请求，因此你不必刻意关注怎么去取消一个请求，或者该在什么时候去取消一个请求
+### display 显示请求
 
-#### 什么时候会自动取消请求？
->* SketchImageView重用的时候会自动取消之前的请求
->* SketchImageView在onDetachedFromWindow的时候也会自动取消请求
+display 显示请求 [Sketch] 会在合适的时候自动取消，如下：
+* [SketchImageView] 重用的时候会自动取消旧的未完成的请求
+* [SketchImageView] 在 onDetachedFromWindow 的时候自动取消未完成的请求
 
-#### 如何主动取消请求？
->* 方法1：在执行commit()或SketchImageView.display***Image()方法之后你会得到一个Request，
-你可以通过Request的isCanceled()方法查看请求是否结束会或通过Request的cancel()方法取消请求
->* 方法2：你可以通过Sketch.cancel(SketchView)方法来取消请求
+因此你不必刻意关注怎么去取消一个显示请求
 
-``取消请求的时候如果正在读取数据，就会立马停止读取，已经读取的数据就算浪费了``
+但有时候你还是想知道如何主动取消显示请求？
+1. 在执行 [DisplayHelper].commit() 或 [SketchImageView].display***Image() 方法之后你会得到一个 [DisplayRequest]，通过其 cancel() 方法可以取消显示请求
+2. 你还可以通过 [Sketch].cancel(SketchView) 方法来取消显示请求
+
+``取消请求的时候如果正在下载图片，就会立马停止下载，已经下载的数据就算浪费了``
+
+### load 加载请求
+
+在执行 [LoadHelper].commit() 方法之后你会得到一个 [LoadRequest]，通过其 cancel() 方法可以取消显示请求
+
+### download 下载请求
+
+在执行 [DownloadHelper].commit() 方法之后你会得到一个 [DownloadRequest]，通过其 cancel() 方法可以取消显示请求
+
+[Sketch]: ../../sketch/src/main/java/me/xiaopan/sketch/Sketch.java
+[SketchImageView]: ../../sketch/src/main/java/me/xiaopan/sketch/SketchImageView.java
+[DisplayHelper]:../../sketch/src/main/java/me/xiaopan/sketch/request/DisplayHelper.java
+[DisplayRequest]:../../sketch/src/main/java/me/xiaopan/sketch/request/DisplayRequest.java
+[LoadHelper]:../../sketch/src/main/java/me/xiaopan/sketch/request/LoadHelper.java
+[LoadRequest]:../../sketch/src/main/java/me/xiaopan/sketch/request/LoadRequest.java
+[DownloadHelper]:../../sketch/src/main/java/me/xiaopan/sketch/request/DownloadHelper.java
+[DownloadRequest]:../../sketch/src/main/java/me/xiaopan/sketch/request/DownloadRequest.java
diff --git a/docs/wiki/correct_image_orientation.md b/docs/wiki/correct_image_orientation.md
@@ -2,9 +2,9 @@
 
 有的时候碰到被旋转的图片，看着很费劲，图片查看器支持了旋转还好说，要是不支持可就蛋疼了。
 
-现在Sketch支持自动识别图片方向并且纠正，看起来就跟图片原本就是正常的一样，并且分块显示超大图功能也能自动纠正
+现在 [Sketch] 支持自动识别图片方向并且纠正，看起来就跟图片原本就是正常的一样，并且分块显示超大图功能也能自动纠正
 
-`仅支持jpeg类型的图片`，因为目前只有jpeg类型的图片才会有exif信息
+`仅支持 jpeg 类型的图片，因为目前只有 jpeg 类型的图片才会有 exif 信息`
 
 ### 关闭自动纠正功能：
 
@@ -39,6 +39,7 @@ Sketch.with(context).display(...).disableCorrectImageOrientation().commit();
 ### 获取图片方向
 
 1.第一种方法：监听显示完成
+
 ```java
 SketchImageView sketchImageView = ...;
 sketchImageView.setDisplayListener(new DisplayListener(){
@@ -51,7 +52,8 @@ sketchImageView.setDisplayListener(new DisplayListener(){
 });
 ```
 
-2.第二种方法：直接通过Drawable获取
+2.第二种方法：直接通过 Drawable 获取
+
 ```java
 SketchImageView sketchImageView = ...;
 Drawable drawable = sketchImageView.getDrawable();
@@ -61,13 +63,17 @@ if (drawable != null && drawable instanceof SketchDrawable){
 }
 ```
 
-这里返回的方向是未经修饰的exif信息里记载的方向，你可以通过ImageOrientationCorrector类提供的工具方法解析这个方向，如下：
+这里返回的方向是未经修饰的 exif 信息里记载的方向，你可以通过 [ImageOrientationCorrector] 类提供的工具方法解析方向，如下：
+
 ```
 int exifOrientation = ...;
 
 // 纠正方向时顺时针方向需要旋转的度数
 int degrees = ImageOrientationCorrector.getExifOrientationDegrees(exifOrientation);
 
-// 纠正方向时X轴需要是的缩放倍数，通常是1（不需要翻转）或-1（横向翻转）
+// 纠正方向时X轴需要是的缩放倍数，通常是 1（不需要翻转）或 -1（横向翻转）
 int xScale = ImageOrientationCorrector.getExifOrientationTranslation(exifOrientation);
 ```
+
+[Sketch]: ../../sketch/src/main/java/me/xiaopan/sketch/Sketch.java
+[ImageOrientationCorrector]: ../../sketch/src/main/java/me/xiaopan/sketch/decode/ImageOrientationCorrector.java