Skip to content

Commit 3a817f3

Browse files
owenthcareyowenthcarey
committed
deploy: 7a3a695 
1 parent 2eee938 commit 3a817f3

File tree

6 files changed

+164
-15
lines changed

6 files changed

+164
-15
lines changed

‎api/pythonnative/index.html‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -799,6 +799,8 @@ <h1 id="pythonnative-package">pythonnative package<a class="headerlink" href="#p
799799
<li><code>pythonnative.utils.IS_ANDROID</code>: platform flag with robust detection for Chaquopy/Android.</li>
800800
<li><code>pythonnative.utils.get_android_context()</code>: returns the current Android Activity/Context when running on Android.</li>
801801
<li><code>pythonnative.utils.set_android_context(ctx)</code>: set by <code>pythonnative.Page</code> on Android; you generally don’t call this directly.</li>
802+
<li><code>pythonnative.utils.get_android_fragment_container()</code>: returns the current Fragment container <code>ViewGroup</code> used for page rendering.</li>
803+
<li><code>pythonnative.utils.set_android_fragment_container(viewGroup)</code>: set by the host <code>PageFragment</code>; you generally don’t call this directly.</li>
802804
</ul>
803805

804806

‎concepts/architecture/index.html‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -407,6 +407,15 @@
407407
</span>
408408
</a>
409409

410+
</li>
411+
412+
<li class="md-nav__item">
413+
<a href="#navigation-model-overview" class="md-nav__link">
414+
<span class="md-ellipsis">
415+
Navigation model overview
416+
</span>
417+
</a>
418+
410419
</li>
411420

412421
<li class="md-nav__item">
@@ -910,6 +919,15 @@
910919
</span>
911920
</a>
912921

922+
</li>
923+
924+
<li class="md-nav__item">
925+
<a href="#navigation-model-overview" class="md-nav__link">
926+
<span class="md-ellipsis">
927+
Navigation model overview
928+
</span>
929+
</a>
930+
913931
</li>
914932

915933
<li class="md-nav__item">
@@ -988,6 +1006,12 @@ <h2 id="key-implications">Key implications<a class="headerlink" href="#key-impli
9881006
<li>Lifecycle rules remain native: Activities/ViewControllers are created by the OS. Python receives and controls them; it does not instantiate Android Activities directly.</li>
9891007
<li>Small, growing surface: the shared Python API favors clarity and consistency, expanding progressively.</li>
9901008
</ul>
1009+
<h2 id="navigation-model-overview">Navigation model overview<a class="headerlink" href="#navigation-model-overview" title="Permanent link">&para;</a></h2>
1010+
<ul>
1011+
<li>See the Navigation guide for full details and comparisons with other frameworks.</li>
1012+
<li>iOS: one host <code>UIViewController</code> class, many instances pushed on a <code>UINavigationController</code>.</li>
1013+
<li>Android: single host <code>Activity</code> with a <code>NavHostFragment</code> and a stack of generic <code>PageFragment</code>s driven by a navigation graph.</li>
1014+
</ul>
9911015
<h2 id="related-docs">Related docs<a class="headerlink" href="#related-docs" title="Permanent link">&para;</a></h2>
9921016
<ul>
9931017
<li>Guides / Android: guides/android.md</li>

‎guides/navigation/index.html‎

Lines changed: 125 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -627,6 +627,48 @@
627627
</span>
628628
</a>
629629

630+
</li>
631+
632+
<li class="md-nav__item">
633+
<a href="#platform-specifics" class="md-nav__link">
634+
<span class="md-ellipsis">
635+
Platform specifics
636+
</span>
637+
</a>
638+
639+
<nav class="md-nav" aria-label="Platform specifics">
640+
<ul class="md-nav__list">
641+
642+
<li class="md-nav__item">
643+
<a href="#ios-uiviewcontroller-per-page" class="md-nav__link">
644+
<span class="md-ellipsis">
645+
iOS (UIViewController per page)
646+
</span>
647+
</a>
648+
649+
</li>
650+
651+
<li class="md-nav__item">
652+
<a href="#android-single-activity-fragment-stack" class="md-nav__link">
653+
<span class="md-ellipsis">
654+
Android (single Activity, Fragment stack)
655+
</span>
656+
</a>
657+
658+
</li>
659+
660+
</ul>
661+
</nav>
662+
663+
</li>
664+
665+
<li class="md-nav__item">
666+
<a href="#comparison-to-other-frameworks" class="md-nav__link">
667+
<span class="md-ellipsis">
668+
Comparison to other frameworks
669+
</span>
670+
</a>
671+
630672
</li>
631673

632674
</ul>
@@ -865,6 +907,48 @@
865907
</span>
866908
</a>
867909

910+
</li>
911+
912+
<li class="md-nav__item">
913+
<a href="#platform-specifics" class="md-nav__link">
914+
<span class="md-ellipsis">
915+
Platform specifics
916+
</span>
917+
</a>
918+
919+
<nav class="md-nav" aria-label="Platform specifics">
920+
<ul class="md-nav__list">
921+
922+
<li class="md-nav__item">
923+
<a href="#ios-uiviewcontroller-per-page" class="md-nav__link">
924+
<span class="md-ellipsis">
925+
iOS (UIViewController per page)
926+
</span>
927+
</a>
928+
929+
</li>
930+
931+
<li class="md-nav__item">
932+
<a href="#android-single-activity-fragment-stack" class="md-nav__link">
933+
<span class="md-ellipsis">
934+
Android (single Activity, Fragment stack)
935+
</span>
936+
</a>
937+
938+
</li>
939+
940+
</ul>
941+
</nav>
942+
943+
</li>
944+
945+
<li class="md-nav__item">
946+
<a href="#comparison-to-other-frameworks" class="md-nav__link">
947+
<span class="md-ellipsis">
948+
Comparison to other frameworks
949+
</span>
950+
</a>
951+
868952
</li>
869953

870954
</ul>
@@ -927,12 +1011,51 @@ <h2 id="lifecycle">Lifecycle<a class="headerlink" href="#lifecycle" title="Perma
9271011
<li><code>on_save_instance_state</code></li>
9281012
<li><code>on_restore_instance_state</code></li>
9291013
</ul>
930-
<p>Android forwards Activity lifecycle via the template <code>MainActivity</code> and <code>PageActivity</code>. iOS forwards <code>viewWillAppear</code>/<code>viewWillDisappear</code> via an internal registry.</p>
1014+
<p>Android uses a single <code>MainActivity</code> hosting a <code>NavHostFragment</code> and a generic <code>PageFragment</code> per page. iOS forwards <code>viewWillAppear</code>/<code>viewWillDisappear</code> via an internal registry.</p>
9311015
<h2 id="notes">Notes<a class="headerlink" href="#notes" title="Permanent link">&para;</a></h2>
9321016
<ul>
933-
<li>On Android, <code>push</code> launches a template <code>PageActivity</code> and passes <code>PY_PAGE_PATH</code> and optional JSON args.</li>
1017+
<li>On Android, <code>push</code> navigates via <code>NavController</code> to a <code>PageFragment</code> and passes <code>page_path</code> and optional JSON <code>args</code>.</li>
9341018
<li>On iOS, <code>push</code> uses the root <code>UINavigationController</code> to push a new <code>ViewController</code> and passes page info via KVC.</li>
9351019
</ul>
1020+
<h2 id="platform-specifics">Platform specifics<a class="headerlink" href="#platform-specifics" title="Permanent link">&para;</a></h2>
1021+
<h3 id="ios-uiviewcontroller-per-page">iOS (UIViewController per page)<a class="headerlink" href="#ios-uiviewcontroller-per-page" title="Permanent link">&para;</a></h3>
1022+
<ul>
1023+
<li>Each PythonNative page is hosted by a Swift <code>ViewController</code> instance.</li>
1024+
<li>Pages are pushed and popped on a root <code>UINavigationController</code>.</li>
1025+
<li>Lifecycle is forwarded from Swift to the registered Python page instance.</li>
1026+
<li>Root view wiring: <code>Page.set_root_view</code> sizes and inserts the Python-native view into the controller’s view.</li>
1027+
</ul>
1028+
<p>Why this matches iOS conventions
1029+
- iOS apps commonly model screens as <code>UIViewController</code>s and use <code>UINavigationController</code> for hierarchical navigation.
1030+
- The approach integrates cleanly with add-to-app and system behaviors (e.g., state restoration).</p>
1031+
<h3 id="android-single-activity-fragment-stack">Android (single Activity, Fragment stack)<a class="headerlink" href="#android-single-activity-fragment-stack" title="Permanent link">&para;</a></h3>
1032+
<ul>
1033+
<li>Single host <code>MainActivity</code> sets a <code>NavHostFragment</code> containing a navigation graph.</li>
1034+
<li>Each PythonNative page is represented by a generic <code>PageFragment</code> which instantiates the Python page and attaches its root view.</li>
1035+
<li><code>push</code>/<code>pop</code> delegate to <code>NavController</code> (via a small <code>Navigator</code> helper).</li>
1036+
<li>Arguments (<code>page_path</code>, <code>args_json</code>) live in Fragment arguments and restore across configuration changes and process death.</li>
1037+
</ul>
1038+
<p>Why this matches Android conventions
1039+
- Modern Android apps favor one Activity with many Fragments, using Jetpack Navigation for back stack, transitions, and deep links.
1040+
- It simplifies lifecycle, back handling, and state compared to one-Activity-per-screen.</p>
1041+
<h2 id="comparison-to-other-frameworks">Comparison to other frameworks<a class="headerlink" href="#comparison-to-other-frameworks" title="Permanent link">&para;</a></h2>
1042+
<ul>
1043+
<li>React Native</li>
1044+
<li>Android: single <code>Activity</code>, screens managed via <code>Fragment</code>s (e.g., <code>react-native-screens</code>).</li>
1045+
<li>iOS: screens map to <code>UIViewController</code>s pushed on <code>UINavigationController</code>.</li>
1046+
<li>.NET MAUI / Xamarin.Forms</li>
1047+
<li>Android: single <code>Activity</code>, pages via Fragments/Navigation.</li>
1048+
<li>iOS: pages map to <code>UIViewController</code>s on a <code>UINavigationController</code>.</li>
1049+
<li>NativeScript</li>
1050+
<li>Android: single <code>Activity</code>, pages as <code>Fragment</code>s.</li>
1051+
<li>iOS: pages as <code>UIViewController</code>s on <code>UINavigationController</code>.</li>
1052+
<li>Flutter (special case)</li>
1053+
<li>Android: single <code>Activity</code> (<code>FlutterActivity</code>/<code>FlutterFragmentActivity</code>).</li>
1054+
<li>iOS: <code>FlutterViewController</code> hosts Flutter’s internal navigator; add-to-app can push multiple <code>FlutterViewController</code>s.</li>
1055+
</ul>
1056+
<p>Bottom line
1057+
- iOS: one host VC class, many instances on a <code>UINavigationController</code>.
1058+
- Android: one host <code>Activity</code>, many <code>Fragment</code>s with Jetpack Navigation.</p>
9361059

9371060

9381061

‎search/search_index.json‎

Lines changed: 1 addition & 1 deletion
Large diffs are not rendered by default.

‎sitemap.xml‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -2,50 +2,50 @@
22
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
33
<url>
44
<loc>https://docs.pythonnative.com/</loc>
5-
<lastmod>2025-10-17</lastmod>
5+
<lastmod>2025-10-18</lastmod>
66
</url>
77
<url>
88
<loc>https://docs.pythonnative.com/examples/</loc>
9-
<lastmod>2025-10-17</lastmod>
9+
<lastmod>2025-10-18</lastmod>
1010
</url>
1111
<url>
1212
<loc>https://docs.pythonnative.com/getting-started/</loc>
13-
<lastmod>2025-10-17</lastmod>
13+
<lastmod>2025-10-18</lastmod>
1414
</url>
1515
<url>
1616
<loc>https://docs.pythonnative.com/api/pythonnative/</loc>
17-
<lastmod>2025-10-17</lastmod>
17+
<lastmod>2025-10-18</lastmod>
1818
</url>
1919
<url>
2020
<loc>https://docs.pythonnative.com/concepts/architecture/</loc>
21-
<lastmod>2025-10-17</lastmod>
21+
<lastmod>2025-10-18</lastmod>
2222
</url>
2323
<url>
2424
<loc>https://docs.pythonnative.com/concepts/components/</loc>
25-
<lastmod>2025-10-17</lastmod>
25+
<lastmod>2025-10-18</lastmod>
2626
</url>
2727
<url>
2828
<loc>https://docs.pythonnative.com/examples/hello-world/</loc>
29-
<lastmod>2025-10-17</lastmod>
29+
<lastmod>2025-10-18</lastmod>
3030
</url>
3131
<url>
3232
<loc>https://docs.pythonnative.com/guides/android/</loc>
33-
<lastmod>2025-10-17</lastmod>
33+
<lastmod>2025-10-18</lastmod>
3434
</url>
3535
<url>
3636
<loc>https://docs.pythonnative.com/guides/ios/</loc>
37-
<lastmod>2025-10-17</lastmod>
37+
<lastmod>2025-10-18</lastmod>
3838
</url>
3939
<url>
4040
<loc>https://docs.pythonnative.com/guides/navigation/</loc>
41-
<lastmod>2025-10-17</lastmod>
41+
<lastmod>2025-10-18</lastmod>
4242
</url>
4343
<url>
4444
<loc>https://docs.pythonnative.com/meta/contributing/</loc>
45-
<lastmod>2025-10-17</lastmod>
45+
<lastmod>2025-10-18</lastmod>
4646
</url>
4747
<url>
4848
<loc>https://docs.pythonnative.com/meta/roadmap/</loc>
49-
<lastmod>2025-10-17</lastmod>
49+
<lastmod>2025-10-18</lastmod>
5050
</url>
5151
</urlset>

‎sitemap.xml.gz‎

-1 Bytes
Binary file not shown.

0 commit comments

Comments
 (0)