core docs

Author: jamesdbrock

_sources/edifice.rst.txt

@@ -57,8 +57,9 @@ There is a lot of imperative and object-oriented Qt API which is meaningless
 or unnecessary in Edifice. In a normal Edifice application you will never (rarely)
 “inherit” from a class or override a “virtual” method.
 
-You never “delete” or “remove” a widget in Edifice, instead you just conditionally
-declare it. When the condition is no longer true the widget will be removed.
+You never “add” or “remove” a widget in Edifice, instead you conditionally
+render it. When the condition is no longer true the widget will be removed,
+see :ref:`Dynamic Rendering`.
 
 `QWidgets <https://doc.qt.io/qtforpython-6/api/qtwidgets/qwidget.html>`_
 are stateful objects but Edifice is designed to provide a
@@ -77,22 +78,18 @@ Reactive
 
 For handling :ref:`Events`, pass a event-handling function as a **prop**.
 
-Do not use Signal and Slots.
-The
+Never (rarely) use Signals and Slots. The
 `Signals and Slots <https://doc.qt.io/qtforpython-6/tutorials/basictutorial/signals_and_slots.html>`_
 tutorial explains that
 “Due to the nature of Qt, QObjects require a way to communicate” but
-due to the nature of Edifice, QObjects are forbidden to communicate
-because they are stateless and therefore have nothing to say.
+due to the nature of Edifice, QObjects are mostly forbidden to communicate
+because it would violate the *one-way information flow* of :ref:`Model-View-Update`.
 
 Application state is managed with :func:`use_state` Hooks.
 
 Application side-effects triggered by state changes are performed by
 :func:`use_effect` and :func:`use_async` Hooks.
 
-For more more information about Edifice reactivity see
-:ref:`Model-View-Update`.
-
 Rules of Edifice
 ----------------
 
@@ -196,7 +193,8 @@ which has child Elements representing different parts of your application.
 Dynamic Rendering
 ^^^^^^^^^^^^^^^^^
 
-For dynamism, use conditions and loops in your rendering declaration.
+For dynamism, use conditions and loops in your :func:`@component <component>`
+render function.
 The conditions and loops can depend on **props** or **state**. For example,
 this :func:`@component <component>` will render input fields only while
 the **props** indicate that they are wanted.

edifice.html

@@ -444,8 +444,9 @@ <h3>Declarative<a class="headerlink" href="#declarative" title="Link to this hea
 <p>There is a lot of imperative and object-oriented Qt API which is meaningless
 or unnecessary in Edifice. In a normal Edifice application you will never (rarely)
 “inherit” from a class or override a “virtual” method.</p>
-<p>You never “delete” or “remove” a widget in Edifice, instead you just conditionally
-declare it. When the condition is no longer true the widget will be removed.</p>
+<p>You never “add” or “remove” a widget in Edifice, instead you conditionally
+render it. When the condition is no longer true the widget will be removed,
+see <a class="reference internal" href="#dynamic-rendering"><span class="std std-ref">Dynamic Rendering</span></a>.</p>
 <p><a class="reference external" href="https://doc.qt.io/qtforpython-6/api/qtwidgets/qwidget.html">QWidgets</a>
 are stateful objects but Edifice is designed to provide a
 <em>stateless</em> API for QWidgets. Each <a class="reference internal" href="base_components.html"><span class="doc">Base Element</span></a> wraps
@@ -459,18 +460,15 @@ <h3>Declarative<a class="headerlink" href="#declarative" title="Link to this hea
 <section id="reactive">
 <h3>Reactive<a class="headerlink" href="#reactive" title="Link to this heading">#</a></h3>
 <p>For handling <a class="reference internal" href="base_components.html#events"><span class="std std-ref">Events</span></a>, pass a event-handling function as a <strong>prop</strong>.</p>
-<p>Do not use Signal and Slots.
-The
+<p>Never (rarely) use Signals and Slots. The
 <a class="reference external" href="https://doc.qt.io/qtforpython-6/tutorials/basictutorial/signals_and_slots.html">Signals and Slots</a>
 tutorial explains that
 “Due to the nature of Qt, QObjects require a way to communicate” but
-due to the nature of Edifice, QObjects are forbidden to communicate
-because they are stateless and therefore have nothing to say.</p>
+due to the nature of Edifice, QObjects are mostly forbidden to communicate
+because it would violate the <em>one-way information flow</em> of <a class="reference internal" href="#model-view-update"><span class="std std-ref">Model-View-Update</span></a>.</p>
 <p>Application state is managed with <a class="reference internal" href="stubs/edifice.use_state.html#edifice.use_state" title="edifice.use_state"><code class="xref py py-func docutils literal notranslate"><span class="pre">use_state()</span></code></a> Hooks.</p>
 <p>Application side-effects triggered by state changes are performed by
 <a class="reference internal" href="stubs/edifice.use_effect.html#edifice.use_effect" title="edifice.use_effect"><code class="xref py py-func docutils literal notranslate"><span class="pre">use_effect()</span></code></a> and <a class="reference internal" href="stubs/edifice.use_async.html#edifice.use_async" title="edifice.use_async"><code class="xref py py-func docutils literal notranslate"><span class="pre">use_async()</span></code></a> Hooks.</p>
-<p>For more more information about Edifice reactivity see
-<a class="reference internal" href="#model-view-update"><span class="std std-ref">Model-View-Update</span></a>.</p>
 </section>
 </section>
 <section id="rules-of-edifice">
@@ -556,7 +554,8 @@ <h2>Declaring Element Trees<a class="headerlink" href="#declaring-element-trees"
 which has child Elements representing different parts of your application.</p>
 <section id="dynamic-rendering">
 <h3>Dynamic Rendering<a class="headerlink" href="#dynamic-rendering" title="Link to this heading">#</a></h3>
-<p>For dynamism, use conditions and loops in your rendering declaration.
+<p>For dynamism, use conditions and loops in your <a class="reference internal" href="stubs/edifice.component.html#edifice.component" title="edifice.component"><code class="xref py py-func docutils literal notranslate"><span class="pre">&#64;component</span></code></a>
+render function.
 The conditions and loops can depend on <strong>props</strong> or <strong>state</strong>. For example,
 this <a class="reference internal" href="stubs/edifice.component.html#edifice.component" title="edifice.component"><code class="xref py py-func docutils literal notranslate"><span class="pre">&#64;component</span></code></a> will render input fields only while
 the <strong>props</strong> indicate that they are wanted.</p>