Skip to content

Commit fc24d54

Browse files
author
TutorialsAndroid
committed
2 parents d830f46 + 2e2a3e0 commit fc24d54

1 file changed

Lines changed: 397 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 397 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,397 @@
1+
![](https://github.com/TutorialsAndroid/MTextField/blob/master/sample/src/main/res/mipmap-xxhdpi/ic_launcher.png)
2+
3+
# MTextField ![API](https://img.shields.io/badge/API-21%2B-brightgreen.svg?style=flat) [![Known Vulnerabilities](https://snyk.io/test/github/TutorialsAndroid/MTextField/badge.svg?style=flat-squaretargetFile=library%2Fbuild.gradle)](https://snyk.io/test/github/TutorialsAndroid/MTextField?targetFile=library%2Fbuild.gradle) [![Android Arsenal](https://img.shields.io/badge/Android%20Arsenal-MTextField-blue.svg?style=plastic)](https://android-arsenal.com/details/1/7627) [![License](https://img.shields.io/badge/License-Apache%202.0-red.svg)](https://opensource.org/licenses/Apache-2.0)
4+
5+
A new Material Design text field that comes in a box, based on [Google Material Design guidelines]
6+
7+
**Library available on JitPack.io**
8+
9+
[![](https://jitpack.io/v/TutorialsAndroid/MTextField.svg)](https://jitpack.io/#TutorialsAndroid/MTextField)
10+
`Version 16.4.19 is deprecated use latest version v4.0.19`
11+
12+
`Latest version of this library is migrated to androidx`
13+
14+
## Hire-Me
15+
16+
<p align="center">Are you having trouble in your android projects then let me help you with it just Email me. I love my users, so feel free to visit http://asm.life
17+
18+
## Sample Screen
19+
20+
![](https://github.com/TutorialsAndroid/MTextField/blob/master/art/device-2019-04-16-132403.png)
21+
22+
## Installation
23+
In order to use it, you need to include it in your project.
24+
25+
#### Gradle:
26+
```groovy
27+
allprojects {
28+
repositories {
29+
...
30+
maven { url 'https://jitpack.io' }
31+
}
32+
}
33+
```
34+
```groovy
35+
dependencies {
36+
   implementation 'com.github.TutorialsAndroid:MTextField:v4.0.19'
37+
}
38+
```
39+
40+
## Usage
41+
42+
#### Table of Contents
43+
1. [Basic](#basic)
44+
2. [Enable / Disable](#enable)
45+
3. [Helper Text & Error Text](#helper)
46+
4. [Prefix & Suffix](#prefix)
47+
5. [Max & Min Characters](#max)
48+
6. [Icon Signifier](#icon)
49+
7. [End Icon](#end)
50+
8. [Clear Button](#clear)
51+
9. [Custom Colors](#color)
52+
10. [Dense Spacing](#dense)
53+
11. [Always Show Hint](#hint)
54+
12. [Text Change Watcher](#watcher)
55+
13. [Dark Theme](#dark)
56+
14. [Manual Validate Error](#validate)
57+
58+
#### <a id="basic"/> 1. Basic
59+
60+
Add `com.developer.mtextfield.TextFieldBoxes` that contains a `com.developer.mtextfield.ExtendedEditText` to your layout:
61+
62+
```xml
63+
...
64+
<com.developer.mtextfield.TextFieldBoxes
65+
android:id="@+id/text_field_boxes"
66+
android:layout_width="match_parent"
67+
android:layout_height="wrap_content"
68+
app:labelText="Label">
69+
70+
<com.developer.mtextfield.ExtendedEditText
71+
android:id="@+id/extended_edit_text"
72+
android:layout_width="wrap_content"
73+
android:layout_height="wrap_content"/>
74+
75+
</com.developer.mtextfield.TextFieldBoxes>
76+
...
77+
```
78+
79+
#### <a id="enable"/> 2. Enable / Disable
80+
81+
`app:enabled` in xml or `setEnabled(boolean enabled)` in Java.
82+
83+
```xml
84+
<com.developer.mtextfield.TextFieldBoxes
85+
...
86+
app:enabled="false"
87+
>
88+
```
89+
90+
#### <a id="helper"/> 3. Helper Text & Error Text
91+
92+
_**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._
93+
94+
helper text: `app:helperText` in xml or `setHelperText(String helperText)` in Java.
95+
96+
```xml
97+
<com.developer.mtextfield.TextFieldBoxes
98+
...
99+
app:helperText="Helper is here"
100+
>
101+
```
102+
103+
error text: `setError(String errorText, boolean giveFocus)` in Java.
104+
105+
Param `giveFocus` determines whether the field will gain focus when set error on. If `true`, the field gains focus immediately.
106+
107+
*NOTE: Error will be removed when the text changes (input or delete).*
108+
109+
```java
110+
setError("Error message");
111+
```
112+
113+
#### <a id="prefix"/> 4. Prefix & Suffix
114+
115+
_**! NOTE:** Prifix and Suffix attributes should be set to `ExtendedEditText`._
116+
117+
Use `app:prefix` in xml or `setPrefix(String prefix)` in Java to set the unselectable prefix text at the start of the field.
118+
119+
Use `app:suffix` in xml or `setSuffix(String suffix)` in Java to set the unselectable suffix text at the end of the field.
120+
121+
```xml
122+
<com.developer.mtextfield.ExtendedEditText
123+
...
124+
app:prefix="$ "
125+
>
126+
```
127+
128+
```xml
129+
<com.developer.mtextfield.ExtendedEditText
130+
...
131+
app:suffix="\@gmail.com"
132+
>
133+
```
134+
135+
#### <a id="max"/> 5. Max & Min Characters
136+
137+
_**NOTE:** setting max or min character will make the bottom view (which contains the counter label) visible and increase the height of the TextFieldBoxes._
138+
139+
Use `app:maxCharacters` in xml or `setMaxCharacters(int maxCharacters)` in java code to set the max characters count. Use `removeMaxCharacters()` in java code to remove the limit.
140+
141+
Use `app:minCharacters` in xml or `setMinCharacters(int minCharacters)` in java code to set the min characters count. Use `removeMinCharacters()` in java code to remove the limit.
142+
143+
The color of the bottom line will turn to `errorColor` (red by default) when exceeding max or min characters limit. `0`, as default, means no max or min characters limit.
144+
145+
*NOTE: Space and line feed will NOT count.*
146+
147+
```xml
148+
<com.developer.mtextfield.TextFieldBoxes
149+
...
150+
app:maxCharacters="10"
151+
app:minCharacters="5"
152+
>
153+
```
154+
155+
```xml
156+
<com.developer.mtextfield.TextFieldBoxes
157+
...
158+
app:maxCharacters="5"
159+
>
160+
```
161+
162+
#### <a id="icon"/> 6. Icon Signifier
163+
164+
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.
165+
166+
You can use `setIsResponsiveIconColor(boolean isrResponsiveIconColor)` in Java code to set whether the icon will change its color when gaining or losing focus as the label text and the bottomLine do.
167+
_**NOTE that if `true`, the icon's color will always be `HighlightColor` (the same as the bottomLine) that will turn gray when losing focus. If `false`, the icon will always be in `primaryColor`.**_
168+
169+
```xml
170+
<com.developer.mtextfield.TextFieldBoxes
171+
...
172+
app:iconSignifier="@drawable/ic_vpn_key_black_24dp"
173+
>
174+
```
175+
176+
#### <a id="end"/> 7. End Icon
177+
178+
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.
179+
180+
```xml
181+
<com.developer.mtextfield.TextFieldBoxes
182+
...
183+
app:endIcon="@drawable/ic_mic_black_24dp"
184+
>
185+
```
186+
187+
To make it useful (trigger voice input, dropdown event), you would like to use `getEndIconImageButton()` in Java code to set, for example, what will happen when it's clicked (with `.setOnClickListener()`), or anything else you want.
188+
189+
```java
190+
final TextFieldBoxes textFieldBoxes = findViewById(R.id.text_field_boxes);
191+
textFieldBoxes.getEndIconImageButton().setOnClickListener(new View.OnClickListener() {
192+
@Override
193+
public void onClick(View view) {
194+
// What you want to do when it's clicked
195+
}
196+
});
197+
```
198+
199+
#### <a id="clear"/> 8. Clear Button
200+
201+
Use `app:hasClearButton` in xml or `setHasClearButton(boolean hasClearButton)` to set whether to show the clear button.
202+
203+
If `true`, a clear button will be shown at the end when there are characters (**ANY** character) entered in the field.
204+
205+
```xml
206+
<com.developer.mtextfield.TextFieldBoxes
207+
...
208+
app:hasClearButton="true"
209+
>
210+
```
211+
212+
#### <a id="color"/> 9. Custom Colors
213+
214+
*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.
215+
216+
*Secondary Color* will be used for the color of the underline, the floating label text and the icon signifier **when NOT HAVING focus**. You can use `app:secondaryColor` in xml or `setSecondaryColor(int colorRes)` in Java. Current theme `textColorTertiary` by default.
217+
218+
*Error Color* will be used for the color that indicates error (e.g. exceeding max characters, `setError()`). You can use `app:errorColor` in xml or `setErrorColor(int colorRes)` in Java. `A400 red` by default.
219+
220+
*Helper Text Color* will be used for the color of the helper text. You can use `app:textHelperColor` in xml or `setHelperTextColor(int colorRes)` in Java. `54% black` by default.
221+
222+
*Panel Background Color* will be used for the color of panel at the back. You can use `app:panelBackgroundColor` in xml or `setPanelBackgroundColor(int colorRes)` in Java. `6% black` by default. *NOTE that the default color, as in the guideline, is the black (`#000000`) color with the transparency of 6%, so when you're customizing and want it to still be transparent you have to set a color with transparency.*
223+
224+
```xml
225+
<com.developer.mtextfield.TextFieldBoxes
226+
...
227+
app:primaryColor="#1B5E20"
228+
app:errorColor="#ddaa00"
229+
app:textHelperColor="#795548"
230+
app:panelBackgroundColor="#ffe8e8"
231+
>
232+
```
233+
234+
*Ripple Color* will be used for the ripple effect when the view is clicked. You can customize it in your `styles.xml` by adding the following:
235+
236+
```xml
237+
<style name="TextFieldBoxes">
238+
<item name="android:colorControlHighlight" tools:targetApi="lollipop">YOUR_COLOR</item>
239+
</style>
240+
```
241+
242+
then set this as the theme for your TextFieldBoxes:
243+
```xml
244+
<com.developer.mtextfield.TextFieldBoxes
245+
...
246+
android:theme="@style/TextFieldBoxes"
247+
>
248+
```
249+
250+
#### <a id="dense"/> 10. Dense Spacing
251+
252+
You can make the layout compact by using a dense verticle spacing to improve user experience in some cases.
253+
254+
Use `app:useDenseSpacing` in xml or `setUseDenseSpacing(boolean useDenseSpacing)` to set whether the field uses a dense spacing between its elements.
255+
256+
```xml
257+
<com.developer.mtextfield.TextFieldBoxes
258+
...
259+
app:useDenseSpacing="true"
260+
>
261+
```
262+
263+
#### <a id="hint"/> 11. Always Show Hint
264+
265+
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).
266+
267+
Use `app:alwaysShowHint` in xml or `setAlwaysShowHint(boolean alwaysShowHint)` to set whether the label is fixed at top when there's a hint in the EditText.
268+
269+
```xml
270+
<com.developer.mtextfield.TextFieldBoxes
271+
...
272+
app:alwaysShowHint="true"
273+
>
274+
```
275+
276+
#### <a id="watcher"/> 12. Text Change Watcher
277+
278+
It is strongly recommanded to use `setSimpleTextChangeWatcher()` to listen the event of changing text instead of `addTextChangedListener()`.
279+
280+
This has the following advantages:
281+
1. You don't need to implement `beforeTextChanged()` and `onTextChanged()` method when unnecessary.
282+
2. Avoids potential unexpected behavior, by guaranteeing your code to run after the default processes (remove error, update counter text, etc.) are finished.
283+
3. When the view is recycled, no manual remove call is needed.
284+
285+
e.g.
286+
```java
287+
final TextFieldBoxes textFieldBoxes = findViewById(R.id.text_field_boxes);
288+
textFieldBoxes.setSimpleTextChangeWatcher(new SimpleTextChangedWatcher() {
289+
@Override
290+
public void onTextChanged(String theNewText, boolean isError) {
291+
// What you want to do when text changes
292+
}
293+
});
294+
```
295+
296+
#### <a id="dark"/> 13. Dark Theme
297+
298+
MTextField use the color attributes within the current theme and will automatically change its color to fit the dark theme without additional settings.
299+
300+
#### <a id="validate"/> 14. Manual Validate Error
301+
302+
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.
303+
304+
Setting `app:manualValidateError` to `true` will make the field validate error only when `validate()` is called.
305+
306+
```xml
307+
<com.developer.mtextfield.TextFieldBoxes
308+
...
309+
app:manualValidateError="true"
310+
>
311+
```
312+
```Java
313+
final TextFieldBoxes textFieldBoxes = findViewById(R.id.text_field_boxes);
314+
// The error state will only be updated when this is called
315+
textFieldBoxes.validate()
316+
```
317+
​
318+
## All Attributes
319+
320+
### ExtendedEditText
321+
322+
##### Texts
323+
324+
| Attribute | Description |
325+
| --- | --- |
326+
| `app:prefix` | Prefix Text |
327+
| `app:suffix` | Suffix Text |
328+
329+
##### Colors
330+
331+
| Attribute | Description | Default |
332+
| --- | --- | --- |
333+
| `app:prefixTextColor` | Prefix text color | Current theme `textColorTertiary` |
334+
| `app:suffixTextColor` | Suffix text color | Current theme `textColorTertiary` |
335+
336+
### TextFieldBoxes
337+
338+
##### Texts
339+
340+
| Attribute | Description |
341+
| --- | --- |
342+
| `app:labelText` | Floating label text at the top |
343+
| `app:helperText` | Helper text at the bottom |
344+
345+
##### Colors
346+
347+
| Attribute | Description | Default |
348+
| --- | --- | --- |
349+
| `app:textHelperColor` | Helper text color | Current theme `textColorTertiary` |
350+
| `app:textCounterColor` | Counter text color | Current theme `textColorTertiary` |
351+
| `app:errorColor` | The color that is used to indicate error (e.g. exceeding max characters, `setError()`) | `A400 red` |
352+
| `app:primaryColor` | The color for the underline, the floating label text and the icon signifier **when HAVING FOCUS** | Current theme `colorPrimary` |
353+
| `app:secondaryColor` | The color for the underline, the floating label text and the icon signifier **when NOT HAVING FOCUS** | Current theme `textColorTertiary` |
354+
| `app:panelBackgroundColor` | The color for the panel at the back | 6% Current theme `colorForeground` |
355+
356+
##### Icons
357+
358+
| Attribute | Description | Default |
359+
| --- | --- | --- |
360+
| `app:iconSignifier` | The resource ID of the icon before the TextFieldBoxes | `0` |
361+
| `app:endIcon` | The resource ID of the icon at the end of the field | `0` |
362+
| `app:isResponsiveIconColor` | whether the icon signifier will change its color when gaining or losing focus as the label and the bottomLine do | `True` |
363+
364+
##### Characters counter
365+
366+
| Attribute | Description | Default |
367+
| --- | --- | --- |
368+
| `app:maxCharacters` | Max characters count limit. `0` means no limit | `0` |
369+
| `app:minCharacters` | Min characters count limit. `0` means no limit | `0` |
370+
371+
##### Others
372+
373+
| Attribute | Description | Default |
374+
| --- | --- | --- |
375+
| `app:enabled` | Whether the text field is enabled | `True` |
376+
| `app:hasClearButton` | Whether to show the clear button at the end of the EditText | `False` |
377+
| `app:hasFocus` | Whether the EditText is having the focus | `False` |
378+
| `app:alwaysShowHint` | Whether the label is fixed at top when there's a hint in the EditText | `False` |
379+
| `app:useDenseSpacing` | Whether the field uses a dense spacing between its elements | `False` |
380+
| `app:manualValidateError` | Whether to validate error state only when `validate()` is called | `False` |
381+
​
382+
383+
## License
384+
385+
Copyright 2019 MTextField
386+
387+
Licensed under the Apache License, Version 2.0 (the "License");
388+
you may not use this file except in compliance with the License.
389+
You may obtain a copy of the License at
390+
391+
http://www.apache.org/licenses/LICENSE-2.0
392+
393+
Unless required by applicable law or agreed to in writing, software
394+
distributed under the License is distributed on an "AS IS" BASIS,
395+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
396+
See the License for the specific language governing permissions and
397+
limitations under the License.

0 commit comments

Comments
 (0)