{"id":18010262,"url":"https://github.com/philliphsu/numberpadtimepicker","last_synced_at":"2025-03-26T14:31:56.661Z","repository":{"id":201842915,"uuid":"94269521","full_name":"philliphsu/NumberPadTimePicker","owner":"philliphsu","description":"Make time selections in Android by typing them.","archived":false,"fork":false,"pushed_at":"2017-08-02T19:55:10.000Z","size":636,"stargazers_count":57,"open_issues_count":0,"forks_count":8,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-21T23:23:14.425Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/philliphsu.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2017-06-14T00:07:40.000Z","updated_at":"2024-04-17T11:43:38.000Z","dependencies_parsed_at":null,"dependency_job_id":"43021104-7f93-4d0b-8360-57af200b98b6","html_url":"https://github.com/philliphsu/NumberPadTimePicker","commit_stats":null,"previous_names":["philliphsu/numberpadtimepicker"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philliphsu%2FNumberPadTimePicker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philliphsu%2FNumberPadTimePicker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philliphsu%2FNumberPadTimePicker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philliphsu%2FNumberPadTimePicker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/philliphsu","download_url":"https://codeload.github.com/philliphsu/NumberPadTimePicker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245670796,"owners_count":20653424,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-30T02:13:29.773Z","updated_at":"2025-03-26T14:31:56.197Z","avatar_url":"https://github.com/philliphsu.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NumberPadTimePicker\n\nMake time selections in Android by typing them.\n\nAs you type or remove digits, number keys and the \"OK\" button are enabled or disabled to prevent\nyou from setting invalid times. The time separator (e.g. \":\") character is dynamically formatted \ninto the correct position.\n\nAvailable as an alert dialog, a bottom sheet dialog, and as a plain `View`.\n\n\u003cimg src=\"screenshots/1.png\" width=\"180\" height=\"320\"\u003e \u003cimg src=\"screenshots/2.png\" width=\"180\" height=\"320\"\u003e \u003cimg src=\"screenshots/3.png\" width=\"180\" height=\"320\"\u003e \u003cimg src=\"screenshots/4.png\" width=\"180\" height=\"320\"\u003e\n\n1. [Sample App](#sample-app)\n2. [Installation](#installation)\n3. [Usage](#usage)\n    1. [Use as Dialog]\n    2. [Use as View](#use-as-view)\n        1. [Define an OK Button](#define-an-ok-button)\n        2. [Register OK Button Callbacks](#register-ok-button-callbacks)\n4. [Themes and Styles]\n5. [Contributing](#contributing)\n6. [License](#license)\n\n## Sample App\n\nThe sample app demos some built-in themes. You can also dynamically customize your own theme with a\nlimited color palette.\n\n\u003ca href='https://play.google.com/store/apps/details?id=com.philliphsu.numberpadtimepickersample\u0026pcampaignid=MKT-Other-global-all-co-prtnr-py-PartBadge-Mar2515-1'\u003e\u003cimg alt='Get it on Google Play' src='https://play.google.com/intl/en_us/badges/images/generic/en_badge_web_generic.png' height=\"80px\"/\u003e\u003c/a\u003e\n\n[Source code](/sample)\n\n## Installation\n\n```groovy\nallprojects {\n    repositories {\n        maven { url 'https://jitpack.io' }\n    }\n}\n\ndependencies {\n    compile 'com.github.philliphsu:numberpadtimepicker:1.1.1'\n}\n```\n\n## Usage\n\n### Use as Dialog\n\nImplement the `android.app.TimePickerDialog.OnTimeSetListener` interface.\n\n```java\n// The TimePicker returned in this callback is a dummy object. It is not\n// the actual NumberPadTimePicker used by this library.\n@Override\npublic void onTimeSet(TimePicker view, int hourOfDay, int minute) {\n    // Do something with the time chosen by the user\n}\n```\n\nObtain an instance of [`NumberPadTimePickerDialog`] or [`BottomSheetNumberPadTimePickerDialog`]. \nYou may pass in an optional style resource to use as the dialog's theme. Alternatively, you can \ntheme the dialog programmatically after you've obtained an instance. See [Themes and Styles] for a \nguide to styling the dialog.\n\n```java\nNumberPadTimePickerDialog dialog = new NumberPadTimePickerDialog(\n    context, R.style.MyNptpAlertDialogTheme, listener, is24HourMode);\n\nBottomSheetNumberPadTimePickerDialog dialog = new BottomSheetNumberPadTimePickerDialog(\n    context, R.style.MyNptpBottomSheetDialogTheme, listener, is24HourMode);\n```\n\nIf you want to use the dialog in a `DialogFragment`, use the support library's\n`android.support.v4.app.DialogFragment`. See the [Pickers guide] for more information.\n\n### Use as View\n\n\u003e Using [`NumberPadTimePicker`] as a `View` requires more care to ensure it is sized appropriately\nin your layouts. As of version 1.1.0, [`NumberPadTimePicker`] is not optimized for small screen \nheights (for example, in landscape). If you are affected by this, you'll need to account for this\nin a way that is appropriate for your use case.\n\nAdd a [`NumberPadTimePicker`] to your layout like any other `View`. However, by itself, it is not \nvery useful as a widget for time input.\n\n#### Define an OK Button\n\nFor a [`NumberPadTimePicker`] to actually be useful for time input, you need to define an \"OK\" \nbutton somewhere in your screen. For example, this can be a `View` in your layout or a \n`MenuItem` in your app bar.\n\nFor your convenience, this library provides ready-to-use \"OK\" buttons you can add to the \n[`NumberPadTimePicker`] instead of defining your own. These are the same buttons that are used\nin the dialogs.\n\nIn your XML layout, specify the `nptp_numberPadTimePickerLayout` attribute on your \n[`NumberPadTimePicker`] with one of these values:\n\n##### Table 1. Values for the `nptp_numberPadTimePickerLayout` attribute\nValue       | Description\n------------|--------------------------------------------------------------------------------------\nstandalone  | The default value. No additional views will be added to the `NumberPadTimePicker`.\nalert       | Adds alert-style action buttons (\"Cancel\", \"OK\") to the `NumberPadTimePicker`.\nbottomSheet | Adds a `FloatingActionButton` to the `NumberPadTimePicker`.\n\n```xml\n\u003ccom.philliphsu.numberpadtimepicker.NumberPadTimePicker\n    xmlns:app=\"http://schemas.android.com/apk/res-auto\"\n    app:nptp_numberPadTimePickerLayout=[\"standalone\" | \"alert\" | \"bottomSheet\"]\n    ... \n    /\u003e\n```\n\n#### Register OK Button Callbacks\n\n```java\nView okButton = ...\n\nNumberPadTimePicker timePicker = ...\ntimePicker.setOkButtonCallbacks(new NumberPadTimePicker.OkButtonCallbacks() {\n    @Override\n    public void onOkButtonEnabled(boolean enabled) {\n        // If you are using the provided OK buttons, you do not need to do anything.\n        okButton.setEnabled(enabled);\n    }\n\n    @Override\n    public void onOkButtonClick(NumberPadTimePicker view, int hourOfDay, int minute) {\n        // Do something with the time chosen by the user\n    }\n});\n\n// If you are using the provided OK buttons, you do not need to set this.\nokButton.setOnClickListener(new View.OnClickListener() {\n    @Override\n    public void onClick(View v) {\n        timePicker.confirmTimeSelection();  // Calls your onOkButtonClick() callback\n    }\n});\n```\n\nIf you are using the `alert` layout, you may also want to set a click listener on the provided \ncancel button:\n \n```java\ntimePicker.setCancelButtonClickListener(new View.OnClickListener() {\n    @Override\n    public void onClick(View v) {\n        // Respond to cancel click \n    }\n});\n```\n\n## Themes and Styles\n\nThis section describes how to style the [`NumberPadTimePicker`] view, which is used in the dialogs \nand is available to use in your own layouts.\n\nYou can style the view in XML or in code.\n\n[`NumberPadTimePickerDialog`], [`BottomSheetNumberPadTimePickerDialog`], and the \n[`NumberPadTimePicker`] view all have a method called `getThemer()`. This returns an object allowing\nyou to theme the time picker in code by chaining setters.\n\nThere are two return types to be aware of: [`NumberPadTimePickerThemer`] and \n[`BottomSheetNumberPadTimePickerThemer`].\n\n* [`NumberPadTimePickerDialog`] returns a [`NumberPadTimePickerThemer`].\n* [`BottomSheetNumberPadTimePickerDialog`] returns a [`BottomSheetNumberPadTimePickerThemer`].\n* [`NumberPadTimePicker`] returns a [`NumberPadTimePickerThemer`], which can possibly be \ncasted to [`BottomSheetNumberPadTimePickerThemer`].\n\nThe following table lists styleable attributes available in all [layouts][Table 1]. These correspond\nto setters in [`NumberPadTimePickerThemer`].\n\n### Table 2. Common styleable attributes\n\nAttribute                | Description\n-------------------------|------------------------------------------------------------------------\nnptp_numberPadTimePickerLayout | Determines the presence and appearance of additional dialog buttons. See [Table 1] for possible values.\nnptp_inputTimeTextColor  | Text color for the inputted time in the header.\nnptp_inputAmPmTextColor  | Text color for the inputted AM/PM in the header.\nnptp_backspaceTint       | Tint to apply to the backspace icon. This should be a color state list with enabled and disabled states.\nnptp_numberKeysTextColor | Text color for the number keys. This should be a color state list with enabled and disabled states.\nnptp_altKeysTextColor    | Text color for the \"AM\"/\"PM\" keys in 12-hour mode or the \":00\"/\":30\" keys in 24-hour mode. This should be a color state list with enabled and disabled states.\nnptp_headerBackground    | Background of the header containing the inputted time and AM/PM. This can be a color or a drawable.\nnptp_divider             | Divider separating the header from the number pad. This can be a color or a drawable.\nnptp_numberPadBackground | Background of the number pad. This can be a color or a drawable.\nnptp_is24HourMode        | Whether the number pad should use 24-hour mode.\n\nThe following table lists styleable attributes available only for the `bottomSheet` layout.\nThese correspond to setters in [`BottomSheetNumberPadTimePickerThemer`].\n\n### Table 3. Bottom sheet styleable attributes\n\nAttribute                      | Description\n-------------------------------|------------------------------------------------------------------\nnptp_fabBackgroundColor        | Background color of the `FloatingActionButton`. This should be a color state list with enabled and disabled states.\nnptp_animateFabBackgroundColor | Whether the `FloatingActionButton` should transition between its enabled and disabled colors. Does not apply if `nptp_showFab` is set to `validTime`.\nnptp_fabRippleColor            | Ripple color of the `FloatingActionButton` when pressed.\nnptp_animateFabIn              | Whether the `FloatingActionButton` should animate onto the screen when the dialog is shown. Does not apply if `nptp_showFab` is set to `validTime`.\nnptp_showFab                   | Indicates when the `FloatingActionButton` should be shown. Either `always` or `validTime`.\nnptp_backspaceLocation         | Location of the backspace key. Either `header` or `footer`.\nnptp_fabIconTint               | Tint to apply to the icon in the `FloatingActionButton`. This should be a color state list with enabled and disabled states.\n\nIf you are using [`NumberPadTimePicker`] in your own layouts, you may find it convenient to specify\none of the following styles. These styles adjust `layout_width` and `layout_height` for multiple \nsize qualifiers.\n\n* `NPTP_NumberPadTimePickerStandaloneStyle_FillHeight`\n* `NPTP_NumberPadTimePickerStandaloneStyle_ExactHeight`\n* `NPTP_NumberPadTimePickerAlertStyle_FillHeight`\n* `NPTP_NumberPadTimePickerAlertStyle_ExactHeight`\n* `NPTP_NumberPadTimePickerBottomSheetStyle_FillHeight`\n* `NPTP_NumberPadTimePickerBottomSheetStyle_ExactHeight`\n\n```xml\n\u003ccom.philliphsu.numberpadtimepicker.NumberPadTimePicker\n    style=\"@style/NPTP_NumberPadTimePickerStandaloneStyle_FillHeight\"\n    ... \n    /\u003e\n```\n\nYou can create a theme for a dialog or `Activity` that uses [`NumberPadTimePicker`].\n\nCreate a style resource using the attributes in [Table 2] and [Table 3]. There are default \nstyle resources that you may inherit from:\n\n* `NPTP_Base_NumberPadTimePickerStandaloneStyle`\n* `NPTP_Base_NumberPadTimePickerAlertStyle`\n* `NPTP_Base_NumberPadTimePickerBottomSheetStyle`\n\nSet this style resource in your theme using the `nptp_numberPadTimePickerStyle` attribute.\n\n```xml\n\u003cstyle name=\"MyNptpAlertStyle\" parent=\"NPTP_Base_NumberPadTimePickerAlertStyle\"\u003e\n    ...\n\u003c/style\u003e\n\n\u003cstyle name=\"MyNptpAlertDialogTheme\" parent=\"Theme.AppCompat.Dialog.Alert\"\u003e\n    \u003citem name=\"nptp_numberPadTimePickerStyle\"\u003e@style/MyNptpAlertStyle\u003c/item\u003e\n\u003c/style\u003e\n\n\u003cstyle name=\"MyNptpBottomSheetStyle\" parent=\"NPTP_Base_NumberPadTimePickerBottomSheetStyle\"\u003e\n    ...\n\u003c/style\u003e\n\n\u003cstyle name=\"MyNptpBottomSheetDialogTheme\" parent=\"Theme.Design.BottomSheetDialog\"\u003e\n    \u003citem name=\"nptp_numberPadTimePickerStyle\"\u003e@style/MyNptpBottomSheetStyle\u003c/item\u003e\n\u003c/style\u003e\n```\n\nObtain an instance of the dialog as described in [Use as Dialog]. If you don't want to pass\nthe theme to the dialog's constructor, you can instead specify it in your `Activity`'s theme.\n\n```xml\n\u003cstyle name=\"AppTheme\" parent=\"Theme.AppCompat\"\u003e\n    \u003citem name=\"nptp_numberPadTimePickerAlertDialogTheme\"\u003e@style/MyNptpAlertDialogTheme\u003c/item\u003e\n    \u003citem name=\"nptp_numberPadTimePickerBottomSheetDialogTheme\"\u003e@style/MyNptpBottomSheetDialogTheme\u003c/item\u003e\n\u003c/style\u003e\n```\n\n## Contributing\n\nContributions are welcome. In particular, contributions to optimize dimensions for any form factor \nor to improve localization are appreciated. Send pull requests to the `develop` branch. If you think \nsomething could look better, feel free to let me know your thoughts.\n\n## License\n\n```\nCopyright 2017 Phillip Hsu\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n\n[pickers guide]: https://developer.android.com/guide/topics/ui/controls/pickers.html#TimePicker\n[Themes and Styles]: #themes-and-styles\n[Use as Dialog]: #use-as-dialog\n[Table 1]: #table-1-values-for-the-nptp_numberpadtimepickerlayout-attribute\n[Table 2]: #table-2-common-styleable-attributes\n[Table 3]: #table-3-bottom-sheet-styleable-attributes\n[`NumberPadTimePickerDialog`]: library/src/main/java/com/philliphsu/numberpadtimepicker/NumberPadTimePickerDialog.java\n[`BottomSheetNumberPadTimePickerDialog`]: library/src/main/java/com/philliphsu/numberpadtimepicker/BottomSheetNumberPadTimePickerDialog.java\n[`NumberPadTimePicker`]: library/src/main/java/com/philliphsu/numberpadtimepicker/NumberPadTimePicker.java\n[`NumberPadTimePickerThemer`]: library/src/main/java/com/philliphsu/numberpadtimepicker/NumberPadTimePickerThemer.java\n[`BottomSheetNumberPadTimePickerThemer`]: library/src/main/java/com/philliphsu/numberpadtimepicker/BottomSheetNumberPadTimePickerThemer.java","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilliphsu%2Fnumberpadtimepicker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphilliphsu%2Fnumberpadtimepicker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilliphsu%2Fnumberpadtimepicker/lists"}