Skip to content

Commit 23156e2

Browse files
delacrixmorgandelacrixmorgan
authored
Update README with Compose Documentation (#38)
1 parent 2d1d01c commit 23156e2

File tree

3 files changed

+228
-7
lines changed

3 files changed

+228
-7
lines changed

‎README.md‎

Lines changed: 228 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,11 @@
22

33
Android library that provides a number keyboard composable.
44

5-
![screenshot](img/screenshot.jpg)
5+
![screenshot](img/screenshot.png)
66

77
## Usage
88

9-
#### Step 1
9+
### Step 1
1010

1111
Add the JitPack repository to your `build.gradle ` file:
1212

@@ -19,23 +19,23 @@ allprojects {
1919
}
2020
```
2121

22-
#### Step 2
22+
### Step 2
2323

2424
Add the dependency:
2525

2626
```gradle
2727
dependencies {
28-
implementation 'com.github.davidmigloz:number-keyboard:4.0.0'
28+
implementation 'com.github.davidmigloz:number-keyboard:4.0.2'
2929
}
3030
```
3131

3232
[CHANGELOG](https://github.com/davidmigloz/number-keyboard/blob/master/CHANGELOG.md)
3333

34-
> **Note:** in v4.0.0 the library was migrated to Jetpack Compose. If you need to old Android View based version, please keep using v3.1.0 instead.
34+
> **Note:** in v4.0.0 the library was migrated to Jetpack Compose. If you need to old Android View based version, please keep using [v3.1.0](https://github.com/davidmigloz/number-keyboard/tree/3.1.0) instead.
3535
36-
#### Step 3
36+
### Step 3
3737

38-
Use `NumberKeyboard` composable in your layout:
38+
#### Use `NumberKeyboard` Composable in your layout:
3939

4040
```kotlin
4141
NumberKeyboard(
@@ -74,6 +74,227 @@ NumberKeyboard(
7474
)
7575
```
7676

77+
##### Attribute
78+
79+
- `maxAllowedAmount` - Double (default: 10_000.0): Maximum amount allowed for the `NumberKeyboard` output
80+
- `maxAllowedDecimals` - Int (default: 2): Maximum decimal points allowed for the `NumberKeyboard` output
81+
- `currencySymbol` - String (default: "$"): Currency symbol for the `NumberKeyboardData` currency format output
82+
- `isInverted` - Boolean (default: false): Default number sequence is the phone number pad sequence, inverted is the calculator number pad sequence
83+
- `roundUpToMax` - Boolean (default: true): Behaviour to round up to the max allowed amount if amount has exceeded
84+
- `verticalArrangement` - Arrangement.HorizontalOrVertical (default: 8.dp): Vertical spacing between the buttons
85+
- `horizontalArrangement` - Arrangement.HorizontalOrVertical (default: 8.dp): Horizontal spacing between the buttons
86+
- `decimalSeparator` - Char (default: DecimalFormat.decimalFormatSymbols.decimalSeparator): Character for decimal separator
87+
- `groupingSeparator` - Char (default: DecimalFormat.decimalFormatSymbols.groupingSeparator): Character for grouping separator
88+
89+
##### Composable
90+
91+
To harness the power and flexibility of Jetpack Compose, `NumberKeyboard` now provides `@Composable` lambdas that gives you control over all the button layouts.
92+
Thus, you can easily customise it with shadows, different shapes or even different locales!
93+
94+
1) `button: @Composable (Int, NumberKeyboardClickedListener) -> Unit,`
95+
- `value` - Int: Number of the button pressed
96+
- `listener` - NumberKeyboardClickedListener: Click listener for all buttons, left aux button and right aux button if applicable.
97+
98+
2) `leftAuxButton, rightAuxButton: @Composable ((NumberKeyboardClickedListener) -> Unit)? = null`
99+
- `listener` - NumberKeyboardClickedListener: Click listener for all buttons, left aux button and right aux button if applicable.
100+
101+
For `NumberKeyboardClickedListener`, it is a click listener for all buttons in `NumberKeyboard`.
102+
Inside `NumberKeyboard`, there is a `NumberKeyboardClickedListener` instance that will be used to format the output through `NumberKeyboardListener`.
103+
104+
If you wish to have more control, you can easily just have a `NumberKeyboardClickedListener` at your Fragment level.
105+
106+
```kotlin
107+
interface NumberKeyboardClickedListener {
108+
fun onNumberClicked(number: Int)
109+
fun onLeftAuxButtonClicked()
110+
fun onRightAuxButtonClicked()
111+
}
112+
```
113+
114+
There is an out-of-box `NumberKeyboardButton` that you can use to quickly get started, it's basically a wrapped `OutlineButton.Text`.
115+
116+
```kotlin
117+
@Composable
118+
fun NumberKeyboardButton(
119+
modifier: Modifier,
120+
textStyle: TextStyle,
121+
shape: Shape = RoundedCornerShape(size = 8.dp),
122+
haptics: HapticFeedback = LocalHapticFeedback.current,
123+
number: Int,
124+
listener: NumberKeyboardClickedListener
125+
) {
126+
OutlinedButton(
127+
modifier = modifier,
128+
shape = shape,
129+
border = BorderStroke(1.dp, Color.LightGray),
130+
onClick = {
131+
haptics.performHapticFeedback(HapticFeedbackType.LongPress)
132+
listener.onNumberClicked(number)
133+
}
134+
) {
135+
Text(
136+
text = number.toString(),
137+
style = textStyle
138+
)
139+
}
140+
}
141+
```
142+
143+
##### NumberKeyboardListener
144+
145+
This listener is _optional_, but if you want to utilise this. Make sure that the `NumberKeyboardClickedListener` is configured properly when you are building your button layouts.
146+
After configuration, it will provide `NumberKeyboardData` that has the `rawAmount` from the `NumberKeyboard` inout and it's variation of Integer and Float variable types.
147+
148+
```kotlin
149+
interface NumberKeyboardListener {
150+
fun onUpdated(data: NumberKeyboardData)
151+
}
152+
153+
class NumberKeyboardData(
154+
amount: String,
155+
private val decimalSeparator: Char,
156+
private val groupingSeparator: Char,
157+
private val currencySymbol: String
158+
) {
159+
val rawAmount: String = amount.ifEmpty { "0" }
160+
161+
// Integer
162+
val byte: Byte
163+
get() = rawAmount.normaliseNumber().toInt().toByte()
164+
165+
val short: Short
166+
get() = rawAmount.normaliseNumber().toInt().toShort()
167+
168+
val int: Int
169+
get() = rawAmount.normaliseNumber().toInt()
170+
171+
val long: Long
172+
get() = rawAmount.normaliseNumber().toLong()
173+
174+
// Floating-point
175+
val float: Float
176+
get() = rawAmount.normaliseNumber().toFloat()
177+
178+
val double: Double
179+
get() = rawAmount.normaliseNumber()
180+
181+
val currency: String
182+
get() = formatCurrency(rawAmount, decimalSeparator, groupingSeparator, currencySymbol)
183+
}
184+
```
185+
186+
##### Examples
187+
188+
1) Integer `NumberKeyboard`
189+
[Sample](https://github.com/davidmigloz/number-keyboard/blob/master/sample/src/main/java/com/davidmiguel/sample/IntegerScreen.kt)
190+
191+
```kotlin
192+
val maxAllowedDecimals: Int = 0
193+
```
194+
195+
2) Decimal `NumberKeyboard`
196+
[Sample](https://github.com/davidmigloz/number-keyboard/blob/master/sample/src/main/java/com/davidmiguel/sample/DecimalScreen.kt)
197+
198+
```kotlin
199+
val maxAllowedAmount: Double = 10_000.00
200+
val maxAllowedDecimals: Int = 2
201+
val currencySymbol: String = "$"
202+
```
203+
204+
3) Biometric `NumberKeyboard`
205+
[Sample](https://github.com/davidmigloz/number-keyboard/blob/master/sample/src/main/java/com/davidmiguel/sample/BiometricScreen.kt)
206+
207+
```kotlin
208+
val maxAllowedAmount: Double = 9_999.0
209+
val maxAllowedDecimals: Int = 0
210+
val roundUpToMax: Boolean = false
211+
```
212+
213+
4) Custom `NumberKeyboard`
214+
[Sample](https://github.com/davidmigloz/number-keyboard/blob/master/sample/src/main/java/com/davidmiguel/sample/CustomScreen.kt)
215+
216+
```kotlin
217+
val maxAllowedAmount: Double = 8_888.88
218+
val maxAllowedDecimals: Int = 3
219+
val currencySymbol: String = "€"
220+
val isInverted: Boolean = true
221+
```
222+
223+
---
224+
225+
#### Use `NumberKeyboard` AndroidView <= [v3.1.0](https://github.com/davidmigloz/number-keyboard/tree/3.1.0) XML view in your layout:
226+
227+
```xml
228+
<com.davidmiguel.numberkeyboard.NumberKeyboard
229+
xmlns:android="http://schemas.android.com/apk/res/android"
230+
xmlns:keyboard="http://schemas.android.com/apk/res-auto"
231+
...
232+
keyboard:numberkeyboard_keyboardType="integer"
233+
... />
234+
```
235+
236+
##### Attributes
237+
238+
- `keyboard:numberkeyboard_keyboardType="[integer|decimal|fingerprint|custom]"` (required): defines the type of keyboard.
239+
- `integer`: numbers and backspace keys.
240+
- `decimal`: numbers, comma and backspace keys.
241+
- `fingerprint`: numbers, fingerprint and backspace keys.
242+
- `custom`: numbers and defined auxiliary keys.
243+
- `keyboard:numberkeyboard_keyWidth="[dimension]"` (default: `match_parent`): key width (`wrap_content` not allowed).
244+
- `keyboard:numberkeyboard_keyHeight="[dimension]"` (default: `match_parent`): key height (`wrap_content` not allowed).
245+
- `keyboard:numberkeyboard_keyPadding="[dimension]"` (default: `16dp`): key padding.
246+
- `keyboard:numberkeyboard_numberKeyBackground="[reference]"` (default: circle): number keys background drawable.
247+
- `keyboard:numberkeyboard_numberKeyTextColor="[reference]"` (default: dark blue): number keys text color.
248+
- `keyboard:numberkeyboard_numberKeyTypeface="[reference]"` (default: dark blue): number keys text color.
249+
- `keyboard:numberkeyboard_numberKeyTypeface="[reference]"` (default: none): number keys text typeface.
250+
- `keyboard:numberkeyboard_numberKeyTextSize="[dimension]"` (default: none): number keys text size (if it is not set, the text auto scales to fit the key).
251+
- `keyboard:numberkeyboard_leftAuxBtnBackground="[reference]"` (default: none): if `keyboardType="custom"`, left auxiliary button background.
252+
- `keyboard:numberkeyboard_rightAuxBtnIcon="[reference]"` (default: none): if `keyboardType="custom"`, icon shown in right auxiliary button.
253+
- `keyboard:numberkeyboard_rightAuxBtnBackground="[reference]"` (default: none): if `keyboardType="custom"`, right auxiliary button background.
254+
255+
##### Methods
256+
257+
- `hideLeftAuxButton()`: hides left auxiliary button.
258+
- `showLeftAuxButton()`: shows left auxiliary button.
259+
- `hideRightAuxButton()`: hides right auxiliary button.
260+
- `showRightAuxButton()`: shows right auxiliary button.
261+
- `setKeyWidth()`: sets key width in px.
262+
- `setKeyHeight()`: sets key height in px.
263+
- `setKeyPadding()`: sets key padding in px.
264+
- `setNumberKeyBackground()`: sets number keys background.
265+
- `setNumberKeyTextColor()`: sets number keys text color.
266+
- `setNumberKeyTypeface()`: sets number keys text typeface.
267+
- `setNumberKeyTextSize()`: sets number keys text size in pixels.
268+
- `setLeftAuxButtonIcon()`: sets left auxiliary button icon.
269+
- `setRightAuxButtonIcon()`: sets right auxiliary button icon.
270+
- `setLeftAuxButtonBackground()`: sets left auxiliary button background.
271+
- `setRightAuxButtonBackground()`: sets right auxiliary button background.
272+
273+
##### Callback
274+
275+
To listen to keyboard events, you have to use `NumberKeyboardListener`:
276+
277+
- `onNumberClicked()`: invoked when a number key is clicked.
278+
- `onLeftAuxButtonClicked()`: invoked when the left auxiliary button is clicked.
279+
- `onRightAuxButtonClicked()`: invoked when the right auxiliary button is clicked.
280+
281+
```kotlin
282+
numberKeyboard.setListener(object: NumberKeyboardListener {
283+
override fun onNumberClicked(number: Int) {
284+
...
285+
}
286+
287+
override fun onLeftAuxButtonClicked() {
288+
...
289+
}
290+
291+
override fun onRightAuxButtonClicked() {
292+
...
293+
}
294+
})
295+
```
296+
297+
77298
Take a look at the [sample app](https://github.com/davidmigloz/number-keyboard/tree/master/sample) to see the library working.
78299

79300
## Contributing

‎img/screenshot.jpg‎

-109 KB
Binary file not shown.

‎img/screenshot.png‎

248 KB
Loading

0 commit comments

Comments
 (0)