diff --git a/changes/2381.docs.rst b/changes/2381.doc.rst similarity index 100% rename from changes/2381.docs.rst rename to changes/2381.doc.rst diff --git a/changes/2463.doc.rst b/changes/2463.doc.rst new file mode 100644 index 0000000000..f87f55f9a4 --- /dev/null +++ b/changes/2463.doc.rst @@ -0,0 +1 @@ +The documentation landing page and some documentation sections were reorganized. diff --git a/docs/_static/custom.css b/docs/_static/custom.css index 02b3970e25..977724746d 100644 --- a/docs/_static/custom.css +++ b/docs/_static/custom.css @@ -1,3 +1,14 @@ +div.table { + clear: both; + display: flex; + flex-wrap: wrap; + column-gap: 2rem; +} + +div.table > * { + width: 20rem; +} + /* Draw lines around table edges. */ table.docutils { border: 1px solid var(--color-background-border); diff --git a/docs/background/community.rst b/docs/background/community.rst new file mode 100644 index 0000000000..90df9ca93b --- /dev/null +++ b/docs/background/community.rst @@ -0,0 +1,18 @@ +========= +Community +========= + +Toga is part of the `BeeWare suite`_. You can talk to the community through: + +* `@beeware@fosstodon.org on Mastodon`_ +* `Discord`_ +* The Toga `GitHub Discussions forum`_ + +We foster a welcoming and respectful community as described in our +`BeeWare Community Code of Conduct`_. + +.. _BeeWare suite: https://beeware.org/ +.. _@beeware@fosstodon.org on Mastodon: https://fosstodon.org/@beeware +.. _Discord: https://beeware.org/bee/chat/ +.. _GitHub Discussions forum: https://github.com/beeware/toga/discussions +.. _BeeWare Community Code of Conduct: https://beeware.org/community/behavior/ diff --git a/docs/background/index.rst b/docs/background/index.rst index 1d4448a4d5..2207e6f43a 100644 --- a/docs/background/index.rst +++ b/docs/background/index.rst @@ -8,5 +8,5 @@ Background :maxdepth: 2 project/index - topics/index + community internals/index diff --git a/docs/background/project/faq.rst b/docs/background/project/faq.rst index 00db652d61..154340cc87 100644 --- a/docs/background/project/faq.rst +++ b/docs/background/project/faq.rst @@ -1,8 +1,8 @@ .. _togas-and-yaks: -======================== -Why "Toga"? Why the Yak? -======================== +=== +FAQ +=== So... why the name Toga? ======================== diff --git a/docs/background/project/index.rst b/docs/background/project/index.rst index 1b377dd2a2..5673ce5bec 100644 --- a/docs/background/project/index.rst +++ b/docs/background/project/index.rst @@ -1,12 +1,12 @@ -================= -About the project -================= +========== +About Toga +========== .. toctree:: :maxdepth: 1 - philosophy - faq + Project philosophy + FAQ success releases roadmap diff --git a/docs/background/project/roadmap.rst b/docs/background/project/roadmap.rst index b4f02bc7ea..9612987a99 100644 --- a/docs/background/project/roadmap.rst +++ b/docs/background/project/roadmap.rst @@ -1,6 +1,6 @@ -======== -Road Map -======== +=============== +Toga's Road Map +=============== Toga is a new project - we have lots of things that we'd like to do. If you'd like to contribute, you can provide a patch for one of these features. @@ -20,37 +20,67 @@ Input Inputs are mechanisms for displaying and editing input provided by the user. -* ``ComboBox`` - A free entry text field that provides options (e.g., text with past choices) +Partially implemented widgets +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* ``Table`` + + Mobile platforms don't provide a native "Table" widget; however, table-like + data could be rendered by using a :class:`~toga.DetailedList`, where the + title and subtitle are the "important" columns selected by the user, and + selecting a row on the table navigates to a sub-page showing the full row + detail. - - Cocoa: ``NSComboBox`` - - GTK: ``Gtk.ComboBox.new_with_model_and_entry`` - - iOS: ? - - Winforms: ``ComboBox`` - - Android: ``Spinner`` +* ``Tree`` + + As with Table, mobile platforms don't provide a native "Tree" widget; however, + we could use a similar approach to Table. + + On Windows, the native widget doesn't provide support for more than one column. This + means we either need to make a special case on Windows for a "simple" tree; or we need + to form a composite widget that pairs the scrolling of a table with a tree. * ``DateTimeInput`` - A widget for selecting a date and a time. - - Cocoa: ``NSDatePicker`` - - GTK: `Gtk.Calendar` + ? - - iOS: ``UIDatePicker`` - - Winforms: ``DateTimePicker`` - - Android: ? + - Cocoa: ``NSDatePicker`` + - GTK: ``Gtk.Calendar`` + ? + - iOS: ``UIDatePicker`` + +New widgets +^^^^^^^^^^^ + +* ``RadioButton`` - a set of mutually exclusive options. + + Functionally, the use case of "select one from a list of options" can be met with a + :class:`~toga.Selection`; however, from a UI design perspective, a radio button is a + common design pattern. + + See `this issue `__ for discussion of how + this widget may be implemented in a way that compliments existing widgets. + +* ``ComboBox`` - A free entry text field that provides options (e.g., text with past choices) + + - Cocoa: ``NSComboBox`` + - GTK: ``Gtk.ComboBox.new_with_model_and_entry`` + - iOS: ? + - Winforms: ``ComboBox`` + - Android: ``Spinner`` * ``ColorInput`` - A widget for selecting a color - - Cocoa: ``NSColorWell`` - - GTK: ``Gtk.ColorButton`` or ``Gtk.ColorSelection`` - - iOS: ? - - Winforms: ? - - Android: ? + - Cocoa: ``NSColorWell`` + - GTK: ``Gtk.ColorButton`` or ``Gtk.ColorSelection`` + - iOS: ? + - Winforms: ? + - Android: ? * ``SearchInput`` - A variant of ``TextField`` that is decorated as a search box. - - Cocoa: ``NSSearchField`` - - GTK: ``Gtk.Entry`` - - iOS: ``UISearchBar``? - - Winforms: ? - - Android: ? + - Cocoa: ``NSSearchField`` + - GTK: ``Gtk.Entry`` + - iOS: ``UISearchBar``? + - Winforms: ? + - Android: ? Views ~~~~~ @@ -60,80 +90,76 @@ usually in a read-only manner. * ``VideoView`` - Display a video - - Cocoa: ``AVPlayerView`` - - GTK: Custom integration with ``GStreamer`` - - iOS: ``MPMoviePlayerController`` - - Winforms: ? - - Android: ? + - Cocoa: ``AVPlayerView`` + - GTK: Custom integration with ``GStreamer`` + - iOS: ``MPMoviePlayerController`` + - Winforms: ? + - Android: ? * ``PDFView`` - Display a PDF document - - Cocoa: ``PDFView`` - - GTK: ? - - iOS: Integration with QuickLook? - - Winforms: ? - - Android: ? - -* ``MapView`` - Display a map - - - Cocoa: ``MKMapView`` - - GTK: Probably a ``Webkit.WebView`` pointing at Google Maps/OpenStreetMap - - iOS: ``MKMapView`` - - Winforms: ? - - Android: ? - + - Cocoa: ``PDFView`` + - GTK: ? + - iOS: Integration with QuickLook? + - Winforms: ? + - Android: ? Container widgets ~~~~~~~~~~~~~~~~~ Containers are widgets that can contain other widgets. -* ``ButtonContainer`` - A layout for a group of radio/checkbox options - - - Cocoa: ``NSMatrix``, or ``NSView`` with pre-set constraints. - - GTK: ``Gtk.ListBox`` - - iOS: ? - - Winforms: ? - - Android: ? - * ``FormContainer`` - A layout for a "key/value" or "label/widget" form - - Cocoa: ``NSForm``, or ``NSView`` with pre-set constraints. - - GTK: - - iOS: - - Winforms: ? - - Android: ? + - Cocoa: ``NSForm``, or ``NSView`` with pre-set constraints. + - GTK: + - iOS: + - Winforms: ? + - Android: ? * ``NavigationContainer`` - A container view that holds a navigable tree of sub-views - Essentially a view that has a "back" button to return to the previous view - in a hierarchy. Example of use: Top level navigation in the macOS System - Preferences panel. + Essentially a view that has a "back" button to return to the previous view + in a hierarchy. Example of use: Top level navigation in the macOS System + Preferences panel. - - Cocoa: No native control - - GTK: No native control; ``Gtk.HeaderBar`` in 3.10+ - - iOS: ``UINavigationBar`` + ``NavigationController`` - - Winforms: ? - - Android: ? + - Cocoa: No native control + - GTK: No native control; ``Gtk.HeaderBar`` in 3.10+ + - iOS: ``UINavigationBar`` + ``NavigationController`` + - Winforms: ? + - Android: ? -Miscellaneous -~~~~~~~~~~~~~ +Other capabilities +------------------ One of the aims of Toga is to provide a rich, feature-driven approach to app development. This requires the development of APIs to support rich features. -* Preferences - Support for saving app preferences, and visualizing them in a +* **Preferences** - Support for saving app preferences, and visualizing them in a platform native way. -* Notification when updates are available +* **Notification** - A mechanism to display popup "toast"-style notifications + +* **System tray icons** - Presenting an icon and/or menu in the platform's system tray - + possibly without having a main app window at all. + +* **Licensing/registration** - Monetization is not a bad thing, and shouldn't be + mutually exclusive with open source. + +* **Audio** - The ability to play sound files, either once off, or on a loop. + +* **Cloud data access** - Traditional apps store all their files locally; however, + using cloud services or network resources is increasingly common, especially in + mobile apps. However, accessing cloud-based files can be very complicated; Toga + is in a position to provide a file-like API that abstracts accessing these APIs. -* Easy Licensing/registration of apps - Monetization is not a bad thing, and - shouldn't be mutually exclusive with open source. +* **QR code scanning** - The ability to scan QR codes and bar codes in an app, and + return the encoded data. Platforms --------- -Toga currently has good support for Cocoa on macOS, GTK on Linux, Winforms on -Windows, iOS and Android. Proof-of-concept support exists for single page web -apps. Support for a more modern Windows API would be desirable. +Toga currently has good support for Cocoa on macOS, GTK on Linux, Winforms on Windows, +iOS and Android. Proof-of-concept support exists for single page web apps and consoles. +Support for a more modern Windows API would be desirable, as would support for Qt. diff --git a/docs/how-to/backends/android.rst b/docs/how-to/backends/android.rst deleted file mode 100644 index cb75794649..0000000000 --- a/docs/how-to/backends/android.rst +++ /dev/null @@ -1,45 +0,0 @@ -======= -Android -======= - -The Android backend uses `Material3 widgets `__. - -The native APIs are accessed using `Chaquopy -`__. - -Activities and Intents -====================== - -On Android, some interactions are managed using Activities, which are started using -Intents. - -Android's implementation of the :any:`toga.App` class includes the method -:meth:`~toga_android.App.start_activity()`, which can be used to start an activity. - -.. py:method:: toga_android.App.start_activity(self, activity, *options, on_complete=None) - - Start a native Android activity. - - :param activity: The ``android.content.Intent`` instance to start - :param options: Any additional arguments to pass to the native - ``android.app.Activity.startActivityForResult()`` call. - :param on_complete: A callback to invoke when the activity completes. The callback - will be invoked with 2 arguments: the result code, and the result data. - -To use this method, instantiate an instance of ``android.content.Intent``; optionally, -provide additional arguments, and a callback that will be invoked when the activity -completes. For example, to dial a phone number with the ``Intent.ACTION_DIAL`` intent:: - - from android.content import Intent - from android.net import Uri - - intent = new Intent(Intent.ACTION_DIAL) - intent.setData(Uri.parse("tel:0123456789")) - - def number_dialed(result, data): - # result is the status code (e.g., Activity.RESULT_OK) - # data is the value returned by the activity. - ... - - # Assuming your toga.App app instance is called `app` - app._impl.start_activity(intent, on_complete=number_dialed) diff --git a/docs/how-to/backends/cocoa.rst b/docs/how-to/backends/cocoa.rst deleted file mode 100644 index bfabec60b2..0000000000 --- a/docs/how-to/backends/cocoa.rst +++ /dev/null @@ -1,9 +0,0 @@ -============= -Cocoa (macOS) -============= - -The backend used on macOS uses the `AppKit API -`__, also known as Cocoa. - -The native APIs are accessed using `Rubicon Objective C -`__. diff --git a/docs/how-to/backends/gtk.rst b/docs/how-to/backends/gtk.rst deleted file mode 100644 index 830701f724..0000000000 --- a/docs/how-to/backends/gtk.rst +++ /dev/null @@ -1,8 +0,0 @@ -=== -GTK -=== - -The GTK backend uses the `GTK3 API `__. - -The native APIs are accessed using the `PyGObject binding -`__. diff --git a/docs/how-to/backends/iOS.rst b/docs/how-to/backends/iOS.rst deleted file mode 100644 index 16a7d0ff79..0000000000 --- a/docs/how-to/backends/iOS.rst +++ /dev/null @@ -1,8 +0,0 @@ -=== -iOS -=== - -The iOS backend uses `UIKit `. - -The native APIs are accessed using `Rubicon Objective C -`__. diff --git a/docs/how-to/backends/index.rst b/docs/how-to/backends/index.rst deleted file mode 100644 index 0ff242452e..0000000000 --- a/docs/how-to/backends/index.rst +++ /dev/null @@ -1,27 +0,0 @@ -============================== -Backend implementation details -============================== - -Although Toga is a cross-platform toolkit, it is sometimes necessary to invoke -platform-specific logic. These guides provide information on how platform-specific -features map onto the Toga backend API. - -Accessing these APIs will result in an application that is no longer cross-platform -(unless you gate the usage of these APIs with ``sys.platform`` or -``toga.platform.current_platform`` checks); however, accessing a backend API may be the -only way to implement a feature that Toga doesn't provide. - -For details on how to access the the backend implementations, see the documentation on -:ref:`Toga's three-layer architecture `. - -.. toctree:: - :maxdepth: 1 - :glob: - - android - gtk - iOS - cocoa - textual - web - winforms diff --git a/docs/how-to/backends/textual.rst b/docs/how-to/backends/textual.rst deleted file mode 100644 index 20e73c2c17..0000000000 --- a/docs/how-to/backends/textual.rst +++ /dev/null @@ -1,8 +0,0 @@ -======= -Textual -======= - -The Textual backend uses the `Textual API `__. - -The native APIs are accessed using `Rubicon Objective C -`__. diff --git a/docs/how-to/backends/web.rst b/docs/how-to/backends/web.rst deleted file mode 100644 index 859c91b28c..0000000000 --- a/docs/how-to/backends/web.rst +++ /dev/null @@ -1,7 +0,0 @@ -=== -Web -=== - -The Web backend uses `Shoelace web components `__. - -The DOM is accessed using `PyScript `__. diff --git a/docs/how-to/backends/winforms.rst b/docs/how-to/backends/winforms.rst deleted file mode 100644 index 72b9419151..0000000000 --- a/docs/how-to/backends/winforms.rst +++ /dev/null @@ -1,8 +0,0 @@ -================== -Winforms (Windows) -================== - -The backend used on Windows uses the `Windows Forms API -`__. - -The native .NET APIs are accessed using `Python.NET `__. diff --git a/docs/how-to/contribute-code.rst b/docs/how-to/contribute/code.rst similarity index 99% rename from docs/how-to/contribute-code.rst rename to docs/how-to/contribute/code.rst index 0b5905f717..00cbbb43c0 100644 --- a/docs/how-to/contribute-code.rst +++ b/docs/how-to/contribute/code.rst @@ -1,8 +1,8 @@ .. _contribute: -============================== -How to contribute code to Toga -============================== +========================= +Contributing code to Toga +========================= If you experience problems with Toga, `log them on GitHub`_. If you want to contribute code, please `fork the code`_ and `submit a pull request`_. @@ -429,10 +429,9 @@ does nothing but reproduce the problem) can be a huge help. Contribute improvements to documentation ---------------------------------------- -We've got a :doc:`separate contribution guide <./contribute-docs>` for -documentation contributions. This covers how to set up your development -environment to build Toga's documentation, and separate ideas for what to work -on. +We've got a :doc:`separate contribution guide <./docs>` for documentation contributions. +This covers how to set up your development environment to build Toga's documentation, +and separate ideas for what to work on. Implement a platform native widget ---------------------------------- diff --git a/docs/how-to/contribute-docs.rst b/docs/how-to/contribute/docs.rst similarity index 100% rename from docs/how-to/contribute-docs.rst rename to docs/how-to/contribute/docs.rst diff --git a/docs/how-to/contribute/index.rst b/docs/how-to/contribute/index.rst new file mode 100644 index 0000000000..b677109f76 --- /dev/null +++ b/docs/how-to/contribute/index.rst @@ -0,0 +1,13 @@ +==================== +Contributing to Toga +==================== + +Toga is an open source project, and actively encourages community contributions. The +following guides will help you get started contributing to Toga. + +.. toctree:: + :maxdepth: 2 + :glob: + + code + docs diff --git a/docs/how-to/get-started.rst b/docs/how-to/get-started.rst deleted file mode 100644 index a9a7e1db21..0000000000 --- a/docs/how-to/get-started.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. _get-started: - -================== -How to get started -================== - -.. note: - - If you're new to Toga, we recommend starting with the :ref:`tutorial`, which will - take you step-by-step through your first steps and introduce you to the important - concepts you need to become familiar with. If you prefer just to dive in, read on. - -Quickstart -========== - -Create a new virtual environment. In your virtual environment, install Toga, and -then run it: - -.. code-block:: console - - $ python -m pip install toga-demo - $ toga-demo - -This will pop up a GUI window showing the full range of widgets available -to an application using Toga. - -Have fun, and see the :ref:`reference` to learn more about what's going on. diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst index 237e365e95..a543734ff6 100644 --- a/docs/how-to/index.rst +++ b/docs/how-to/index.rst @@ -13,8 +13,6 @@ stand alone. :maxdepth: 2 :glob: - Get started - Contribute code to Toga - Contribute documentation to Toga - backends/index + topics/index + contribute/index internal/index diff --git a/docs/background/topics/data-sources.rst b/docs/how-to/topics/data-sources.rst similarity index 100% rename from docs/background/topics/data-sources.rst rename to docs/how-to/topics/data-sources.rst diff --git a/docs/background/topics/index.rst b/docs/how-to/topics/index.rst similarity index 100% rename from docs/background/topics/index.rst rename to docs/how-to/topics/index.rst diff --git a/docs/background/topics/layout.rst b/docs/how-to/topics/layout.rst similarity index 100% rename from docs/background/topics/layout.rst rename to docs/how-to/topics/layout.rst diff --git a/docs/index.rst b/docs/index.rst index c6b38bf7af..fbb0302b40 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,8 +6,8 @@ Toga is a Python native, OS native, cross platform GUI toolkit. Toga consists of library of base components with a shared interface to simplify platform-agnostic GUI development. -Toga is available on macOS, Windows, Linux (GTK), Android, iOS, and for -single-page web apps. +Toga is available on macOS, Windows, Linux (GTK), Android, iOS, for +single-page web apps, and console apps. .. tabs:: @@ -29,49 +29,45 @@ single-page web apps. :align: center :width: 450px +.. raw:: html -.. rst-class:: row - -Table of contents -================= +
:ref:`Tutorial ` -------------------------- -Get started with a hands-on introduction to Toga for beginners. +* :doc:`A quick Toga demonstration ` +* :doc:`A hands-on introduction to Toga ` -:ref:`How-to guides ` ------------------------------ +:ref:`Reference ` +---------------------------- -Guides and recipes for common problems and tasks. +* :doc:`API reference ` +* :doc:`Toga's platform support ` +* :doc:`Widget support by platform ` +* :doc:`Managing style with Toga ` +* :doc:`Toga's plugin interfaces ` -:ref:`Background ` ------------------------------- - -Explanation and discussion of key topics and concepts. +:ref:`How-to ` +---------------------- -:ref:`Reference ` ----------------------------- +* :doc:`Topic guides ` +* :doc:`Contribute to Toga ` +* :doc:`Internal Toga processes ` -Technical reference - commands, modules, classes, methods. +:ref:`Background ` +------------------------------ -Community -========= +* :doc:`Learn more about Toga ` +* :doc:`Contacting the BeeWare community ` +* :doc:`Toga's architecture and other internals ` -Toga is part of the `BeeWare suite`_. You can talk to the community through: -* `@beeware@fosstodon.org on Mastodon`_ -* `Discord`_ -* The Toga `Github Discussions forum`_ +.. toctree:: -We foster a welcoming and respectful community as described in our -`BeeWare Community Code of Conduct`_. +.. raw:: html -.. _BeeWare suite: https://beeware.org/ -.. _@beeware@fosstodon.org on Mastodon: https://fosstodon.org/@beeware -.. _Discord: https://beeware.org/bee/chat/ -.. _Github Discussions forum: https://github.com/beeware/toga/discussions -.. _BeeWare Community Code of Conduct: https://beeware.org/community/behavior/ +
.. toctree:: @@ -79,8 +75,7 @@ We foster a welcoming and respectful community as described in our :hidden: :titlesonly: - tutorial/index - how-to/index reference/index + how-to/index background/index diff --git a/docs/reference/api/resources/sources/list_source.rst b/docs/reference/api/resources/sources/list_source.rst index 3b891b96bc..4972d06b38 100644 --- a/docs/reference/api/resources/sources/list_source.rst +++ b/docs/reference/api/resources/sources/list_source.rst @@ -8,7 +8,7 @@ Usage Data sources are abstractions that allow you to define the data being managed by your application independent of the GUI representation of that data. For details on the use -of data sources, see the :doc:`background guide `. +of data sources, see the :doc:`topic guide `. ListSource is an implementation of an ordered list of data. When a ListSource is created, it is given a list of ``accessors`` - these are the attributes that all items diff --git a/docs/reference/api/resources/sources/source.rst b/docs/reference/api/resources/sources/source.rst index 6d9b13f9f9..b73429e9e7 100644 --- a/docs/reference/api/resources/sources/source.rst +++ b/docs/reference/api/resources/sources/source.rst @@ -8,7 +8,7 @@ Usage Data sources are abstractions that allow you to define the data being managed by your application independent of the GUI representation of that data. For details on the use -of data sources, see the :doc:`background guide `. +of data sources, see the :doc:`topic guide `. Source isn't useful on its own; it is a base class for data source implementations. It is used by ListSource, TreeSource and ValueSource, but it can also be used by custom diff --git a/docs/reference/api/resources/sources/tree_source.rst b/docs/reference/api/resources/sources/tree_source.rst index d38e0807db..2abb766e05 100644 --- a/docs/reference/api/resources/sources/tree_source.rst +++ b/docs/reference/api/resources/sources/tree_source.rst @@ -8,7 +8,7 @@ Usage Data sources are abstractions that allow you to define the data being managed by your application independent of the GUI representation of that data. For details on the use -of data sources, see the :doc:`background guide `. +of data sources, see the :doc:`topic guide `. TreeSource is an implementation of an ordered hierarchical tree of values. When a TreeSource is created, it is given a list of ``accessors`` - these are the attributes diff --git a/docs/reference/api/resources/sources/value_source.rst b/docs/reference/api/resources/sources/value_source.rst index 20472f065b..6a81bd603b 100644 --- a/docs/reference/api/resources/sources/value_source.rst +++ b/docs/reference/api/resources/sources/value_source.rst @@ -8,7 +8,7 @@ Usage Data sources are abstractions that allow you to define the data being managed by your application independent of the GUI representation of that data. For details on the use -of data sources, see the :doc:`background guide `. +of data sources, see the :doc:`topic guide `. ValueSource is an wrapper around a single atomic value. diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 46fe473dbc..b2047cf614 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -7,8 +7,8 @@ Reference .. toctree:: :maxdepth: 1 + api/index platforms/index widgets_by_platform - api/index style/index plugins/index diff --git a/docs/reference/platforms/android.rst b/docs/reference/platforms/android.rst index 23917dd4dc..6669ae5cce 100644 --- a/docs/reference/platforms/android.rst +++ b/docs/reference/platforms/android.rst @@ -6,20 +6,62 @@ The Toga backend for Android is `toga-android `__. Prerequisites -------------- +============= ``toga-android`` requires Android SDK 24 (Android 7 / Nougat) or newer. Installation ------------- +============ ``toga-android`` must be manually installed into an Android project; The recommended approach for deploying ``toga-android`` is to use `Briefcase `__ to package your app. Implementation details +====================== + +The ``toga-android`` backend uses the `Android Java API +`__, with `Material3 widgets +`__. It uses `Chaquopy `__ to +provide a bridge to the native Android Java libraries and implement Java interfaces from +Python. + +Platform-specific APIs +====================== + +Activities and Intents ---------------------- -``toga-android`` uses the Android Java APIs to build apps. It uses `Chaquopy -`__ to provide a bridge to the native Android Java -libraries and implement Java interfaces from Python. +On Android, some interactions are managed using Activities, which are started using +Intents. + +Android's implementation of the :any:`toga.App` class includes the method +:meth:`~toga_android.App.start_activity()`, which can be used to start an activity. + +.. py:method:: toga_android.App.start_activity(self, activity, *options, on_complete=None) + + Start a native Android activity. + + :param activity: The ``android.content.Intent`` instance to start + :param options: Any additional arguments to pass to the native + ``android.app.Activity.startActivityForResult()`` call. + :param on_complete: A callback to invoke when the activity completes. The callback + will be invoked with 2 arguments: the result code, and the result data. + +To use this method, instantiate an instance of ``android.content.Intent``; optionally, +provide additional arguments, and a callback that will be invoked when the activity +completes. For example, to dial a phone number with the ``Intent.ACTION_DIAL`` intent:: + + from android.content import Intent + from android.net import Uri + + intent = new Intent(Intent.ACTION_DIAL) + intent.setData(Uri.parse("tel:0123456789")) + + def number_dialed(result, data): + # result is the status code (e.g., Activity.RESULT_OK) + # data is the value returned by the activity. + ... + + # Assuming your toga.App app instance is called `app` + app._impl.start_activity(intent, on_complete=number_dialed) diff --git a/docs/reference/platforms/iOS.rst b/docs/reference/platforms/iOS.rst index e01a481528..ce35f4a62f 100644 --- a/docs/reference/platforms/iOS.rst +++ b/docs/reference/platforms/iOS.rst @@ -20,6 +20,8 @@ to package your app. Implementation details ---------------------- -``toga-iOS`` uses the iOS UIKit Objective-C APIs to build apps. It uses `Rubicon -Objective-C `__ to provide a bridge to the native -UIKit libraries from Python. +The ``toga-iOS`` backend uses the `UIKit Objective C +API `__. + +The native APIs are accessed using `Rubicon Objective C +`__. diff --git a/docs/reference/platforms/linux.rst b/docs/reference/platforms/linux.rst index 6e11c60fad..919bfaf92e 100644 --- a/docs/reference/platforms/linux.rst +++ b/docs/reference/platforms/linux.rst @@ -21,7 +21,8 @@ The Toga backend for Linux (and other Unix-like operating systems) is `toga-gtk Although GTK *can* be installed on Windows and macOS, and the ``toga-gtk`` backend *may* work on those platforms, this is not officially supported by Toga. We - recommend using ``toga-winforms`` on Windows, and ``toga-cocoa`` on macOS. + recommend using ``toga-winforms`` on :doc:`./windows`, and ``toga-cocoa`` + on :doc:`macOS`. Prerequisites ------------- @@ -52,4 +53,7 @@ Installation Implementation details ---------------------- -``toga-gtk`` uses the native GObject Python bindings. +The ``toga-gtk`` backend uses the `GTK3 API `__. + +The native APIs are accessed using the `PyGObject binding +`__. diff --git a/docs/reference/platforms/macOS.rst b/docs/reference/platforms/macOS.rst index 54c7570bf0..7c4a6670cd 100644 --- a/docs/reference/platforms/macOS.rst +++ b/docs/reference/platforms/macOS.rst @@ -27,6 +27,8 @@ Installation Implementation details ---------------------- -``toga-cocoa`` uses the macOS AppKit Objective-C APIs to build apps. It uses `Rubicon -Objective-C `__ to provide a bridge to the native -AppKit libraries from Python. +The ``toga-cocoa`` backend uses the `AppKit Objective-C API +`__, also known as Cocoa. + +The native APIs are accessed using `Rubicon Objective C +`__. diff --git a/docs/reference/platforms/terminal.rst b/docs/reference/platforms/terminal.rst index 54174e54b5..560f38c1e8 100644 --- a/docs/reference/platforms/terminal.rst +++ b/docs/reference/platforms/terminal.rst @@ -33,7 +33,7 @@ the backend. Implementation details ---------------------- -``toga-textual`` uses the `Textual `__ UI toolkit. +The ``toga-textual`` backend uses the `Textual API `__. macOS Terminal.app limitations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/reference/platforms/web.rst b/docs/reference/platforms/web.rst index 79d6e52a70..21c5fda378 100644 --- a/docs/reference/platforms/web.rst +++ b/docs/reference/platforms/web.rst @@ -13,8 +13,9 @@ Toga is able to deploy apps as a single-page web app using the `toga-web Prerequisites ------------- -``toga-web`` will run in any modern browser. It requires `PyScript`_ 2023.05.01 or -newer, and `Shoelace v2.3 `__. +``toga-web`` will run in any modern browser. It requires `PyScript +`__ 2023.05.01 or newer, and `Shoelace v2.3 +`__. Installation ------------ @@ -28,6 +29,7 @@ configuration file. Implementation details ---------------------- -``toga-web`` uses `PyScript`_ to run Python code in the browser. +The ``toga-web`` backend is implemented using `Shoelace web components +`__. -.. _PyScript: https://pyscript.net +The DOM is accessed using `PyScript `__. diff --git a/docs/reference/platforms/windows.rst b/docs/reference/platforms/windows.rst index d24ec6b7ff..d55c28a504 100644 --- a/docs/reference/platforms/windows.rst +++ b/docs/reference/platforms/windows.rst @@ -34,4 +34,7 @@ Installation Implementation details ---------------------- -``toga-winforms`` uses `Python.net `__. +The ``toga-winforms`` backend uses the `Windows Forms API +`__. + +The native .NET APIs are accessed using `Python.NET `__. diff --git a/docs/tutorial/get-started.rst b/docs/tutorial/get-started.rst new file mode 100644 index 0000000000..3faa55822e --- /dev/null +++ b/docs/tutorial/get-started.rst @@ -0,0 +1,19 @@ +.. _get-started: + +================ +Toga quick start +================ + +Create a new virtual environment. In your virtual environment, install Toga, and +then run it: + +.. code-block:: console + + $ python -m pip install toga-demo + $ toga-demo + +This will pop up a GUI window showing the full range of widgets available +to an application using Toga. + +If you want to see how to write a Toga app of your own, you can :doc:`start the tutorial +`. diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index 4845ce3940..fc9c74d47c 100644 --- a/docs/tutorial/index.rst +++ b/docs/tutorial/index.rst @@ -14,14 +14,21 @@ Tutorials .. toctree:: :maxdepth: 1 + :hidden: :titlesonly: + Get started tutorial-0 tutorial-1 tutorial-2 tutorial-3 tutorial-4 +A quick test drive +================== + +Before you run through the tutorial, :doc:`install a Toga app ` to see what +Toga looks like. Tutorial 0 - your first Toga app ================================