diff --git a/picker/src/main/java/org/fknives/android/compose/picker/time/DefaultAMPMList.kt b/picker/src/main/java/org/fknives/android/compose/picker/time/DefaultAMPMList.kt index 2f5a3d4..12b06fd 100644 --- a/picker/src/main/java/org/fknives/android/compose/picker/time/DefaultAMPMList.kt +++ b/picker/src/main/java/org/fknives/android/compose/picker/time/DefaultAMPMList.kt @@ -5,10 +5,16 @@ import androidx.compose.runtime.remember import java.text.DateFormatSymbols import java.util.Locale +/** + * Returns Default AM, PM texts for given [locale]. + */ fun defaultAmPmStrings(locale: Locale = Locale.getDefault()) = DateFormatSymbols.getInstance(locale).amPmStrings.toList() +/** + * Caches the [defaultAmPmStrings]. + */ @Composable fun rememberDefaultAMPMList(locale: Locale = Locale.getDefault()) = remember(locale) { - DateFormatSymbols.getInstance(locale).amPmStrings.toList() + defaultAmPmStrings(locale = locale) } \ No newline at end of file diff --git a/picker/src/main/java/org/fknives/android/compose/picker/time/SelectedTime.kt b/picker/src/main/java/org/fknives/android/compose/picker/time/SelectedTime.kt index 86df882..ac14a26 100644 --- a/picker/src/main/java/org/fknives/android/compose/picker/time/SelectedTime.kt +++ b/picker/src/main/java/org/fknives/android/compose/picker/time/SelectedTime.kt @@ -3,6 +3,9 @@ package org.fknives.android.compose.picker.time import androidx.compose.runtime.Immutable import java.util.Calendar +/** + * Selection state object, representing current selection of [TimePicker] + */ @Immutable data class SelectedTime( val hour: Int, @@ -11,6 +14,10 @@ data class SelectedTime( ) { companion object { + /** + * Creates [SelectedTime] from the given unix [time] stamp. + * Defaults to Current Time. + */ fun get(time: Long = System.currentTimeMillis()): SelectedTime { val calendar = Calendar.getInstance() calendar.timeInMillis = time diff --git a/picker/src/main/java/org/fknives/android/compose/picker/time/TimePicker.kt b/picker/src/main/java/org/fknives/android/compose/picker/time/TimePicker.kt index 49bea71..f012159 100644 --- a/picker/src/main/java/org/fknives/android/compose/picker/time/TimePicker.kt +++ b/picker/src/main/java/org/fknives/android/compose/picker/time/TimePicker.kt @@ -8,12 +8,25 @@ import org.fknives.android.compose.picker.number.NumberPickerConfig import org.fknives.android.compose.picker.number.rememberNumberPickerScope import org.fknives.android.compose.picker.number.rememberNumberPickerState +/** + * Sets up Time Pickers. + * Expected to contain an Hour, Minute and AM/PM Picker, respectively, Number, Number and TextPicker. + * + * Creates a [TimePickerScope] which then is feeded to [timePickers]. + * + * @param timePickersMinWidth MinWidth given for each TimePicker. + * @param selectedTime currently selected [SelectedTime] + * @param onSelectedTimeChanged notified when [SelectedTime] should be changes by User Actions. + * @param amPm the list of translated texts for "AM" and "PM". Expected order is AM,PM. + * @param timePickers the actual Composable for TimePickers. + * *Note: Check Defaults for customization: [StandardTimePickers]. + */ @Composable fun TimePicker( timePickersMinWidth: Dp = 40.dp, selectedTime: SelectedTime, - amPm: List = rememberDefaultAMPMList(), onSelectedTimeChanged: (SelectedTime) -> Unit, + amPm: List = rememberDefaultAMPMList(), timePickers: @Composable (TimePickerScope) -> Unit = { StandardTimePickers(it) } ) { val hourConfig = remember { NumberPickerConfig.configHourPicker12 } diff --git a/picker/src/main/java/org/fknives/android/compose/picker/time/TimePickerScope.kt b/picker/src/main/java/org/fknives/android/compose/picker/time/TimePickerScope.kt index 2804b9b..26a5ff8 100644 --- a/picker/src/main/java/org/fknives/android/compose/picker/time/TimePickerScope.kt +++ b/picker/src/main/java/org/fknives/android/compose/picker/time/TimePickerScope.kt @@ -7,6 +7,11 @@ import androidx.compose.ui.unit.Dp import org.fknives.android.compose.picker.number.NumberPickerScope import org.fknives.android.compose.picker.text.util.TextPickerDefaults +/** + * Scope setup from [TimePicker]. + * + * Contains all the Values for the respective Hour, Minute and AMorPM Pickers. + */ @Immutable interface TimePickerScope { val timePickerMinWidth: Dp @@ -15,6 +20,9 @@ interface TimePickerScope { val amORpmPickerScope: AMorPMPickerScope } +/** + * Data class implementation of [TimePickerScope] + */ @Immutable data class TimePickerScopeImpl( override val timePickerMinWidth: Dp, @@ -23,6 +31,10 @@ data class TimePickerScopeImpl( override val amORpmPickerScope: AMorPMPickerScope ) : TimePickerScope +/** + * Intended scope for AMorPM Picker. + * Contained within [TimePickerScope] + */ @Immutable interface AMorPMPickerScope { val listOfAMorPM: List @@ -31,6 +43,9 @@ interface AMorPMPickerScope { val onIndexDifferenceChanging: (Int) -> Unit } +/** + * Data class implementation of [AMorPMPickerScope] + */ @Immutable data class AMorPMPickerScopeImpl( override val listOfAMorPM: List, @@ -39,6 +54,9 @@ data class AMorPMPickerScopeImpl( override val onIndexDifferenceChanging: (Int) -> Unit = TextPickerDefaults.onIndexDifferenceChanging ) : AMorPMPickerScope +/** + * Caching function for [AMorPMPickerScope] + */ @Composable fun rememberAMorPMPickerScope( listOfAMorPM: List, @@ -57,6 +75,9 @@ fun rememberAMorPMPickerScope( } } +/** + * Caching function for [TimePickerScope] + */ @Composable fun rememberTimePickerScope( timePickerMinWidth: Dp, diff --git a/picker/src/main/java/org/fknives/android/compose/picker/time/TimePickerScopeExtensions.kt b/picker/src/main/java/org/fknives/android/compose/picker/time/TimePickerScopeExtensions.kt index daf64ac..139593a 100644 --- a/picker/src/main/java/org/fknives/android/compose/picker/time/TimePickerScopeExtensions.kt +++ b/picker/src/main/java/org/fknives/android/compose/picker/time/TimePickerScopeExtensions.kt @@ -10,6 +10,11 @@ import org.fknives.android.compose.picker.number.CustomInnerTextPicker import org.fknives.android.compose.picker.text.TextPicker import org.fknives.android.compose.picker.text.util.TextPickerDefaults +/** + * Default Pickers for [TimePicker]. + * + * Gets values from [scope] and creates the respective Pickers. + */ @Composable fun StandardTimePickers(scope: TimePickerScope) { Row { @@ -21,6 +26,11 @@ fun StandardTimePickers(scope: TimePickerScope) { } } +/** + * Default Hour Picker for [TimePicker] + * + * Gets values from [TimePickerScope.hoursPickerScope]. + */ @Composable fun TimePickerScope.HourPicker( modifier: Modifier = Modifier, @@ -36,6 +46,12 @@ fun TimePickerScope.HourPicker( } } +/** + * Default Hour Picker for [TimePicker] + * + * Gets values from [TimePickerScope.minutesPickerScope]. + */ + @Composable fun TimePickerScope.MinutePicker( modifier: Modifier = Modifier, @@ -51,6 +67,11 @@ fun TimePickerScope.MinutePicker( } } +/** + * Default Hour Picker for [TimePicker] + * + * Gets values from [TimePickerScope.amORpmPickerScope]. + */ @Composable fun TimePickerScope.IsAMorPMPicker( modifier: Modifier = Modifier, diff --git a/picker/src/main/java/org/fknives/android/compose/picker/time/clock/ClockPicker.kt b/picker/src/main/java/org/fknives/android/compose/picker/time/clock/ClockPicker.kt index 0eac8b3..022d539 100644 --- a/picker/src/main/java/org/fknives/android/compose/picker/time/clock/ClockPicker.kt +++ b/picker/src/main/java/org/fknives/android/compose/picker/time/clock/ClockPicker.kt @@ -19,9 +19,28 @@ import org.fknives.android.compose.picker.time.rememberDefaultAMPMList import org.fknives.android.compose.picker.time.rememberTimePickerScope import kotlin.math.abs +/** + * Custom [TimePicker][org.fknives.android.compose.picker.time.TimePicker] implementation. + * + * Main difference is that this implementation contains additional interactions between the elements: + * - When Hour Rotates Around (1 -by decrease-> 12 or 12 -by increase-> 1) the AM/PM Picker is automatically updated. + * - When Minute Rotates Around (0 -by decrease-> 59 or 59 by increase-> 0) the Hour Picker is updated + * (if that rotates around the AM/PM also) + * + * These updates are just on the UI while selecting, they become permanent, aka [onSelectedTimeChanged] notified only when the user lets go. + * + * Creates a Custom Implementation [TimePickerScope] which then is feeded to [timePickers]. + * + * @param timePickersMinWidth MinWidth given for each TimePicker. + * @param selectedTime currently selected [SelectedTime] + * @param onSelectedTimeChanged notified when [SelectedTime] should be changes by User Actions. + * @param amPm the list of translated texts for "AM" and "PM". Expected order is AM,PM. + * @param timePickers the actual Composable for TimePickers. + * *Note: Check Defaults for customization: [StandardTimePickers]. + */ @Composable fun ClockTimePicker( - timePickerMinWidth: Dp = 40.dp, + timePickersMinWidth: Dp = 40.dp, selectedTime: SelectedTime, amPm: List = rememberDefaultAMPMList(), onSelectedTimeChanged: (SelectedTime) -> Unit, @@ -80,7 +99,7 @@ fun ClockTimePicker( ) val scope = rememberTimePickerScope( - timePickerMinWidth = timePickerMinWidth, + timePickerMinWidth = timePickersMinWidth, hoursPickerScope = hourScope, minutesPickerScope = minutesScope, amORpmPickerScope = amORpmScope