From ab93cbc1bff8befe12d6da8ac6f9eb3e789badc3 Mon Sep 17 00:00:00 2001 From: david-swift Date: Sat, 30 Mar 2024 07:24:56 +0100 Subject: [PATCH] Improve docc documentation --- .../Adwaita.docc/Advanced/CreatingWidgets.md | 63 +++++++++++++++++++ .../Adwaita.docc/Advanced/PublishingApps.md | 48 ++++++++++++++ Sources/Adwaita/Adwaita.docc/Adwaita.md | 11 ++++ .../{ => Basics}/CreatingViews.md | 2 +- .../{ => Basics}/KeyboardShortcuts.md | 0 .../Adwaita.docc/{ => Basics}/Windows.md | 4 +- 6 files changed, 125 insertions(+), 3 deletions(-) create mode 100644 Sources/Adwaita/Adwaita.docc/Advanced/CreatingWidgets.md create mode 100644 Sources/Adwaita/Adwaita.docc/Advanced/PublishingApps.md rename Sources/Adwaita/Adwaita.docc/{ => Basics}/CreatingViews.md (97%) rename Sources/Adwaita/Adwaita.docc/{ => Basics}/KeyboardShortcuts.md (100%) rename Sources/Adwaita/Adwaita.docc/{ => Basics}/Windows.md (96%) diff --git a/Sources/Adwaita/Adwaita.docc/Advanced/CreatingWidgets.md b/Sources/Adwaita/Adwaita.docc/Advanced/CreatingWidgets.md new file mode 100644 index 0000000..27f55e9 --- /dev/null +++ b/Sources/Adwaita/Adwaita.docc/Advanced/CreatingWidgets.md @@ -0,0 +1,63 @@ +# Creating widgets + +Widgets are special views that do not provide a collection of other views as a content, +but have functions that are called when creating or updating the view. +Normally, a widget manages a GTK or Libadwaita widget using the C API. + +## Recreate the Text widget +In this tutorial, we will recreate the ``Text`` widget. +A widget conforms to the ``Widget`` protocol: +```swift +struct CustomText: Widget { } +``` +You can add properties to the widget: +```swift +struct CustomText: Widget { + + var text: String + +} +``` +This widget can be called in a view body using `CustomText(text: "Hello, world!")`. +Now, add the two functions required by the protocol: +```swift +import CAdw + +struct CustomText: Widget { + + var text: String + + public func container(modifiers: [(View) -> View]) -> ViewStorage { } + public func update(_ storage: ViewStorage, modifiers: [(View) -> View], updateProperties: Bool) { } + +} +``` +Import CAdw which exposes the whole C Libadwaita and Gtk API to Swift. + +## The `container(modifiers:)` function +This function initializes the widget when the widget appears for the first time. +It expects a ``ViewStorage`` as the return type. +In our case, this function is very simple: +```swift +func container(modifiers: [(View) -> View]) -> ViewStorage { + .init(gtk_label_new(text)?.opaque()) +} +``` + +## The `update(_:modifiers:updateProperties:)` function +Whenever a state of the app changes, the ``Widget/update(_:modifiers:updateProperties:)`` function of the widget gets called. +You get the view storage that you have previously initialized as a parameter. +Update the storage to reflect the current state of the widget: +```swift +func update(_ storage: ViewStorage, modifiers: [(View) -> View], updateProperties: Bool) { + if updateProperties { + gtk_label_set_label(storage.pointer, text) + } +} +``` + +## Containers +Some widgets act as containers that accept other widgets as children. +In that case, use the ``ViewStorage``'s `content` property for storing their view storages. +In the ``Widget/update(_:modifiers:updateProperties:)`` function, update the children's storages. +Take a look at the code of the container widgets in this library as a reference. diff --git a/Sources/Adwaita/Adwaita.docc/Advanced/PublishingApps.md b/Sources/Adwaita/Adwaita.docc/Advanced/PublishingApps.md new file mode 100644 index 0000000..958ae3a --- /dev/null +++ b/Sources/Adwaita/Adwaita.docc/Advanced/PublishingApps.md @@ -0,0 +1,48 @@ +# Publishing apps + +Learn how to publish your apps using Flatpak. + +Once you feel ready to publish your app to [Flathub](https://flathub.org/), or +to a [self-hosted repository](https://docs.flatpak.org/en/latest/hosting-a-repository.html), +you can follow this step-by-step guide. + +## Create a Flatpak manifest +You have to create a Flatpak manifest, similar to the one [here](https://github.com/flathub/io.github.david_swift.Flashcards/blob/master/io.github.david_swift.Flashcards.json). +Find detailed information in the [Flatpak documentation](https://docs.flatpak.org/en/latest/manifests.html). +This is the only code that should be submitted to Flathub. +There will be a new repository created under `flathub/app-id` that hosts the manifest. + +### SDK Extension for Swift 5 +I recommend using the SDK Extension for building the app. +Add the following snippet. + +```json +"sdk-extensions": [ + "org.freedesktop.Sdk.Extension.swift5" +] +``` + +### Generate sources for the Swift Package Manager +You cannot access the web while building the app. +Therefore, you need to add all the dependencies as modules to the manifest file. +This can be automated using the [Flatpak builder tool for SPM](https://github.com/flatpak/flatpak-builder-tools/tree/master/spm). + +## MetaInfo file +In the Flatpak Manifest file, under the build commands, you should add the [code to install the app's +MetaInfo file](https://github.com/flathub/io.github.david_swift.Flashcards/blob/c5c0421ffb5589641ddb44a269a6e7e07d430581/io.github.david_swift.Flashcards.json#L49). +The MetaInfo file is located in the app's main repository (not in the Flathub repository). +Take a look at the example [here](https://github.com/david-swift/Memorize/blob/main/data/io.github.david_swift.Flashcards.metainfo.xml). + +## Desktop entry file +[This line](https://github.com/flathub/io.github.david_swift.Flashcards/blob/c5c0421ffb5589641ddb44a269a6e7e07d430581/io.github.david_swift.Flashcards.json#L50) in the example installs the Desktop Entry file. +It is located in the [main repository](https://github.com/david-swift/Memorize/blob/main/data/io.github.david_swift.Flashcards.desktop). + +## Check the requirements +Before submitting an app to Flathub, make sure to check the [requirements](https://docs.flathub.org/docs/for-app-authors/requirements), +[MetaInfo guidelines](https://docs.flathub.org/docs/for-app-authors/metainfo-guidelines/), and [quality guidelines](https://docs.flathub.org/docs/for-app-authors/metainfo-guidelines/quality-guidelines). +Then, test and submit the app following the [submission instructions](https://docs.flathub.org/docs/for-app-authors/submission). + +## Get the badges +Use the [Flathub badges](https://flathub.org/badges) to inform users about the simple installation option. +Even more assets are available [here](https://github.com/flathub-infra/assets). + diff --git a/Sources/Adwaita/Adwaita.docc/Adwaita.md b/Sources/Adwaita/Adwaita.docc/Adwaita.md index 7be0585..5468d6c 100644 --- a/Sources/Adwaita/Adwaita.docc/Adwaita.md +++ b/Sources/Adwaita/Adwaita.docc/Adwaita.md @@ -81,3 +81,14 @@ Find more information in the [template repository](https://github.com/AparokshaU ### Tutorials - + +### Basics + +- +- +- + +### Advanced + +- +- diff --git a/Sources/Adwaita/Adwaita.docc/CreatingViews.md b/Sources/Adwaita/Adwaita.docc/Basics/CreatingViews.md similarity index 97% rename from Sources/Adwaita/Adwaita.docc/CreatingViews.md rename to Sources/Adwaita/Adwaita.docc/Basics/CreatingViews.md index 99feae8..f27faaa 100644 --- a/Sources/Adwaita/Adwaita.docc/CreatingViews.md +++ b/Sources/Adwaita/Adwaita.docc/Basics/CreatingViews.md @@ -30,7 +30,7 @@ In this example, the widgets ``HeaderBar`` and ``Text`` are used. `padding` is a view modifier, a function that modifies a view, which adds some padding around the text. ## Create custom views -While directly adding widgets into the `Window`'s body might work for very simple apps, +While directly adding widgets into the ``Window``'s body might work for very simple apps, it can get messy very quickly. Create custom views by declaring types that conform to the ``View`` protocol: ```swift diff --git a/Sources/Adwaita/Adwaita.docc/KeyboardShortcuts.md b/Sources/Adwaita/Adwaita.docc/Basics/KeyboardShortcuts.md similarity index 100% rename from Sources/Adwaita/Adwaita.docc/KeyboardShortcuts.md rename to Sources/Adwaita/Adwaita.docc/Basics/KeyboardShortcuts.md diff --git a/Sources/Adwaita/Adwaita.docc/Windows.md b/Sources/Adwaita/Adwaita.docc/Basics/Windows.md similarity index 96% rename from Sources/Adwaita/Adwaita.docc/Windows.md rename to Sources/Adwaita/Adwaita.docc/Basics/Windows.md index 186fdb1..b36e5ee 100644 --- a/Sources/Adwaita/Adwaita.docc/Windows.md +++ b/Sources/Adwaita/Adwaita.docc/Basics/Windows.md @@ -32,7 +32,7 @@ struct HelloWorld: App { ``` ## Showing windows -Every app contains the property `app`. +Every app contains the property ``App/app``. You can use this property for running functions that affect the whole app, e.g. quitting the app. Another use case is showing a window: ```swift @@ -66,7 +66,7 @@ It should be used for opening windows that cannot be presented more than once and for moving a window that is already open into the foreground. ## Adding windows -You can call the `addWindow(_:parent:)` function instead of `showWindow(_:)` +You can call the ``GTUIApp/addWindow(_:parent:)`` function instead of ``GTUIApp/showWindow(_:)`` if you want to add and focus another instance of a window type: ```swift @main