Skip to content

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:

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 Page instance that is used when there is a single page in this interface, referenced as the root page (located at /).
If page is a raw string and if it holds a path to a readable file then a Markdown page is built from the content of that file.
If page is a string that does not indicate a path to readable file then a Markdown page is built from that string.
Note that if pages is provided, those pages are added as well.

None
pages Optional[dict]

Used if you want to initialize this instance with a set of pages.
The method add_pages(pages) is called if pages is not None. You can find details on the possible values of this argument in the documentation for this method.

None
css_file Optional[str]

A pathname to a CSS file that gets used as a style sheet in all the pages.
The default value is a file that has the same base name as the Python file defining the main function, sitting next to this Python file, with the .css extension.

None
path_mapping Optional[dict]

A dictionary that associates a URL prefix to a path in the server file system.
If the assets of your application are located in /home/me/app_assets and you want to access them using only 'assets' in your application, you can set path_mapping={"assets": "/home/me/app_assets"}. If your application then requests the file "/assets/images/logo.png", the server searches for the file "/home/me/app_assets/images/logo.png".
If empty or not defined, access through the browser to all resources under the directory of the main Python file is allowed.

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.)
The default value is "taipy.gui.env"

None
libraries Optional[List[ElementLibrary]]

An optional list of extension library instances that pages can reference.
Using this argument is equivalent to calling add_library() for each list's elements.

None
flask Optional[Flask]

An optional instance of a Flask application object.
If this argument is set, this Gui instance will use the value of this argument as the underlying server. If omitted or set to None, this Gui will create its own Flask application instance and use it to serve the pages.

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]

The content of the page.
It can be an instance of Markdown or Html.
If page is a string, then:

  • If page is set to the pathname of a readable file, the page content is read as Markdown input text.
  • If it is not, the page content is read from this string as Markdown text.
required
style Optional[str]

Additional CSS style to apply to this page.

  • If there is style associated with a page, it is used at a global level
  • If there is no style associated with the page, the style is cleared at a global level
  • If the page is embedded in a block control, the style is ignored
''

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.
If pages is a dictionary, a page is added to this Gui instance for each of the entries in pages:

  • The entry key is used as the page name.
  • The entry value is used as the page content:
    • The value can can be an instance of Markdown or Html, then it is used as the page definition.
    • If entry value is a string, then:
      • If it is set to the pathname of a readable file, the page content is read as Markdown input text.
      • If it is not, the page content is read from this string as Markdown text.
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.
It can be an instance of Markdown or Html.
If page is a string, then:

  • If page is set to the pathname of a readable file, the content of the new Partial is read as Markdown input text.
  • If it is not, the content of the new Partial is read from this string as Markdown text.
required

Returns:

Type Description
Partial

The new Partial object defined by page.

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.
The first parameter of this function must be a State object representing the client for which it is invoked.
The other parameters should reflect the ones provided in the args collection.

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 get_state_id().

required
callback Callable[[State, ...], None]

The user-defined function that is invoked.
The first parameter of this function must be a State.

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.
Note that if you are running in an IPython notebook context, the web server always runs in a separate thread.

False
async_mode str

The asynchronous model to use for the Flask-SocketIO. Valid values are:

  • "gevent": Use a gevent server.
  • "threading": Use the Flask Development Server. This allows the application to use the Flask reloader (the use_reloader option) and Debug mode (the debug option).
  • "eventlet": Use an eventlet event-driven WSGI server.

The default value is "gevent"
Note that only the "threading" value provides support for the development reloader functionality (use_reloader option). Any other value makes the use_reloader configuration parameter ignored.
Also note that setting the debug argument to True forces async_mode to "threading".

'gevent'
**kwargs dict[str, any]

Additional keyword arguments that configure how this Gui is run. Please refer to the gui config section page of the User Manual for more information.

{}

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.
This can be expressed as a path name or a URL (relative or not).

required
state Optional[State]

The state to apply the change to.
If no set or set to None, all the application's clients are impacted.

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 on_add callback.

required
new_row Optional[List[Any]]

The initial values for the new row.
If this parameter is not specified, the new row is initialized with all values set to 0, with the exact meaning depending on the column data type.

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 on_delete callback.

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 on_edit callback.
This dictionary has the following keys:

  • "index": The row index of the cell to be modified.
  • "col": Specifies the name of the column of the cell to be modified.
  • "value": Specifies the new value to be assigned to the cell.
  • "user_value": Contains the text entered by the user.
  • "tz": Specifies the timezone to be used, if applicable.
required