Skip to content

Commit

Permalink
Mainly integrate new code examples for button.
Browse files Browse the repository at this point in the history
  • Loading branch information
FabienLelaquais committed Oct 5, 2024
1 parent 5f72e8a commit 0a1002c
Show file tree
Hide file tree
Showing 11 changed files with 118 additions and 27 deletions.
114 changes: 101 additions & 13 deletions docs/refmans/gui/viselements/generic/button.md_template
Original file line number Diff line number Diff line change
Expand Up @@ -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:
<figure>
<img src="../button-simple-d.png" class="visible-dark" />
<img src="../button-simple-l.png" class="visible-light"/>
<figcaption>A simple button</figcaption>
</figure>

## 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.<br/>
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:
<figure>
<img src="../button_icon-d.png" class="visible-dark" />
<img src="../button_icon-l.png" class="visible-light"/>
<figcaption>Icon in a button</figcaption>
</figure>

# 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:

Expand Down Expand Up @@ -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:
<figure class="tp-center">
<img src="../button_styling-d.png" class="visible-dark" />
<img src="../button_styling-l.png" class="visible-light" />
<figcaption>Styling the button control</figcaption>
</figure>

The corners of the button are no longer rounded (`border-radius: 0`) and the text color has been
changed to green (`color: green`).
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 2 additions & 2 deletions docs/refmans/gui/viselements/generic/dialog.md_template
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -179,7 +179,7 @@ When *show_dialog* is set to True, the dialog will display two buttons at the bo
</figure>

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

Expand Down
4 changes: 2 additions & 2 deletions docs/tutorials/articles/jupyter_notebooks/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/userman/advanced_features/configuration/gui-config.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
- <a name="p-port_auto_ranges"></a>*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"..<br/>
configuration parameter is set to "auto".<br/>
This parameter must be a list of tuples, each containing two integers that specify the start
and end of a port range.
- <a name="p-async_mode"></a>*async_mode* (str or None, default: "gevent"): specifies the
Expand Down
21 changes: 12 additions & 9 deletions docs/userman/gui/pages/builder.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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.<br/>
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.<br/>
When run, the application would show a page looking like this:
<figure>
<img src="../tgb-1-d.png" class="visible-dark" />
Expand Down Expand Up @@ -81,7 +82,8 @@ Note how, in the `input^` control, we use the property names of the control as p
class constructor.
<br/>
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")
```
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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":
Expand Down

0 comments on commit 0a1002c

Please sign in to comment.