diff --git a/docs/manuals/gui/viselements/slider-date-range-d.png b/docs/manuals/gui/viselements/slider-date-range-d.png new file mode 100644 index 000000000..0f6e49feb Binary files /dev/null and b/docs/manuals/gui/viselements/slider-date-range-d.png differ diff --git a/docs/manuals/gui/viselements/slider-date-range-l.png b/docs/manuals/gui/viselements/slider-date-range-l.png new file mode 100644 index 000000000..be881acbc Binary files /dev/null and b/docs/manuals/gui/viselements/slider-date-range-l.png differ diff --git a/docs/manuals/gui/viselements/slider-lov-d.png b/docs/manuals/gui/viselements/slider-lov-d.png new file mode 100644 index 000000000..60b65baca Binary files /dev/null and b/docs/manuals/gui/viselements/slider-lov-d.png differ diff --git a/docs/manuals/gui/viselements/slider-lov-l.png b/docs/manuals/gui/viselements/slider-lov-l.png new file mode 100644 index 000000000..06254f54d Binary files /dev/null and b/docs/manuals/gui/viselements/slider-lov-l.png differ diff --git a/docs/manuals/gui/viselements/slider-multiple-d.png b/docs/manuals/gui/viselements/slider-multiple-d.png new file mode 100644 index 000000000..b2e8b2af6 Binary files /dev/null and b/docs/manuals/gui/viselements/slider-multiple-d.png differ diff --git a/docs/manuals/gui/viselements/slider-multiple-l.png b/docs/manuals/gui/viselements/slider-multiple-l.png new file mode 100644 index 000000000..a6cc10bba Binary files /dev/null and b/docs/manuals/gui/viselements/slider-multiple-l.png differ diff --git a/docs/manuals/gui/viselements/slider-orientation-d.png b/docs/manuals/gui/viselements/slider-orientation-d.png new file mode 100644 index 000000000..b6383b22d Binary files /dev/null and b/docs/manuals/gui/viselements/slider-orientation-d.png differ diff --git a/docs/manuals/gui/viselements/slider-orientation-l.png b/docs/manuals/gui/viselements/slider-orientation-l.png new file mode 100644 index 000000000..d415a792b Binary files /dev/null and b/docs/manuals/gui/viselements/slider-orientation-l.png differ diff --git a/docs/manuals/gui/viselements/slider-range-d.png b/docs/manuals/gui/viselements/slider-range-d.png new file mode 100644 index 000000000..9ed6b026c Binary files /dev/null and b/docs/manuals/gui/viselements/slider-range-d.png differ diff --git a/docs/manuals/gui/viselements/slider-range-l.png b/docs/manuals/gui/viselements/slider-range-l.png new file mode 100644 index 000000000..8a8cb5541 Binary files /dev/null and b/docs/manuals/gui/viselements/slider-range-l.png differ diff --git a/docs/manuals/gui/viselements/slider-simple-d.png b/docs/manuals/gui/viselements/slider-simple-d.png new file mode 100644 index 000000000..226d274b5 Binary files /dev/null and b/docs/manuals/gui/viselements/slider-simple-d.png differ diff --git a/docs/manuals/gui/viselements/slider-simple-l.png b/docs/manuals/gui/viselements/slider-simple-l.png new file mode 100644 index 000000000..8b709b720 Binary files /dev/null and b/docs/manuals/gui/viselements/slider-simple-l.png differ diff --git a/docs/manuals/gui/viselements/slider.md_template b/docs/manuals/gui/viselements/slider.md_template index 82082b7ea..f7fc8a8b9 100644 --- a/docs/manuals/gui/viselements/slider.md_template +++ b/docs/manuals/gui/viselements/slider.md_template @@ -12,10 +12,9 @@ name to select the sliders on your page and apply style. ## Usage -### Selecting a value between 0 and 100 +### Selecting a value in a range {data-source="gui:doc/examples/elements/slider-simple.py"} -A numeric value can easily be represented and interacted with using the -following content: +A numeric value can easily be represented and interacted with using the following content: !!! example "Page content" @@ -31,9 +30,20 @@ following content: {value} ``` -### Constraining values +The page contains a slider that looks like this: +
+ + +
A simple slider
+
-You can specify what bounds the value should be restrained to: +The user can pick the slider knob and move it around to select a value within the default range +[0, 100]. + +### Setting the slider range {data-source="gui:doc/examples/elements/slider-range.py"} + +You can specify, in the [*min*](#p-min) and [*max*](#p-max) properties, what bounds the selected +value should be constrained to: !!! example "Page content" @@ -49,8 +59,17 @@ You can specify what bounds the value should be restrained to: {value} ``` -### Changing orientation +The resulting slider looks like this: +
+ + +
Custom range
+
+### Changing orientation {data-source="gui:doc/examples/elements/slider-orientation.py"} + +A slider can also be vertical if the [*orientation*](#p-orientation) property is set to a string +beginning with the letter "v". !!! example "Page content" @@ -63,5 +82,148 @@ You can specify what bounds the value should be restrained to: === "HTML" ```html - {value} + {value} + ``` + +And now the slider is displayed vertically: +
+ + +
Changing the default orientation
+
+ +### Select among a list of values {data-source="gui:doc/examples/elements/slider-lov.py"} + +A slider can also allow users to select a value from a list of predefined values.
+To do this, you must set the [*lov*](#p-lov) property to a list of values: + +!!! example "Page content" + + === "Markdown" + + ``` + <|{value}|slider|lov=XXS;XS;S;M;L;XL;XXL|> + ``` + + === "HTML" + + ```html + {value} + ``` + +Then only those values are accessible by the user: +
+ + +
List of values
+
+ +### Multi selection {data-source="gui:doc/examples/elements/slider-multiple.py"} + +You can use a slider control to display multiple values and let users select each.
+To achieve that, the [*value*](#p-value) property must be initially set to an array containing +the initial values to reflect. The slider will have one knob for each value.
+When the user moves any of the knobs, the [*on_change*](../../callbacks.md#variable-value-change) +is invoked with the variable value set to an array containing the new selection. + +Let's create an initial value for our slider: +```py +values = [20, 40, 80] +``` + +And use this variable as the [*value*](#p-value) property value: + +!!! example "Page content" + + === "Markdown" + + ``` + <|{values}|slider|> + ``` + + === "HTML" + + ```html + {values} ``` + +Because the initial value is an array with three values, the slider is displayed with three knobs +that the user can move: +
+ + +
Multiple values
+
+ +### Date range selection {data-source="gui:doc/examples/elements/slider-date-range.py"} + +You can create a slider to select a date range, combining the use of the [*lov*](#p-lov) property +with a multi-knob slider.
+Note that this can work only if your base date range (the one the user can pick from) is small enough +or it could be tricky for users to select a specific date. + +Here is an example that lets you select a date range taken from an entire year. + +You need to initialize an array of date strings that will be shown to the user as knobs are moved +along the slider: + +```py +# Create the list of dates (all year 2000) +all_dates = {} +all_dates_str = [] +start_date = date(2000, 1, 1) +end_date = date(2001, 1, 1) +a_date = start_date +while a_date < end_date: + date_str = a_date.strftime("%Y/%m/%d") + all_dates_str.append(date_str) + all_dates[date_str] = a_date + a_date += timedelta(days=1) + +# Initial selection: first and last day +dates=[all_dates_str[1], all_dates_str[-1]] +# These two variables are used in text controls +start_sel = all_dates[dates[0]] +end_sel = all_dates[dates[1]] +``` + +Now, *all_dates_str* contains the list of all dates the user can choose from. We will use that +array as the value of the [*value*](#p-value) property.
+*dates* holds the initial date range selection. + +*start_sel* and *end_sel* are string values that can be used in text controls as a visual feedback.
+We need to update these variables when the user picks new dates: + +```py +def on_change(state, _, var_value): + # Update the text controls + state.start_sel = all_dates[var_value[0]] + state.end_sel = all_dates[var_value[1]] +``` + +This callback will receive, in *var_value*, the array of the two selected dates. We can simply update +*start_sel* and *end_sel* accordingly. + +The slider control definition is the following: + +!!! example "Page content" + + === "Markdown" + + ``` + <|{dates}|slider|lov={all_dates_str}|> + ``` + + === "HTML" + + ```html + {dates} + ``` + +And this is what this date range picker looks like: + +
+ + +
Date range selection
+