diff --git a/README.md b/README.md
index 57c85fd..6c90e62 100644
--- a/README.md
+++ b/README.md
@@ -20,12 +20,14 @@ A new Material Design text field that comes in a box, based on [Google Material
## ***UPDATE NOTICE***
+#### 1.4.3 Release
+- Add [`setSimpleTextChangeWatcher()`](#watcher) as a better way to listen the input (#69).
+- Add [`app:manualValidateError`](#validate) attribute to manually control error state validation (#70).
+- Bug fix (#71).
+
#### 1.4.2 Release
- Fixed #59 #60 #61.
-#### 1.4.1 Release
-- Ultimately fixed #49.
-
## Requirements
- Android 4.0.3 IceCreamSandwich (API lv 15) or greater
@@ -46,7 +48,7 @@ allprojects {
```
```groovy
dependencies {
- compile 'com.github.HITGIF:TextFieldBoxes:1.4.2'
+ compile 'com.github.HITGIF:TextFieldBoxes:1.4.3'
}
```
@@ -63,7 +65,7 @@ dependencies {
com.github.HITGIF
TextFieldBoxes
- 1.4.2
+ 1.4.3
```
@@ -72,7 +74,7 @@ dependencies {
resolvers += "jitpack" at "https://jitpack.io"
```
```scala
-libraryDependencies += "com.github.HITGIF" % "TextFieldBoxes" % "1.4.2"
+libraryDependencies += "com.github.HITGIF" % "TextFieldBoxes" % "1.4.3"
```
@@ -81,12 +83,29 @@ libraryDependencies += "com.github.HITGIF" % "TextFieldBoxes" % "1.4.2"
:repositories [["jitpack" "https://jitpack.io"]]
```
```scala
-:dependencies [[com.github.hitgif/textfieldboxes "1.4.2"]]
+:dependencies [[com.github.hitgif/textfieldboxes "1.4.3"]]
```
## Usage
+#### Table of Contents
+1. [Basic](#basic)
+2. [Enable / Disable](#enable)
+3. [Helper Text & Error Text](#helper)
+4. [Prefix & Suffix](#prefix)
+5. [Max & Min Characters](#max)
+6. [Icon Signifier](#icon)
+7. [End Icon](#end)
+8. [Clear Button](#clear)
+9. [Custom Colors](#color)
+10. [Dense Spacing](#dense)
+11. [Always Show Hint](#hint)
+12. [Text Change Watcher](#watcher)
+13. [Dark Theme](#dark)
+14. [Manual Validate Error](#validate)
+
+
#### 1. Basic
Add `studio.carbonylgroup.textfieldboxes.TextFieldBoxes` that contains a `studio.carbonylgroup.textfieldboxes.ExtendedEditText` to your layout:
@@ -114,6 +133,7 @@ Add `studio.carbonylgroup.textfieldboxes.TextFieldBoxes` that contains a `studio
+
#### 2. Enable / Disable
`app:enabled` in xml or `setEnabled(boolean enabled)` in Java.
@@ -127,7 +147,8 @@ Add `studio.carbonylgroup.textfieldboxes.TextFieldBoxes` that contains a `studio
-#### 3. Helper Text and Error Text
+
+#### 3. Helper Text & Error Text
_**NOTE:** setting helper or error text to anything **not empty** will make the bottom view (which contains the helper label) visible and increase the height of the TextFieldBoxes. So if you want to always keep the bottom view visible (height increased), set the helper text to `" "` when there should be nothing._
@@ -155,6 +176,7 @@ setError("Error message");
+
#### 4. Prefix & Suffix
_**! NOTE:** Prifix and Suffix attributes should be set to `ExtendedEditText`._
@@ -182,6 +204,7 @@ Use `app:suffix` in xml or `setSuffix(String suffix)` in Java to set the unselec
+
#### 5. Max & Min Characters
_**NOTE:** setting max or min character will make the bottom view (which contains the counter label) visible and increase the height of the TextFieldBoxes._
@@ -213,6 +236,7 @@ The color of the bottom line will turn to `errorColor` (red by default) when exc
+
#### 6. Icon Signifier
Use `app:iconSignifier` in xml or `setIconSignifier(Int resourceID)` to set the icon that is shown in front of the TextFieldBoxes if you want there to be one.
@@ -229,6 +253,7 @@ _**NOTE that if `true`, the icon's color will always be `HighlightColor` (the sa
+
#### 7. End Icon
Use `app:endIcon` in xml or `setEndIcon(Int resourceID)` to set the icon of the ImageButton that is shown at the end of the field if you want there to be one.
@@ -254,6 +279,7 @@ textFieldBoxes.getEndIconImageButton().setOnClickListener(new View.OnClickListen
});
```
+
#### 8. Clear Button
Use `app:hasClearButton` in xml or `setHasClearButton(boolean hasClearButton)` to set whether to show the clear button.
@@ -269,6 +295,7 @@ If `true`, a clear button will be shown at the end when there are characters (**
+
#### 9. Custom Colors
*Primary Color* will be used for the color of the underline, the floating label text and the icon signifier **when HAVING focus**. You can use `app:primaryColor` in xml or `setPrimaryColor(int colorRes)` in Java. Current theme `Primary Color` by default.
@@ -309,6 +336,7 @@ then set this as the theme for your TextFieldBoxes:
>
```
+
#### 10. Dense Spacing
You can make the layout compact by using a dense verticle spacing to improve user experience in some cases.
@@ -326,6 +354,7 @@ Use `app:useDenseSpacing` in xml or `setUseDenseSpacing(boolean useDenseSpacing)
+
#### 11. Always Show Hint
Sometimes you may want the label and the hint to show different messages, but need the hint to always be shown (instead being blocked by the label when losing focus).
@@ -341,7 +370,29 @@ Use `app:alwaysShowHint` in xml or `setAlwaysShowHint(boolean alwaysShowHint)` t
-#### 12. Dark Theme
+
+#### 12. Text Change Watcher
+
+It is strongly recommanded to use `setSimpleTextChangeWatcher()` to listen the event of changing text instead of `addTextChangedListener()`.
+
+This has the following advantages:
+1. You don't need to implement `beforeTextChanged()` and `onTextChanged()` method when unnecessary.
+2. Avoids potential unexpected behavior, by guaranteeing your code to run after the default processes (remove error, update counter text, etc.) are finished.
+3. When the view is recycled, no manual remove call is needed.
+
+e.g.
+```java
+final TextFieldBoxes textFieldBoxes = findViewById(R.id.text_field_boxes);
+textFieldBoxes.setSimpleTextChangeWatcher(new SimpleTextChangedWatcher() {
+ @Override
+ public void onTextChanged(String theNewText, boolean isError) {
+ // What you want to do when text changes
+ }
+});
+```
+
+
+#### 13. Dark Theme
TextFieldBoxes use the color attributes within the current theme and will automatically change its color to fit the dark theme without additional settings.
@@ -349,6 +400,24 @@ TextFieldBoxes use the color attributes within the current theme and will automa
+
+#### 14. Manual Validate Error
+
+By default, the error state of the field is validated each time the text changes and also at time of construction. This means a field with a minimum length requirement will start in the Error state.
+
+Setting `app:manualValidateError` to `true` will make the field validate error only when `validateError()` is called.
+
+```xml
+
+```
+```Java
+final TextFieldBoxes textFieldBoxes = findViewById(R.id.text_field_boxes);
+// The error state will only be updated when this is called
+textFieldBoxes.validateError()
+```
## All Attributes
@@ -412,6 +481,7 @@ TextFieldBoxes use the color attributes within the current theme and will automa
| `app:hasFocus` | Whether the EditText is having the focus | `False` |
| `app:alwaysShowHint` | Whether the label is fixed at top when there's a hint in the EditText | `False` |
| `app:useDenseSpacing` | Whether the field uses a dense spacing between its elements | `False` |
+| `app:manualValidateError` | Whether to validate error state only when `validateError()` is called | `False` |
## License
diff --git a/README_CN.md b/README_CN.md
index 3a3b9f2..e6adeb2 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -18,12 +18,14 @@
## ***更新注意***
+#### 1.4.3 Release
+- 增加 [`setSimpleTextChangeWatcher()`](#watcher) 以便更好地监听文字输入 (#69)。
+- 增加 [`app:manualValidateError`](#validate) 属性以手动刷新错误状态 (#70)。
+- Bug 修复 (#71)。
+
#### 1.4.2 Release
- 修复了 #59 #60 #61。
-#### 1.4.1 Release
-- 最终修复了 #49。
-
## 要求
- Android 4.0.3 IceCreamSandwich (API lv 15) 或更高
@@ -44,7 +46,7 @@ allprojects {
```
```groovy
dependencies {
- compile 'com.github.HITGIF:TextFieldBoxes:1.4.2'
+ compile 'com.github.HITGIF:TextFieldBoxes:1.4.3'
}
```
@@ -61,7 +63,7 @@ dependencies {
com.github.HITGIF
TextFieldBoxes
- 1.4.2
+ 1.4.3
```
@@ -70,7 +72,7 @@ dependencies {
resolvers += "jitpack" at "https://jitpack.io"
```
```scala
-libraryDependencies += "com.github.HITGIF" % "TextFieldBoxes" % "1.4.2"
+libraryDependencies += "com.github.HITGIF" % "TextFieldBoxes" % "1.4.3"
```
@@ -79,12 +81,29 @@ libraryDependencies += "com.github.HITGIF" % "TextFieldBoxes" % "1.4.2"
:repositories [["jitpack" "https://jitpack.io"]]
```
```scala
-:dependencies [[com.github.hitgif/textfieldboxes "1.4.2"]]
+:dependencies [[com.github.hitgif/textfieldboxes "1.4.3"]]
```
## 使用
+#### 目录
+1. [基础](#basic)
+2. [启用 / 禁用](#enable)
+3. [帮助和错误信息](#helper)
+4. [前缀 & 后缀](#prefix)
+5. [最大和最小字符数](#max)
+6. [首图标](#icon)
+7. [末图标](#end)
+8. [清除按钮](#clear)
+9. [自定义颜色](#color)
+10. [紧凑布局](#dense)
+11. [不隐藏提示文本](#hint)
+12. [监听文字输入](#watcher)
+13. [暗主题](#dark)
+14. [手动刷新错误状态](#validate)
+
+
#### 1. 基础
将包含`studio.carbonylgroup.textfieldboxes.ExtendedEditText` 的 `studio.carbonylgroup.textfieldboxes.TextFieldBoxes` 加入你的布局文件:
@@ -112,6 +131,7 @@ libraryDependencies += "com.github.HITGIF" % "TextFieldBoxes" % "1.4.2"
+
#### 2. 启用 / 禁用
在 xml 中加入 `app:enabled` 或在 Java 代码中使用 `setEnabled(boolean enabled)`。
@@ -125,6 +145,7 @@ libraryDependencies += "com.github.HITGIF" % "TextFieldBoxes" % "1.4.2"
+
#### 3. 帮助和错误信息
_**注意:** 将帮助或错误信息设置为任何**不为空**的字符将会使底部 View (包含了帮助标签) 可见并增加 TextFieldBoxes 的高度。所以如果你想让底部 View 始终可见 (保持增加后的高度)，则可在帮助标签应为空时将其设为 `" "` 。_
@@ -154,6 +175,7 @@ setError("Error message");
+
#### 4. 前缀 & 后缀
_**！注意:** 前缀与后缀应在 `ExtendedEditText` 中设置。_
@@ -181,6 +203,7 @@ _**！注意:** 前缀与后缀应在 `ExtendedEditText` 中设置。_
+
#### 5. 最大和最小字符数
_**注意:** 设置最大或最小字符数将会使底部 View (包含了计数标签) 可见并增加 TextFieldBoxes 的高度。_
@@ -212,6 +235,7 @@ _**注意:** 设置最大或最小字符数将会使底部 View (包含了计数
+
#### 6. 首图标
在 xml 中加入 `app:iconSignifier` 或在 Java 代码中使用 `setIconSignifier(Int resourceID)` 以设置 TextFieldBoxes 前边的图标（如果你想要有）。
@@ -228,6 +252,7 @@ _**注意：如果值为 `true`，图标颜色将始终为 `HighlightColor` (与
+
#### 7. 末图标
在 xml 中使用 `app:endIcon` 或在 Java 代码中使用 `setEndIcon(Int resourceID)` 以设置文本域末端的 ImageButton 的图标（如果你想要有）。
@@ -253,6 +278,7 @@ textFieldBoxes.getEndIconImageButton().setOnClickListener(new View.OnClickListen
});
```
+
#### 8. 清除按钮
在 xml 中使用 `app:hasClearButton` 或在 Java 代码中使用 `setHasClearButton(boolean hasClearButton)` 以设置是否显示清除按钮。
@@ -268,6 +294,7 @@ textFieldBoxes.getEndIconImageButton().setOnClickListener(new View.OnClickListen
+
#### 9. 自定义颜色
*Primary Color* 是底部的线、标签文字和首图标在**获得焦点**时的颜色。在 xml 中加入 `app:primaryColor` 或在 Java 代码中使用 `setPrimaryColor(int colorRes)` 以设置。默认值为目前主题的 `Primary Color`。
@@ -309,6 +336,7 @@ textFieldBoxes.getEndIconImageButton().setOnClickListener(new View.OnClickListen
>
```
+
#### 10. 紧凑布局
你可以使用更小的元素纵向间距，让文本框的布局更加紧凑，以在某些情况下改善用户体验。
@@ -326,6 +354,7 @@ textFieldBoxes.getEndIconImageButton().setOnClickListener(new View.OnClickListen
+
#### 11. 不隐藏提示文本
有些时候，你可能需要在顶部标签与提示 (Hint) 文本中显示不同的内容， 并且不希望提示文本在失去焦点时被标签盖住。
@@ -341,7 +370,29 @@ textFieldBoxes.getEndIconImageButton().setOnClickListener(new View.OnClickListen
-#### 12. 暗主题
+
+#### 12. 监听文字输入
+
+强烈建议使用 `setSimpleTextChangeWatcher()` 来监听文字输入，而不是 `addTextChangedListener()`。
+
+这有以下好处：
+1. 不需要时，可以不用实现 `beforeTextChanged()` and `onTextChanged()` 方法。
+2. 保证你的代码在默认进程结束（去除错误状态，更新计数文本等）后执行，从而避免可能的无法预料的问题。
+3. 不需要在视图回收后手动调用移除函数。
+
+比如：
+```java
+final TextFieldBoxes textFieldBoxes = findViewById(R.id.text_field_boxes);
+textFieldBoxes.setSimpleTextChangeWatcher(new SimpleTextChangedWatcher() {
+ @Override
+ public void onTextChanged(String theNewText, boolean isError) {
+ // What you want to do when text changes
+ }
+});
+```
+
+
+#### 13. 暗主题
TextFieldBoxes 用目前主题中的颜色属性因此将自动改变颜色以适应暗主题而不需其他设置。
@@ -349,6 +400,25 @@ TextFieldBoxes 用目前主题中的颜色属性因此将自动改变颜色以
+
+
+#### 14. 手动刷新错误状态
+
+默认情况下，文本框的错误状态将在初始化和文本变化时更新。这将导致在设置了最小字符限制时，文本框将在初始化时处于错误状态。
+
+将 `app:manualValidateError` 设置为 `true`，将使错误状态只在调用 `validateError()` 时刷新。
+
+```xml
+
+```
+```Java
+final TextFieldBoxes textFieldBoxes = findViewById(R.id.text_field_boxes);
+// 错误状态只在调用这个时刷新
+textFieldBoxes.validateError()
+```
## 全部属性
@@ -412,6 +482,7 @@ TextFieldBoxes 用目前主题中的颜色属性因此将自动改变颜色以
| `app:hasFocus` | 文本框是否获得焦点 | `False` |
| `app:alwaysShowHint` | 当 EditText 中有提示文本时，是否将标签始终固定在顶部 | `False` |
| `app:useDenseSpacing` | 是否使用紧凑的布局 | `False` |
+| `app:manualValidateError` | 错误状态是否只在调用 `validateError()` 时刷新 | `False` |
## 开源许可