<commit_before># NumberPadTimePicker

Make time selections in Android by typing them.

As you type or remove digits, number keys and the "OK" button are enabled or disabled to prevent
you from setting invalid times. The time separator (e.g. ":") character is dynamically formatted 
into the correct position.

Available as an alert dialog, a bottom sheet dialog, and as a plain `View`.

<img src="screenshots/1.png" width="180" height="320"> <img src="screenshots/2.png" width="180" height="320"> <img src="screenshots/3.png" width="180" height="320"> <img src="screenshots/4.png" width="180" height="320">

1. [Sample App](#sample-app)
2. [Installation](#installation)
3. [Usage](#usage)
    1. [Use as Dialog]
    2. [Use as View](#use-as-view)
        1. [Define an OK Button](#define-an-ok-button)
        2. [Register OK Button Callbacks](#register-ok-button-callbacks)
4. [Themes and Styles]
5. [Contributing](#contributing)
6. [License](#license)

## Sample App

The sample app demos some built-in themes. You can also dynamically customize your own theme with a
limited color palette.

<a href='https://play.google.com/store/apps/details?id=com.philliphsu.numberpadtimepickersample&pcampaignid=MKT-Other-global-all-co-prtnr-py-PartBadge-Mar2515-1'><img alt='Get it on Google Play' src='https://play.google.com/intl/en_us/badges/images/generic/en_badge_web_generic.png' height="80px"/></a>

[Source code](/sample)

## Installation

```groovy
allprojects {
    repositories {
        maven { url 'https://jitpack.io' }
    }
}

dependencies {
    compile 'com.github.philliphsu:numberpadtimepicker:1.1.0'
}
```

## Usage

### Use as Dialog

Implement the standard `android.app.TimePickerDialog.OnTimeSetListener` interface.

```java
// The TimePicker returned in this callback is a dummy object. It is not
// the actual number pad time picker used by this library.
@Override
public void onTimeSet(TimePicker view, int hourOfDay, int minute) {
    // Do something with the time chosen by the user
}
```

Obtain an instance of [`NumberPadTimePickerDialog`] or [`BottomSheetNumberPadTimePickerDialog`]. 
You may pass in an optional style resource to use as the dialog's theme. Alternatively, you can 
theme the dialog programmatically after you've obtained an instance. See [Themes and Styles] for a 
guide to styling the dialog.

```java
NumberPadTimePickerDialog dialog = new NumberPadTimePickerDialog(
    context, R.style.MyAlertDialogTheme, listener, is24HourMode);

BottomSheetNumberPadTimePickerDialog dialog = new BottomSheetNumberPadTimePickerDialog(
    context, R.style.MyBottomSheetDialogTheme, listener, is24HourMode);
```

If you want to use the dialog in a `DialogFragment`, use the support library's
`android.support.v4.app.DialogFragment`. See the [Pickers guide] for more information.

### Use as View

Add a [`NumberPadTimePicker`] to your layout like any other `View`. However, by itself, it is not 
very useful as a widget for time input.

#### Define an OK Button

For a [`NumberPadTimePicker`] to actually be useful for time input, you need to define an "OK" 
button somewhere in your screen. For example, this can be a `View` in your layout or a 
`MenuItem` in your app bar.

For your convenience, this library provides ready-to-use "OK" buttons you can add to the 
[`NumberPadTimePicker`] instead of defining your own. These are the same buttons that are used
in the dialogs.

In your XML layout, specify the `nptp_numberPadTimePickerLayout` attribute on your 
[`NumberPadTimePicker`] with one of these values:

##### Table 1. Values for the `nptp_numberPadTimePickerLayout` attribute
Value       | Description<commit_msg>Add caveat to README about using NumberPadTimePicker in limited-height screen sizes<commit_after># NumberPadTimePicker

Make time selections in Android by typing them.

As you type or remove digits, number keys and the "OK" button are enabled or disabled to prevent
you from setting invalid times. The time separator (e.g. ":") character is dynamically formatted 
into the correct position.

Available as an alert dialog, a bottom sheet dialog, and as a plain `View`.

<img src="screenshots/1.png" width="180" height="320"> <img src="screenshots/2.png" width="180" height="320"> <img src="screenshots/3.png" width="180" height="320"> <img src="screenshots/4.png" width="180" height="320">

1. [Sample App](#sample-app)
2. [Installation](#installation)
3. [Usage](#usage)
    1. [Use as Dialog]
    2. [Use as View](#use-as-view)
        1. [Define an OK Button](#define-an-ok-button)
        2. [Register OK Button Callbacks](#register-ok-button-callbacks)
4. [Themes and Styles]
5. [Contributing](#contributing)
6. [License](#license)

## Sample App

The sample app demos some built-in themes. You can also dynamically customize your own theme with a
limited color palette.

<a href='https://play.google.com/store/apps/details?id=com.philliphsu.numberpadtimepickersample&pcampaignid=MKT-Other-global-all-co-prtnr-py-PartBadge-Mar2515-1'><img alt='Get it on Google Play' src='https://play.google.com/intl/en_us/badges/images/generic/en_badge_web_generic.png' height="80px"/></a>

[Source code](/sample)

## Installation

```groovy
allprojects {
    repositories {
        maven { url 'https://jitpack.io' }
    }
}

dependencies {
    compile 'com.github.philliphsu:numberpadtimepicker:1.1.0'
}
```

## Usage

### Use as Dialog

Implement the standard `android.app.TimePickerDialog.OnTimeSetListener` interface.

```java
// The TimePicker returned in this callback is a dummy object. It is not
// the actual number pad time picker used by this library.
@Override
public void onTimeSet(TimePicker view, int hourOfDay, int minute) {
    // Do something with the time chosen by the user
}
```

Obtain an instance of [`NumberPadTimePickerDialog`] or [`BottomSheetNumberPadTimePickerDialog`]. 
You may pass in an optional style resource to use as the dialog's theme. Alternatively, you can 
theme the dialog programmatically after you've obtained an instance. See [Themes and Styles] for a 
guide to styling the dialog.

```java
NumberPadTimePickerDialog dialog = new NumberPadTimePickerDialog(
    context, R.style.MyAlertDialogTheme, listener, is24HourMode);

BottomSheetNumberPadTimePickerDialog dialog = new BottomSheetNumberPadTimePickerDialog(
    context, R.style.MyBottomSheetDialogTheme, listener, is24HourMode);
```

If you want to use the dialog in a `DialogFragment`, use the support library's
`android.support.v4.app.DialogFragment`. See the [Pickers guide] for more information.

### Use as View

> Using [`NumberPadTimePicker`] as a `View` requires more care to ensure it is sized appropriately
in your layouts. As of version 1.1.0, [`NumberPadTimePicker`] is not optimized for small screen 
heights (for example, in landscape). If you are affected by this, you'll need to account for this
in a way that is appropriate for your use case.

Add a [`NumberPadTimePicker`] to your layout like any other `View`. However, by itself, it is not 
very useful as a widget for time input.

#### Define an OK Button

For a [`NumberPadTimePicker`] to actually be useful for time input, you need to define an "OK" 
button somewhere in your screen. For example, this can be a `View` in your layout or a 
`MenuItem` in your app bar.

For your convenience, this library provides ready-to-use "OK" buttons you can add to the 
[`NumberPadTimePicker`] instead of defining your own. These are the same buttons that are used
in the dialogs.

In your XML layout, specify the `nptp_numberPadTimePickerLayout` attribute on your 
[`NumberPadTimePicker`] with one of these values:

##### Table 1. Values for the `nptp_numberPadTimePickerLayout` attribute
Value       | Description
{'fraction_non_alphanumeric': 0.1009983145339038, 'fraction_numerical': 0.014391287436795021, 'mean_word_length': 4.659574468085107, 'pattern_counts': {'":': 2, '<': 17, '<?xml version=': 0, '>': 18, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3763699', 'n_tokens_mistral': 2399, 'n_tokens_neox': 2264, 'n_words': 884}