tutorial

Author: jamesdbrock

_sources/developer_tools.rst.txt

@@ -3,6 +3,12 @@ Developer Tools
 
 The Edifice Runner provides some useful tools for developing Edifice applications.
 
+To use the Edifice Runner, you must install the :code:`watchdog` package.
+
+.. code-block:: shell
+
+    pip install watchdog
+
 Dynamic hot-reload
 ------------------
 
@@ -77,8 +83,8 @@ To launch the Element Inspector, use the :code:`--inspect` flag for the Edifice
 
     python -m edifice --inspect path/to/your/app.py RootElement
 
-The Element Inspector, like the Inspect Elements tool of web browsers
-or the React inspector tool,
-allows you to inspect the internal state of your components.
+The Element Inspector allows you to inspect the running state of the application.
 It displays the entire Element Tree, as well as the props and state of
 every component.
+It is like the Inspect Elements tool of web browsers
+or the React inspector tool.

_sources/tutorial.rst.txt

@@ -35,7 +35,9 @@ First, install Qt and Edifice.
 
 
 Let’s create the basic skeleton of our UI.
-Copy this code into a new file, for example tutorial.py::
+Copy this code into a new file, :code:`tutorial.py`
+
+.. code-block:: python
 
     from edifice import App, Label, TextInput, HBoxView, Window, component
 
@@ -50,6 +52,12 @@ Copy this code into a new file, for example tutorial.py::
     if __name__ == "__main__":
         App(MyApp()).start()
 
+Run this code with
+
+.. code-block:: shell
+
+    python tutorial.py
+
 What does this code do?
 First we define a function :code:`MyApp` which is decorated by
 :func:`@component<component>`.
@@ -62,7 +70,7 @@ then declare its children, we use a
 `with statement <https://docs.python.org/3/reference/compound_stmts.html#with>`_
 context. Elements inside the :code:`with` context are children.
 
-In HTML or XML, we might have written it as:
+In HTML or XML or React JSX, we might have written it as:
 
 .. code-block:: xml
 
@@ -81,25 +89,13 @@ It takes the description of each Element, and it decides when and how to render
 It does so by monitoring the **state** of each Element, and it will re-render
 when the Element **state** changes.
 
-As you might expect, you can run this application with :code:`python tutorial.py`.
-However, let us take advantage of Edifice's :doc:`dynamic loading capability<developer_tools>`,
-so that we do not have to continually close the app and re-issue the command every time we change something.
-To run the app with dynamic loading, first install watchdog::
-
-    pip install watchdog
-
-then do::
-
-    python -m edifice tutorial.py MyApp
-
-You should see a basic form emerge. However, it's not pretty, and it doesn't really do anything.
-
 We can change the formatting of the :class:`Label<Label>`, :class:`TextInput<edifice.TextInput>`, and
 :class:`HBoxView<edifice.HBoxView>` using Qt :doc:`styling<styling>`,
 which is similar to CSS styling.
 Here, we want to add padding between the HBoxView and Window boundary,
 make the Labels shorter, and add a margin between the Label and TextInput.
-For example::
+
+.. code-block:: python
 
     from edifice import App, Label, TextInput, HBoxView, Window, component
 
@@ -119,14 +115,12 @@ For example::
     if __name__ == "__main__":
         App(MyApp()).start()
 
-When we are running :code:`MyApp` with dynamic loading, Edifice will detect the change
-to the source file and reload :code:`MyApp` at runtime so that we can see the styling
-changes immediately.
-
 Our application still doesn't do anything, however. Let's add an :code:`on_change`
 event handler **prop** for the :class:`TextInput<edifice.TextInput>`.
 the :code:`on_change` **prop** function will be called whenever the contents in the
-text input changes due to user action::
+text input changes due to user action.
+
+.. code-block:: python
 
     from edifice import App, Label, TextInput, HBoxView, Window, component, use_state
 
@@ -146,7 +140,7 @@ text input changes due to user action::
                 Label("Measurement in meters:", style=meters_label_style)
                 TextInput(meters, style=input_style, on_change=meters_set)
                 try:
-                    feet = "%.3f" % (float(meters) * METERS_TO_FEET)
+                    feet = f"{float(meters) * METERS_TO_FEET :.3f}"
                     Label(f"Measurement in feet: {feet}", style=feet_label_style)
                 except ValueError: # Could not convert string to float
                     pass # So don't render the Label
@@ -168,19 +162,13 @@ the :code:`on_change` **prop** for the :class:`TextInput<edifice.TextInput>`.
 Whenever the user types in the text input, the state will be set and
 the UI will re-render.
 
-Think of the component function as a map from the
+Think of the :func:`@component <component>` function as a map from the
 :code:`meters` **state** to an Element tree.
 
-In the component function, we read the value of :code:`meters` and convert it to feet,
+In the :func:`@component <component>` function, we read the value of :code:`meters`
+and convert it to feet,
 and we render the text input and label Elements.
 
-If we want to see the **state** changes in action, we can open the Element Inspector::
-
-    python -m edifice --inspect tutorial.py MyApp
-
-The Element Inspector allows us to see the current **state** and **props** for all Elements in a UI.
-Play around with the application and see how the **state** changes.
-
 Now we want to add conversion from feet to meters. Instead of copying our code and repeating
 it for each measurement pair, we can factor out the conversion logic into its own component.
 We pass the conversion parameters into the component as **props** arguments::
@@ -190,7 +178,7 @@ We pass the conversion parameters into the component as **props** arguments::
     METERS_TO_FEET = 3.28084
 
     @component
-    def ConversionWidget(self, from_unit, to_unit, factor):
+    def ConversionWidget(self, from_unit:str, to_unit:str, factor:float):
 
         current_text, current_text_set = use_state("0.0")
 
@@ -202,7 +190,7 @@ We pass the conversion parameters into the component as **props** arguments::
             Label(f"Measurement in {from_unit}:", style=from_label_style)
             TextInput(current_text, style=input_style, on_change=current_text_set)
             try:
-                to_text = "%.3f" % (float(current_text) * factor)
+                to_text = f"{float(current_text) * factor :.3f}"
                 Label(f"Measurement in {to_unit}: {to_text}", style=to_label_style)
             except ValueError: # Could not convert string to float
                 pass # So don't render the Label
@@ -216,3 +204,26 @@ We pass the conversion parameters into the component as **props** arguments::
 
     if __name__ == "__main__":
         App(MyApp()).start()
+
+
+We can use the :doc:`Edifice Runner <developer_tools>` to run our application.
+
+First install :code:`watchdog`.
+
+.. code-block:: shell
+
+    pip install watchdog
+
+Then run the application with the :doc:`Edifice Runner <developer_tools>`.
+This will run our application with **Element Inspector** and **Hot-Reload**.
+
+.. code-block:: shell
+
+    python -m edifice --inspect tutorial.py MyApp
+
+The Element Inspector allows us to see the current **state** and **props** for all Elements in a UI.
+Type in the :class:`TextInput` widget and see how the **state** changes.
+
+Editing and saving the :code:`ConversionWidget` component source code will automatically
+reload the component and update the UI. (Editing the :code:`MyApp` component will
+not reload the UI, because Hot-Reload does not work for the root component.)

developer_tools.html

@@ -385,6 +385,10 @@
   <section id="developer-tools">
 <h1>Developer Tools<a class="headerlink" href="#developer-tools" title="Link to this heading">#</a></h1>
 <p>The Edifice Runner provides some useful tools for developing Edifice applications.</p>
+<p>To use the Edifice Runner, you must install the <code class="code docutils literal notranslate"><span class="pre">watchdog</span></code> package.</p>
+<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>pip<span class="w"> </span>install<span class="w"> </span>watchdog
+</pre></div>
+</div>
 <section id="dynamic-hot-reload">
 <h2>Dynamic hot-reload<a class="headerlink" href="#dynamic-hot-reload" title="Link to this heading">#</a></h2>
 <figure class="align-default">
@@ -455,11 +459,11 @@ <h2>Element Inspector<a class="headerlink" href="#element-inspector" title="Link
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">edifice</span> <span class="o">--</span><span class="n">inspect</span> <span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">your</span><span class="o">/</span><span class="n">app</span><span class="o">.</span><span class="n">py</span> <span class="n">RootElement</span>
 </pre></div>
 </div>
-<p>The Element Inspector, like the Inspect Elements tool of web browsers
-or the React inspector tool,
-allows you to inspect the internal state of your components.
+<p>The Element Inspector allows you to inspect the running state of the application.
 It displays the entire Element Tree, as well as the props and state of
-every component.</p>
+every component.
+It is like the Inspect Elements tool of web browsers
+or the React inspector tool.</p>
 </section>
 </section>