diff --git a/docs/refmans/gui/viselements/generic/button.md_template b/docs/refmans/gui/viselements/generic/button.md_template index 8330e3cb1..fa53861d0 100644 --- a/docs/refmans/gui/viselements/generic/button.md_template +++ b/docs/refmans/gui/viselements/generic/button.md_template @@ -2,44 +2,105 @@ A control that can trigger a function when pressed. # Usage -## Simple button +## Simple button {data-source="gui:doc/examples/controls/button_simple.py"} -The button label, which is the button control's default property, is simply displayed as the button -text. +The label of the button, defined by the default property [*label*](#p-label) of the button control, +is displayed as the text on the button. +Below is an example of how to define a button: !!! taipy-element default=Button Label +Here is how the button is displayed:
A simple button
-## Specific action callback +## Specific action callback {data-source="gui:doc/examples/controls/button_action.py"} -Button can specify a callback function to be invoked when the button is pressed. +A button can specify a callback function to be invoked when it is pressed. By default, the global +function *on_action()* is triggered by the `on_action` callback if it is defined, as described in +the [section on callbacks](../../../../userman/gui/callbacks.md). -If you want some function called *button_pressed()* to be invoked when the user presses a button, -you can define this function as follows: -```py +To define a custom callback function for a button press, you can set the [*on_action*](#p-on_action) +property to reference the specific callback function you want to invoke. + +Here is an example of defining such a callback function, named *button_pressed()*: +```python def button_pressed(state): - # React to the button press action + # React to the button press action ``` -Then refer to this function in the definition of the control, as the value of the button's -[*on_action*](#p-on_action) property: - +You can then assign this function to the button's [*on_action*](#p-on_action) property: !!! taipy-element default=Button Label on_action:f=button_pressed +When the user presses the button, the callback function *button_pressed()* is triggered. + +The appearance of the button remains the same, even with a callback function bound to it. + +## Action as a lambda function {data-source="gui:doc/examples/controls/button_lambda.py"} + +A callback function can be defined as a lambda function to handle button actions. + +Below is an example of defining a button using a lambda function for the [*on_action*](#p-on_action) +property: +!!! taipy-element + default=Button Label + id=button1 + on_action:f=lambda s, i, p: s.assign("text", f"button '{i}': '{p.get('action')}'.") + +The lambda function takes the same parameters as a standard `on_action` callback: + +- *s* (the state object), +- *i* (the control id), and +- *p* (a payload dictionary, where the "action" key holds the action name). + +In this example, the lambda function sets the *text* variable to a string that includes the button's +id and the action name.
+This variable can be used by another control, and any change to its value triggers the `on_change` +callback as expected. + +Note that when using a lambda function, the action name may appear as a mangled symbol generated by +the Python interpreter. + +## Using an icon {data-source="gui:doc/examples/controls/button_icon.py"} + +A button can contain text, an icon, or both. + +To add an icon to a button, you must first create an instance of the `Icon^` object, which +represents the image and its associated label (text). + +To add an icon to a button, you must create an `Icon^` instance: +```python +icon = Icon("charles-avatar.png", "Charles") +``` + +The variable *icon* contains the path path of the image file used as the icon (in this example, the +file should be located in the same directory as the Python script) and the text label that will +appear next to the icon. + +Once you have created the icon instance, you can assign it to the button's [*label*](#p-label) +property: +!!! taipy-element + default={icon} + +This will display both the image and the associated text ("Charles") on the button: +
+ + +
Icon in a button
+
+ # Styling All the button controls are generated with the "taipy-button" CSS class. You can use this class name to select the buttons on your page and apply style. -## [Stylekit](../../../../userman/gui/styling/stylekit.md) support +## [Stylekit](../../../../userman/gui/styling/stylekit.md) support {data-source="gui:doc/examples/controls/button_stylekit.py"} The [Stylekit](../../../../userman/gui/styling/stylekit.md) provides specific classes that you can use to style buttons: @@ -78,3 +139,30 @@ The [Stylekit](../../../../userman/gui/styling/stylekit.md) provides specific cl * *fullwidth*: The button is rendered on its own line and expands across the entire available width. + +## Customizing with CSS {data-source="gui:doc/examples/controls/button_styling.py"} + +You can apply all relevant CSS properties to customize the appearance of the button control. + +We can add a specific CSS class to the button's definition: +!!! taipy-element + default=Button Label + class_name=my-style + +This class can be used to create a CSS rule specifically for this button: +```css +.taipy-button.my-style { + border-radius: 0; + color: green; +} +``` + +When this CSS rule is applied, the button will be styled as shown below: +
+ + +
Styling the button control
+
+ +The corners of the button are no longer rounded (`border-radius: 0`) and the text color has been +changed to green (`color: green`). diff --git a/docs/refmans/gui/viselements/generic/button_icon-d.png b/docs/refmans/gui/viselements/generic/button_icon-d.png new file mode 100644 index 000000000..b80a3b8b4 Binary files /dev/null and b/docs/refmans/gui/viselements/generic/button_icon-d.png differ diff --git a/docs/refmans/gui/viselements/generic/button_icon-l.png b/docs/refmans/gui/viselements/generic/button_icon-l.png new file mode 100644 index 000000000..0ef13b987 Binary files /dev/null and b/docs/refmans/gui/viselements/generic/button_icon-l.png differ diff --git a/docs/refmans/gui/viselements/generic/button_stylekit-d.png b/docs/refmans/gui/viselements/generic/button_stylekit-d.png new file mode 100644 index 000000000..56559873d Binary files /dev/null and b/docs/refmans/gui/viselements/generic/button_stylekit-d.png differ diff --git a/docs/refmans/gui/viselements/generic/button_stylekit-l.png b/docs/refmans/gui/viselements/generic/button_stylekit-l.png new file mode 100644 index 000000000..48c2c5969 Binary files /dev/null and b/docs/refmans/gui/viselements/generic/button_stylekit-l.png differ diff --git a/docs/refmans/gui/viselements/generic/button_styling-d.png b/docs/refmans/gui/viselements/generic/button_styling-d.png new file mode 100644 index 000000000..e015d194c Binary files /dev/null and b/docs/refmans/gui/viselements/generic/button_styling-d.png differ diff --git a/docs/refmans/gui/viselements/generic/button_styling-l.png b/docs/refmans/gui/viselements/generic/button_styling-l.png new file mode 100644 index 000000000..e9c1a0fab Binary files /dev/null and b/docs/refmans/gui/viselements/generic/button_styling-l.png differ diff --git a/docs/refmans/gui/viselements/generic/dialog.md_template b/docs/refmans/gui/viselements/generic/dialog.md_template index f9fa90389..96fe3cb37 100644 --- a/docs/refmans/gui/viselements/generic/dialog.md_template +++ b/docs/refmans/gui/viselements/generic/dialog.md_template @@ -164,7 +164,7 @@ def dialog_action(state, _, payload): state.show_dialog = False ``` -The payload["args"][0] value indicates which button was pressed: +The *payload["args"]\[0\]* value indicates which button was pressed: - 0: The first button ("Couldn't be better") was pressed. - 1: The second button ("Not my day") was pressed. - -1: The Close button of the dialog was pressed. @@ -179,7 +179,7 @@ When *show_dialog* is set to True, the dialog will display two buttons at the bo If the user presses the first button, "COULDN'T BE BETTER", the *dialog_action()* callback will be -invoked with *payload["args"][0]* set to 0. +invoked with *payload["args"]\[0\]* set to 0. ## Dialog with page diff --git a/docs/tutorials/articles/jupyter_notebooks/index.md b/docs/tutorials/articles/jupyter_notebooks/index.md index 1760c139b..b5a6f768d 100644 --- a/docs/tutorials/articles/jupyter_notebooks/index.md +++ b/docs/tutorials/articles/jupyter_notebooks/index.md @@ -24,10 +24,10 @@ and rerun all cells, which can be cumbersome. To solve this and enhance the experience of using Taipy in Jupyter Notebook, we should utilize two straightforward functions for updating the user interface after making changes to our code: -1. [Page.set_content()](../../../refmans/reference/pkg_taipy/pkg_gui/Page#taipy.gui.Page.set_content): +1. [Page.set_content()](../../../refmans/reference/pkg_taipy/pkg_gui/Page/index.md#taipy.gui.Page.set_content): Use this method when you update the content of a page. -2. [Gui.reload()](../../../refmans/reference/pkg_taipy/pkg_gui/Gui#taipy.gui.Gui.reload): Use this +2. [Gui.reload()](../../../refmans/reference/pkg_taipy/pkg_gui/Gui/index.md#taipy.gui.Gui.reload): Use this method when you modify a variable that's used in a page. # Modifying Page Content diff --git a/docs/userman/advanced_features/configuration/gui-config.md b/docs/userman/advanced_features/configuration/gui-config.md index 06f81dbfa..b2bc85696 100644 --- a/docs/userman/advanced_features/configuration/gui-config.md +++ b/docs/userman/advanced_features/configuration/gui-config.md @@ -164,7 +164,7 @@ Here is the list of the configuration parameters you can use in Note that this setting is forced to True when running in a Notebook context. - *port_auto_ranges* (list[tuple[int,int]]), default: [(49152, 65535)]: defines the ranges of port numbers to be used when the [*port*](#p-port) - configuration parameter is set to "auto"..
+ configuration parameter is set to "auto".
This parameter must be a list of tuples, each containing two integers that specify the start and end of a port range. - *async_mode* (str or None, default: "gevent"): specifies the diff --git a/docs/userman/gui/pages/builder.md b/docs/userman/gui/pages/builder.md index 95a211db6..d072c3531 100644 --- a/docs/userman/gui/pages/builder.md +++ b/docs/userman/gui/pages/builder.md @@ -3,14 +3,15 @@ title: The Page Builder API --- The Page Builder API is a set of classes located in the -[`taipy.gui.builder`](../../../refmans/reference/pkg_taipy/pkg_gui/pkg_builder/index.md) package that lets users -create Taipy GUI pages entirely from Python code. +[`taipy.gui.builder`](../../../refmans/reference/pkg_taipy/pkg_gui/pkg_builder/index.md) package +that lets users create Taipy GUI pages entirely from Python code. This package contains a class for every visual element available in Taipy, including those defined in [extension libraries](../extension/index.md). To access the Page Builder classes, you must import the -[`taipy.gui.builder`](../../../refmans/reference/pkg_taipy/pkg_gui/pkg_builder/index.md) package in your script. +[`taipy.gui.builder`](../../../refmans/reference/pkg_taipy/pkg_gui/pkg_builder/index.md) package in +your script. # Generating a new page @@ -42,8 +43,8 @@ with tgb.Page() as page: tgb.input() ``` -In this example, we add an empty [`input`](../../../refmans/gui/viselements/generic/input.md) control by creating a new -instance of the `(builder.)input^` class.
+In this example, we add an empty [`input`](../../../refmans/gui/viselements/generic/input.md) +control by creating a new instance of the `(builder.)input^` class.
When run, the application would show a page looking like this:
@@ -81,7 +82,8 @@ Note how, in the `input^` control, we use the property names of the control as p class constructor.
The first parameter is set to the element's default property. Because *value* is the default -property for the [`input`](../../../refmans/gui/viselements/generic/input.md) control, we could have built the control using: +property for the [`input`](../../../refmans/gui/viselements/generic/input.md) control, we could have +built the control using: ```python tgb.input(label="First name", value="John") ``` @@ -117,7 +119,8 @@ Compared to the previous example, you can see that the label uses a bold font we code. !!! warning "Indexed properties" - Some elements of Taipy GUI (such as [`chart`](../../../refmans/gui/viselements/generic/chart.md), + Some elements of Taipy GUI (such as + [`chart`](../../../refmans/gui/viselements/generic/chart.md), [`table`](../../../refmans/gui/viselements/generic/table.md), or [`layout`](../../../refmans/gui/viselements/generic/layout.md)) have *indexed properties*. The syntax to express these property names, where the *root name* of the property @@ -237,8 +240,8 @@ Default callbacks are invoked if not explicitly assigned to callback properties. Consider the following script: ```python -from src.taipy.gui import Gui -import src.taipy.gui.builder as tgb +from taipy.gui import Gui +import taipy.gui.builder as tgb def on_action(state, id): if id == "my_button":