Gui class
Entry point for the Graphical User Interface generation.
Note
This class belongs to and is documented in the taipy.gui
package, but it is
accessible from the top taipy
package to simplify its access, allowing to
use:
from taipy import Gui
Attributes¶
on_action
instance-attribute
¶
on_action: Optional[Callable] = None
The function called when a control triggers an action, as the result of an end-user's interaction.
It defaults to the on_action()
global function defined in the Python
application. If there is no such function, actions will not trigger anything.
The signature of the on_action callback function must be:
- state: the
State
instance of the caller. - id (optional): a string representing the identifier of the caller.
- payload (optional): an optional payload from the caller.
on_change
instance-attribute
¶
on_change: Optional[Callable] = None
The function called when a control modifies bound variables, as the result of an end-user's interaction.
It defaults to the on_change()
global function defined in the Python
application. If there is no such function, user interactions will not trigger
anything.
The signature of the on_change callback function must be:
- state: the
State
instance of the caller. - var_name (str): The name of the variable that triggered this callback.
- var_value (any): The new value for this variable.
on_exception
instance-attribute
¶
on_exception: Optional[Callable] = None
The function that is called an exception occurs on user code.
It defaults to the on_exception()
global function defined in the Python
application. If there is no such function, exceptions will not trigger
anything.
The signature of the on_exception callback function must be:
- state: the
State
instance of the caller. - function_name: the name of the function that raised the exception.
- exception: the exception object that was raised.
on_init
instance-attribute
¶
on_init: Optional[Callable] = None
The function that is called on the first connection of a new client.
It defaults to the on_init()
global function defined in the Python
application. If there is no such function, the first connection will not trigger
anything.
The signature of the on_init callback function must be:
- state: the
State
instance of the caller.
on_navigate
instance-attribute
¶
on_navigate: Optional[Callable] = None
The function that is called when a page is requested.
It defaults to the on_navigate()
global function defined in the Python
application. If there is no such function, page requests will not trigger
anything.
The signature of the on_navigate callback function must be:
- state: the
State
instance of the caller. - page_name: the name of the page the user is navigating to.
- params (Optional): the query parameters provided in the URL.
The on_navigate callback function must return the name of the page the user should be directed to.
on_page_load
instance-attribute
¶
on_page_load: Optional[Callable] = None
This callback is invoked just before the page content is sent to the front-end.
It defaults to the on_page_load()
global function defined in the Python
application. If there is no such function, page loads will not trigger
anything.
The signature of the on_page_load callback function must be:
- state: the State
instance of the caller.
- page_name: the name of the page that is being loaded.
on_status
instance-attribute
¶
on_status: Optional[Callable] = None
The function that is called when the status page is shown.
It defaults to the on_status()
global function defined in the Python
application. If there is no such function, status page content shows only the status of the
server.
The signature of the on_status callback function must be:
- state: the
State
instance of the caller.
It must return raw and valid HTML content as a string.
on_user_content
instance-attribute
¶
on_user_content: Optional[Callable] = None
The function that is called when a specific URL (generated by get_user_content_url()
) is requested.
This callback function must return the raw HTML content of the page to be displayed on the browser.
This attribute defaults to the on_user_content()
global function defined in the Python
application. If there is no such function, those specific URLs will not trigger
anything.
The signature of the on_user_content callback function must be:
- state: the
State
instance of the caller. - path: the path provided to the
get_user_content_url()
to build the URL. - parameters: An optional dictionary as defined in the
get_user_content_url()
call.
The returned HTML content can therefore use both the variables stored in the state
and the parameters provided in the call to get_user_content_url()
.
Methods¶
__init__() ¶
__init__(
page: t.Optional[t.Union[str, Page]] = None,
pages: t.Optional[dict] = None,
css_file: t.Optional[str] = None,
path_mapping: t.Optional[dict] = None,
env_filename: t.Optional[str] = None,
libraries: t.Optional[t.List[ElementLibrary]] = None,
flask: t.Optional[Flask] = None,
)
Initialize a new Gui instance.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
page |
Optional[Union[str, Page]]
|
An optional |
None
|
pages |
Optional[dict]
|
Used if you want to initialize this instance with a set
of pages. |
None
|
css_file |
Optional[str]
|
A pathname to a CSS file that gets used as a style sheet in
all the pages. |
None
|
path_mapping |
Optional[dict]
|
A dictionary that associates a URL prefix to
a path in the server file system. |
None
|
env_filename |
Optional[str]
|
An optional file from which to load application
configuration variables (see the
Configuration
section of the User Manual for details.) |
None
|
libraries |
Optional[List[ElementLibrary]]
|
An optional list of extension library
instances that pages can reference. |
None
|
flask |
Optional[Flask]
|
An optional instance of a Flask application object. |
None
|
add_library()
staticmethod
¶
add_library(library: ElementLibrary) -> None
Add a custom visual element library.
This application will be able to use custom visual elements defined in this library.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
library |
ElementLibrary
|
The custom visual element library to add to this application. |
required |
Multiple libraries with the same name can be added. This allows to split multiple custom visual
elements in several ElementLibrary
instances, but still refer to these elements with the same
prefix in the page definitions.
add_page() ¶
add_page(
name: str,
page: t.Union[str, Page],
style: t.Optional[str] = "",
) -> None
Add a page to the Graphical User Interface.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
name |
str
|
The name of the page. |
required |
page |
Union[str, Page]
|
required | |
style |
Optional[str]
|
Additional CSS style to apply to this page.
|
''
|
Note that page names cannot start with the slash ('/') character and that each page must have a unique name.
add_pages() ¶
add_pages(
pages: t.Optional[
t.Union[t.Mapping[str, t.Union[str, Page]], str]
] = None
) -> None
Add several pages to the Graphical User Interface.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
pages |
Union[dict[str, Union[str, Page]], str]
|
The pages to add.
|
None
|
Reading pages from a directory
If pages is a string that holds the path to a readable directory, then this directory is traversed, recursively, to find files that Taipy can build pages from.
For every new directory that is traversed, a new hierarchical level for pages is created.
For every file that is found:
- If the filename extension is .md, it is read as Markdown content and a new page is created with the base name of this filename.
- If the filename extension is .html, it is read as HTML content and a new page is created with the base name of this filename.
For example, say you have the following directory structure:
reports
├── home.html
├── budget/
│ ├── expenses/
│ │ ├── marketing.md
│ │ └── production.md
│ └── revenue/
│ ├── EMAE.md
│ ├── USA.md
│ └── ASIA.md
└── cashflow/
├── weekly.md
├── monthly.md
└── yearly.md
Calling gui.add_pages('reports')
is equivalent to calling:
gui.add_pages({
"reports/home", Html("reports/home.html"),
"reports/budget/expenses/marketing", Markdown("reports/budget/expenses/marketing.md"),
"reports/budget/expenses/production", Markdown("reports/budget/expenses/production.md"),
"reports/budget/revenue/EMAE", Markdown("reports/budget/revenue/EMAE.md"),
"reports/budget/revenue/USA", Markdown("reports/budget/revenue/USA.md"),
"reports/budget/revenue/ASIA", Markdown("reports/budget/revenue/ASIA.md"),
"reports/cashflow/weekly", Markdown("reports/cashflow/weekly.md"),
"reports/cashflow/monthly", Markdown("reports/cashflow/monthly.md"),
"reports/cashflow/yearly", Markdown("reports/cashflow/yearly.md")
})
add_partial() ¶
add_partial(page: t.Union[str, Page]) -> Partial
Create a new Partial
.
The User Manual section on Partials gives details on when and how to use this class.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
page |
Union[str, Page]
|
The page to create a new Partial from.
|
required |
Returns:
Type | Description |
---|---|
Partial
|
The new |
add_shared_variable()
staticmethod
¶
add_shared_variable(*names: str) -> None
Add shared variables.
The variables will be synchronized between all clients when updated. Note that only variables from the main module will be registered.
This is a synonym for add_shared_variables()
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
names |
str
|
The names of the variables that become shared, as a list argument. |
()
|
add_shared_variables()
staticmethod
¶
add_shared_variables(*names: str) -> None
Add shared variables.
The variables will be synchronized between all clients when updated. Note that only variables from the main module will be registered.
This is a synonym for add_shared_variable()
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
names |
str
|
The names of the variables that become shared, as a list argument. |
()
|
broadcast_callback() ¶
broadcast_callback(
callback: t.Callable,
args: t.Optional[t.Sequence[t.Any]] = None,
module_context: t.Optional[str] = None,
) -> t.Dict[str, t.Any]
Invoke a callback for every client.
This callback gets invoked for every client connected to the application with the appropriate
State
instance. You can then perform client-specific tasks, such as updating the state
variable reflected in the user interface.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
callback |
Callable
|
The user-defined function to be invoked. |
required |
args |
Optional[Sequence[Any]]
|
The parameters to send to callback, if any. |
None
|
broadcast_change() ¶
broadcast_change(var_name: str, value: t.Any)
Propagates a new value for a given variable to all states.
This callback gets invoked for every client connected to the application to update the value
of the variable called var_name to the new value value, in their specific State
instance. All user interfaces reflect the change.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
var_name |
str
|
The name of the variable to change. |
required |
value |
Any
|
The new value for the variable. |
required |
broadcast_changes() ¶
broadcast_changes(
values: t.Optional[dict[str, t.Any]] = None, **kwargs
)
Propagates new values for several variables to all states.
This callback gets invoked for every client connected to the application to update the value
of all the variables that are keys in values, in their specific State
instance. All
user interfaces reflect the change.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
values |
Optional[dict[str, Any]]
|
An optional dictionary where each key is the name of a variable to change, and where the associated value is the new value to set for that variable, in each state for the application. |
None
|
**kwargs |
dict[str, any]
|
A collection of variable name-value pairs that are updated for each state of the application. Name-value pairs overload the ones in values if the name exists as a key in the dictionary. |
{}
|
get_flask_app() ¶
get_flask_app() -> Flask
Get the internal Flask application.
This method must be called after run()
was invoked.
Returns:
Type | Description |
---|---|
Flask
|
The Flask instance used. |
invoke_callback() ¶
invoke_callback(
state_id: str,
callback: t.Callable,
args: t.Optional[t.Sequence[t.Any]] = None,
module_context: t.Optional[str] = None,
) -> t.Any
Invoke a user callback for a given state.
See the section on Long Running Callbacks in a Thread in the User Manual for details on when and how this function can be used.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
state_id |
str
|
The identifier of the state to use, as returned by |
required |
callback |
Callable[[State, ...], None]
|
The user-defined function that is invoked. |
required |
args |
Optional[Sequence]
|
The remaining arguments, as a List or a Tuple. |
None
|
module_context |
Optional[str]
|
The name of the module that will be used. |
None
|
register_content_provider()
staticmethod
¶
register_content_provider(
content_type: type,
content_provider: t.Callable[..., str],
) -> None
Add a custom content provider.
The application can use custom content for the part
block when its content property
is set to an object with type type.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
content_type |
type
|
The type of the content that triggers the content provider. |
required |
content_provider |
Callable[..., str]
|
The function that converts content of type type into an HTML string. |
required |
reload() ¶
reload()
Reload the web server.
This function reloads the underlying web server only in the situation where
it was run in a separated thread: the run_in_thread parameter to the
run
method was set to True, or you are running in an IPython notebook
context.
run() ¶
run(
run_server: bool = True,
run_in_thread: bool = False,
async_mode: str = "gevent",
**kwargs
) -> t.Optional[Flask]
Start the server that delivers pages to web clients.
Once you enter run()
, users can run web browsers and point to the web server
URL that Gui
serves. The default is to listen to the localhost address
(127.0.0.1) on the port number 5000. However, the configuration of this Gui
object may impact that (see the
Configuration
section of the User Manual for details).
Parameters:
Name | Type | Description | Default |
---|---|---|---|
run_server |
bool
|
Whether or not to run a web server locally. If set to False, a web server is not created and started. |
True
|
run_in_thread |
bool
|
Whether or not to run a web server in a separated thread.
If set to True, the web server runs is a separated thread. |
False
|
async_mode |
str
|
The asynchronous model to use for the Flask-SocketIO.
Valid values are:
The default value is "gevent" |
'gevent'
|
**kwargs |
dict[str, any]
|
Additional keyword arguments that configure how this |
{}
|
Returns:
Type | Description |
---|---|
Optional[Flask]
|
The Flask instance if run_server is False else None. |
set_favicon() ¶
set_favicon(
favicon_path: t.Union[str, Path],
state: t.Optional[State] = None,
)
Change the favicon for all clients.
This function dynamically changes the favicon (the icon associated with the application's
pages) of Taipy GUI pages for a single or all connected clients.
Note that the favicon parameter to run()
can also be used to change
the favicon when the application starts.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
favicon_path |
Union[str, Path]
|
The path to the image file to use. |
required |
state |
Optional[State]
|
The state to apply the change to. |
None
|
stop() ¶
stop()
Stop the web server.
This function stops the underlying web server only in the situation where
it was run in a separated thread: the run_in_thread parameter to the
run()
method was set to True, or you are running in an IPython notebook
context.
table_on_add() ¶
table_on_add(
state: State,
var_name: str,
payload: t.Dict[str, t.Any],
new_row: t.Optional[t.List[t.Any]] = None,
)
Default implementation of the on_add
callback for tables.
This function creates a new row in the tabular dataset stored in var_name.
The row is added at the index specified in payload["index"].
Parameters:
Name | Type | Description | Default |
---|---|---|---|
state |
State
|
The state instance received from the callback. |
required |
var_name |
str
|
The name of the variable bound to the table's data property. |
required |
payload |
Dict[str, Any]
|
The payload dictionary received from the |
required |
new_row |
Optional[List[Any]]
|
The initial values for the new row. |
None
|
table_on_delete() ¶
table_on_delete(
state: State, var_name: str, payload: t.Dict[str, t.Any]
)
Default implementation of the on_delete
callback for tables.
This function removes a row from the tabular dataset stored in var_name.
The row to be removed is located at the index specified in payload["index"].
Parameters:
Name | Type | Description | Default |
---|---|---|---|
state |
State
|
The state instance received in the callback. |
required |
var_name |
str
|
The name of the variable bound to the table's data property. |
required |
payload |
Dict[str, Any]
|
The payload dictionary received from the |
required |
table_on_edit() ¶
table_on_edit(
state: State, var_name: str, payload: t.Dict[str, t.Any]
)
Default implementation of the on_edit
callback for tables.
This function sets the value of a specific cell in the tabular dataset stored in var_name, typically bound to the data property of a table control.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
state |
State
|
the state instance received in the callback. |
required |
var_name |
str
|
the name of the variable bound to the table's data property. |
required |
payload |
Dict[str, Any]
|
the payload dictionary received from the
|
required |