Add pane code samples (#1759)

- Minor doc errors here and there

doc/gui/examples/blocks/pane-anchor.py

@@ -0,0 +1,31 @@
+# Copyright 2021-2024 Avaiga Private Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations under the License.
+# -----------------------------------------------------------------------------------------
+# To execute this script, make sure that the taipy-gui package is installed in your
+# Python environment and run:
+#     python <script>
+# -----------------------------------------------------------------------------------------
+from taipy.gui import Gui
+
+show_pane = True
+
+page = """
+<|{show_pane}|pane|anchor=top|height=50px|
+Here is some text that is displayed at the top of the page in a pane.
+|>
+
+# Main page content
+
+This is the content of the page.
+"""
+
+if __name__ == "__main__":
+    Gui(page).run()

doc/gui/examples/blocks/pane-as-page.py

@@ -0,0 +1,59 @@
+# Copyright 2021-2024 Avaiga Private Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations under the License.
+# -----------------------------------------------------------------------------------------
+# To execute this script, make sure that the taipy-gui package is installed in your
+# Python environment and run:
+#     python <script>
+# -----------------------------------------------------------------------------------------
+from taipy.gui import Gui
+
+# Initially invested amount
+initial_investment = 100
+# Interest rate by period
+rate = 5
+# Number of periods
+periods = 0
+# Number of periods
+final_amount = initial_investment
+# Is the interest rate setting panel shown
+show_rate = False
+
+pane_page = """
+Rate (in %):
+<|{rate}|number|>
+"""
+
+page = """
+# Interest Calculator
+
+<|{show_rate}|pane|show_button|page=_rate_pane|>
+
+Initial amount: <|{initial_investment}|number|>
+
+Periods: <|{periods}|number|min=0|max=50|>
+
+Final amount: <|{final_amount}|format=%.2f|>
+"""
+
+
+# Invoked when any control value is changed.
+def on_change(state, var_name: str):
+    # Cumulated interest percentage
+    progress = pow(1 + state.rate / 100, state.periods)
+    state.final_amount = state.initial_investment * progress
+
+
+if __name__ == "__main__":
+    pages = {
+        "main": page,
+        "_rate_pane": pane_page,
+    }
+    Gui(pages=pages).run()

doc/gui/examples/blocks/pane-simple-lambda.py

@@ -0,0 +1,33 @@
+# Copyright 2021-2024 Avaiga Private Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations under the License.
+# -----------------------------------------------------------------------------------------
+# To execute this script, make sure that the taipy-gui package is installed in your
+# Python environment and run:
+#     python <script>
+# -----------------------------------------------------------------------------------------
+from taipy.gui import Gui
+
+show_pane = False
+
+page = """
+# The **pane** block
+
+<|{show_pane}|pane|
+Here is the content of the pane.
+|>
+
+This is the content of the page.
+
+<|Show pane|button|on_action={lambda s: s.assign("show_pane", True)}|>
+"""
+
+if __name__ == "__main__":
+    Gui(page).run()

doc/gui/examples/blocks/pane-simple.py

@@ -0,0 +1,39 @@
+# Copyright 2021-2024 Avaiga Private Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations under the License.
+# -----------------------------------------------------------------------------------------
+# To execute this script, make sure that the taipy-gui package is installed in your
+# Python environment and run:
+#     python <script>
+# -----------------------------------------------------------------------------------------
+from taipy.gui import Gui
+
+show_pane = False
+
+
+# When the button is pressed, set the variable controlling the pane visibility to True
+def on_action(state):
+    state.show_pane = True
+
+
+page = """
+# The **pane** block
+
+<|{show_pane}|pane|
+Here is the content of the pane.
+|>
+
+This is the content of the page.
+
+<|Show pane|button|>
+"""
+
+if __name__ == "__main__":
+    Gui(page).run()

taipy/gui/builder/_element.py

@@ -284,14 +284,11 @@ class content(_Control):
     """
     Create a `content` pseudo-element
 
-    Arguments:
-            None
+    This pseudo-element can be used in the root page of your application. It is replaced at runtime
+    by the content of the page the user navigates to.
 
-        Examples:
-            - To generate `content`, use:
-               ```
-               content()
-               ```
+    The usage of this pseudo-element is described in
+    [this page](../../userman/gui/pages/index.md#application-header-and-footer).
     """
 
     def _render(self, gui: "Gui") -> str:

taipy/gui/gui_actions.py

@@ -299,8 +299,8 @@ def broadcast_callback(
 ) -> t.Dict[str, t.Any]:
     """Invoke a callback for every client.
 
-    Calling this function is equivalent to calling
-    *gui*.[Gui.]broadcast_callback(callback, args, module_context)^`.
+    Calling this function is equivalent to calling the method
+    *gui*.`(Gui.)broadcast_callback(callback, args)^`.
 
     Arguments:
         gui (Gui^): The current Gui instance.

taipy/gui/viselements.json

@@ -23,7 +23,7 @@
                     {
                         "name": "mode",
                         "type": "str",
-                        "doc": "Define the way the text is processed:\n<ul><li>&quot;raw&quot;: synonym for setting the *raw* property to True</li><li>&quot;pre&quot;: keeps spaces and new lines</li><li>&quot;markdown&quot; or &quot;md&quot;: basic support for Markdown."
+                        "doc": "Define the way the text is processed:\n<ul><li>&quot;raw&quot;: synonym for setting the <i>raw</i> property to True</li><li>&quot;pre&quot;: keeps spaces and new lines</li><li>&quot;markdown&quot; or &quot;md&quot;: basic support for Markdown."
                     },
                     {
                         "name": "format",
@@ -126,7 +126,7 @@
                         "name": "type",
                         "type": "str",
                         "default_value": "\"text\"",
-                        "doc": "TODO: The type of input: text, tel, email ... as defined in HTML standards https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#input_types "
+                        "doc": "The type of generated input HTML element, as defined in [HTML input types](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#input_types).<br/>This value forces certain values to be entered and can be set to \"text\", \"tel\", \"url\", \"url\"..., among other choices."
                     }
                 ]
             }
@@ -284,7 +284,7 @@
                     {
                         "name": "mode",
                         "type": "str",
-                        "doc": "Define the way the toggle is displayed:\n<ul><li>&quot;theme&quot;: synonym for setting the *theme* property to True</li></ul>"
+                        "doc": "Define the way the toggle is displayed:\n<ul><li>&quot;theme&quot;: synonym for setting the <i>theme</i> property to True</li></ul>"
                     },
                     {
                         "name": "label",
@@ -673,7 +673,7 @@
                     {
                         "name": "figure",
                         "type": "dynamic(plotly.graph_objects.Figure)",
-                        "doc": "A figure as produced by plotly."
+                        "doc": "A figure as produced by Plotly."
                     },
                     {
                         "name": "on_click",
@@ -909,7 +909,7 @@
                     {
                         "name": "on_action",
                         "type": "Callable",
-                        "doc": "The name of a function that is triggered when the user selects a row.<br/>All parameters of that function are optional:\n<ul>\n<li>state (<code>State^</code>): the state instance.</li>\n<li>var_name (str): the name of the tabular data variable.</li>\n<li>payload (dict): the details on this callback's invocation.<br/>This dictionary has the following keys:\n<ul>\n<li>action: the name of the action that triggered this callback.</li>\n<li>index (int): the row index.</li>\n<li>col (str): the column name.</li>\n<li>reason (str): the origin of the action: \"click\", or \"button\" if the cell contains a Markdown link syntax.</li>\n<li>value (str): the *link value* indicated in the cell when using a Markdown link syntax (that is, <i>reason</i> is set to \"button\").</li></ul></li></ul>.",
+                        "doc": "The name of a function that is triggered when the user selects a row.<br/>All parameters of that function are optional:\n<ul>\n<li>state (<code>State^</code>): the state instance.</li>\n<li>var_name (str): the name of the tabular data variable.</li>\n<li>payload (dict): the details on this callback's invocation.<br/>This dictionary has the following keys:\n<ul>\n<li>action: the name of the action that triggered this callback.</li>\n<li>index (int): the row index.</li>\n<li>col (str): the column name.</li>\n<li>reason (str): the origin of the action: \"click\", or \"button\" if the cell contains a Markdown link syntax.</li>\n<li>value (str): the <i>link value</i> indicated in the cell when using a Markdown link syntax (that is, <i>reason</i> is set to \"button\").</li></ul></li></ul>.",
                         "signature": [
                             [
                                 "state",
@@ -1504,7 +1504,7 @@
                         "name": "lov",
                         "default_property": true,
                         "type": "dict[str, Any]",
-                        "doc": "The list of pages. The keys should be:\n<ul>\n<li>page id (start with \"/\")</li>\n<li>or full URL</li>\n</ul>\nThe values are labels. See the <a href=\"../../../../userman/gui/binding/#list-of-values\">section on List of Values</a> for details."
+                        "doc": "The list of pages. The keys should be:\n<ul>\n<li>page id (start with \"/\")</li>\n<li>or full URL</li>\n</ul>\nThe values are labels. See the <a href=\"../../../../../userman/gui/binding/#list-of-values\">section on List of Values</a> for details."
                     }
                 ]
             }
@@ -1590,7 +1590,7 @@
                     {
                         "name": "users",
                         "type": "dynamic(list[Union[str,Icon]])",
-                        "doc": "The list of users. See the <a href=\"../../../../userman/gui/binding/#list-of-values\">section on List of Values</a> for details."
+                        "doc": "The list of users. See the <a href=\"../../../../../userman/gui/binding/#list-of-values\">section on List of Values</a> for details."
                     },
                     {
                         "name": "sender_id",
@@ -1811,7 +1811,7 @@
                         "default_property": true,
                         "type": "str",
                         "default_value": "\"1 1\"",
-                        "doc": "The list of weights for each column.<br/>For example, `\"1 2\"` creates a 2 column grid:\n<ul>\n<li>1fr</li>\n<li>2fr</li>\n</ul><br/>The creation of multiple same size columns can be simplified by using the multiply sign eg. \"5*1\" is equivalent to \"1 1 1 1 1\"."
+                        "doc": "The list of weights for each column.<br/>For example, \"1 2\" creates a 2 column grid:\n<ul>\n<li>1fr</li>\n<li>2fr</li>\n</ul><br/>The creation of multiple same size columns can be simplified by using the multiply sign eg. \"5*1\" is equivalent to \"1 1 1 1 1\"."
                     },
                     {
                         "name": "columns[mobile]",
@@ -1866,6 +1866,12 @@
                         "default_value": "\"left\"",
                         "doc": "Anchor side of the pane.<br/>Valid values are \"left\", \"right\", \"top\", or \"bottom\"."
                     },
+                    {
+                        "name": "persistent",
+                        "type": "bool",
+                        "default_value": "False",
+                        "doc": "If False, the pane covers the page where it appeared and disappears if the user clicks in the page.<br/>If True, the pane appears next to the page. Note that the parent section of the pane must have the <i>flex</i> display mode set. See below for an example using the <code>persistent</code> property."
+                    },
                     {
                         "name": "width",
                         "type": "str",
@@ -1878,12 +1884,6 @@
                         "default_value": "\"30vh\"",
                         "doc": "Height, in CSS units, of this pane.<br/>This is used only if <i>anchor</i> is \"top\" or \"bottom\"."
                     },
-                    {
-                        "name": "persistent",
-                        "type": "bool",
-                        "default_value": "False",
-                        "doc": "If False, the pane covers the page where it appeared and disappears if the user clicks in the page.<br/>If True, the pane appears next to the page. Note that the parent section of the pane must have the <i>flex</i> display mode set. See below for an example using the <code>persistent</code> property."
-                    },
                     {
                         "name": "show_button",
                         "type": "bool",
@@ -1924,12 +1924,12 @@
                     {
                         "name": "lov",
                         "type": "dict[str, Any]",
-                        "doc": "The list of values. See the <a href=\"../../../../userman/gui/binding/#list-of-values\">section on List of Values</a> for details."
+                        "doc": "The list of values. See the <a href=\"../../../../../userman/gui/binding/#list-of-values\">section on List of Values</a> for details."
                     },
                     {
                         "name": "adapter",
                         "type": "Function",
-                        "default_value": "`lambda x: str(x)`",
+                        "default_value": "`\"lambda x: str(x)\"`",
                         "doc": "The function that transforms an element of <i>lov</i> into a <i>tuple(id:str, label:Union[str,Icon])</i>."
                     },
                     {
@@ -1977,15 +1977,15 @@
             "partial",
             {
                 "properties": [
-                    {
-                        "name": "partial",
-                        "type": "taipy.gui.Partial",
-                        "doc": "A Partial object that holds the content of the block.<br/>This should not be defined if <i>page</i> is set."
-                    },
                     {
                         "name": "page",
                         "type": "str",
                         "doc": "The page name to show as the content of the block.<br/>This should not be defined if <i>partial</i> is set."
+                    },
+                    {
+                        "name": "partial",
+                        "type": "taipy.gui.Partial",
+                        "doc": "A Partial object that holds the content of the block.<br/>This should not be defined if <i>page</i> is set."
                     }
                 ]
             }
@@ -2068,7 +2068,7 @@
                     {
                         "name": "class_name",
                         "type": "dynamic(str)",
-                        "doc": "The list of CSS class names that are associated with the generated HTML Element.<br/>These class names are added to the default <code>taipy-&lt;element_type&gt;</code> class name."
+                        "doc": "The list of CSS class names that are associated with the generated HTML Element.<br/>These class names are added to the default <code>taipy-[element_type]</code> class name."
                     },
                     {
                         "name": "hover_text",

taipy/gui_core/__init__.py

@@ -9,5 +9,10 @@
 # an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
 # specific language governing permissions and limitations under the License.
 
+"""# Taipy GUI for Scenario Management
+
+This package provides classes that can be used in GUI controls dedicated to scenario management.
+"""
+
 from ._adapters import CustomScenarioFilter, DataNodeFilter, DataNodeScenarioFilter, ScenarioFilter
 from ._init import *

tools/gui/generate_pyi.py

@@ -148,12 +148,20 @@ def build_doc(name: str, desc: Dict[str, Any]):
     if "doc" not in desc:
         return ""
     doc = str(desc["doc"])
+    # Hack to replace the actual element name in the class_name property doc
     if desc["name"] == "class_name":
-        doc = doc.replace("<element_type>", name)
+        doc = doc.replace("[element_type]", name)
     # This won't work for Scenario Management and Block elements
     doc = re.sub(r"(href=\")\.\.((?:.*?)\")", r"\1" + taipy_doc_url + name + r"/../..\2", doc)
+    doc = re.sub(r"<tt>([\w_]+)</tt>", r"`\1`", doc) # <tt> not processed properly by markdownify()
     doc = "\n  ".join(markdownify(doc).split("\n"))
-    doc = doc.replace("  \n", "  \\n")
+    # <, >, `, [, -, _ and * prefixed with a \
+    doc = doc.replace("  \n", "  \\n").replace("\\<", "<").replace("\\>", ">").replace("\\`", "`")
+    doc = doc.replace("\\[", "[").replace("\\-", "-").replace("\\_", "_").replace("\\*", "*")
+    # Final dots are prefixed with a \
+    doc = re.sub(r"\\.$", ".", doc)
+    # Link anchors # signs are prefixed with a \
+    doc = re.sub(r"\\(#[a-z_]+\))", r"\1", doc)
     doc = re.sub(r"(?:\s+\\n)?\s+See below(?:[^\.]*)?\.", "", doc).replace("\n", "\\n")
     return f"{desc['name']}{desc['dynamic']}{desc['indexed']}\\n  {doc}\\n\\n"