From eadc08d61d0899850c9a4368009a1bd227493fbe Mon Sep 17 00:00:00 2001 From: david-swift Date: Fri, 19 Jul 2024 23:41:19 +0200 Subject: [PATCH] Update documentation --- .github/workflows/docs.yml | 13 ++---- .../Button/ButtonCollection.swift | 10 ++--- Sources/TermKitBackend/Menu/Menu.swift | 2 +- .../TermKitBackend/Menu/MenuCollection.swift | 8 ++-- Sources/TermKitBackend/Model/TermKitApp.swift | 4 +- Sources/TermKitBackend/Scene/MenuBar.swift | 21 ++++----- Sources/TermKitBackend/Scene/Window.swift | 8 ++++ .../TermKitBackend.docc/GettingStarted.md | 40 +++++++++++++++++ Sources/TestApp/TestApp.swift | 45 ++++++++++++------- 9 files changed, 98 insertions(+), 53 deletions(-) create mode 100644 Sources/TermKitBackend/TermKitBackend.docc/GettingStarted.md diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index fae842f..d2a1907 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -23,15 +23,10 @@ jobs: - uses: actions/checkout@v4 - name: Build Docs run: | - xcrun xcodebuild docbuild \ - -scheme TermKitBackend \ - -destination 'generic/platform=macOS' \ - -derivedDataPath "$PWD/.derivedData" \ - -skipPackagePluginValidation - xcrun docc process-archive transform-for-static-hosting \ - "$PWD/.derivedData/Build/Products/Debug/TermKitBackend.doccarchive" \ - --output-path "docs" \ - --hosting-base-path "TermKitBackend" + sed -i '' -n 'H;${x;s/^\n//;s/ .package.*$/ .package(url: "https:\/\/github.com\/swiftlang\/swift-docc-plugin", from: "1.3.0"),\n&/;p;}' Package.swift + swift package --allow-writing-to-directory ./docs \ + generate-documentation --target TermKitBackend --output-path ./docs \ + --transform-for-static-hosting --hosting-base-path TermKitBackend - name: Modify Docs run: | echo "" > docs/index.html; diff --git a/Sources/TermKitBackend/Button/ButtonCollection.swift b/Sources/TermKitBackend/Button/ButtonCollection.swift index 0adf187..efd0d19 100644 --- a/Sources/TermKitBackend/Button/ButtonCollection.swift +++ b/Sources/TermKitBackend/Button/ButtonCollection.swift @@ -7,16 +7,14 @@ import TermKit -/// A menu is an item of a ``MenuBar``. +/// A collection of buttons. public struct ButtonCollection: ButtonContext.Widget, Wrapper { - /// The content of the menu. + /// The content of the collection. var content: Body - /// Initialize a menu. - /// - Parameters: - /// - label: The menu's label, displayed in the menu bar. - /// - content: The content of the menu. + /// Initialize a collection. + /// - Parameter content: The content of the collection. public init(@ViewBuilder content: @escaping () -> Body) { self.content = content() } diff --git a/Sources/TermKitBackend/Menu/Menu.swift b/Sources/TermKitBackend/Menu/Menu.swift index 4356469..3ce2cb9 100644 --- a/Sources/TermKitBackend/Menu/Menu.swift +++ b/Sources/TermKitBackend/Menu/Menu.swift @@ -7,7 +7,7 @@ import TermKit -/// A menu is an item of a ``MenuBar``. +/// A menu is an item of a `MenuBar`. public struct Menu: MenuContext.Widget { /// The menu's label, displayed in the menu bar. diff --git a/Sources/TermKitBackend/Menu/MenuCollection.swift b/Sources/TermKitBackend/Menu/MenuCollection.swift index aa16155..1c65d01 100644 --- a/Sources/TermKitBackend/Menu/MenuCollection.swift +++ b/Sources/TermKitBackend/Menu/MenuCollection.swift @@ -7,16 +7,14 @@ import TermKit -/// A menu is an item of a ``MenuBar``. +/// A collection of menus. public struct MenuCollection: MenuContext.Widget, Wrapper { - /// The content of the menu. + /// The content of the collection. var content: Body /// Initialize a menu. - /// - Parameters: - /// - label: The menu's label, displayed in the menu bar. - /// - content: The content of the menu. + /// - Parameter content: The content of the collection. public init(@ViewBuilder content: @escaping () -> Body) { self.content = content() } diff --git a/Sources/TermKitBackend/Model/TermKitApp.swift b/Sources/TermKitBackend/Model/TermKitApp.swift index aefc08c..110f36e 100644 --- a/Sources/TermKitBackend/Model/TermKitApp.swift +++ b/Sources/TermKitBackend/Model/TermKitApp.swift @@ -22,9 +22,7 @@ public class TermKitApp: AppStorage { public var storage: StandardAppStorage = .init() /// Initialize the app storage. - /// - Parameters: - /// - id: The identifier. - /// - app: The application. + /// - Parameter id: The identifier. public required init(id: String) { } /// Execute the app. diff --git a/Sources/TermKitBackend/Scene/MenuBar.swift b/Sources/TermKitBackend/Scene/MenuBar.swift index c568da2..7473637 100644 --- a/Sources/TermKitBackend/Scene/MenuBar.swift +++ b/Sources/TermKitBackend/Scene/MenuBar.swift @@ -8,10 +8,10 @@ import TermKit /// The menu bar scene element adds a menu bar to the top of the app. -public struct MenuBar: TermKitSceneElement { +struct MenuBar: TermKitSceneElement { /// The identifier of the menu bar. - public var id: String + var id: String /// The menu bar's content. var content: Body @@ -19,31 +19,28 @@ public struct MenuBar: TermKitSceneElement { /// - Parameters: /// - id: The identifier of the menu bar. /// - content: The menu bar's content. - public init(id: String = "main-menu", @ViewBuilder content: () -> Body) { + init(id: String = "main-menu", @ViewBuilder content: () -> Body) { self.id = id self.content = content() } /// Set up the initial scene storages. /// - Parameter app: The app storage. - public func setupInitialContainers(app: Storage) where Storage: AppStorage { + func setupInitialContainers(app: Storage) where Storage: AppStorage { app.storage.sceneStorage.append(container(app: app)) } /// The scene storage. /// - Parameter app: The app storage. - public func container(app: Storage) -> SceneStorage where Storage: AppStorage { + func container(app: Storage) -> SceneStorage where Storage: AppStorage { let items = MenuCollection { content }.container(modifiers: [], type: MenuContext.self) let menubar = TermKit.MenuBar( menus: items.pointer as? [TermKit.MenuBarItem] ?? [] ) - Task { - try await Task.sleep(nanoseconds: 1) - for element in Application.top.subviews { - element.y = .bottom(of: menubar) - } - Application.top.addSubview(menubar) + for element in Application.top.subviews { + element.y = .bottom(of: menubar) } + Application.top.addSubview(menubar) return .init(id: id, pointer: menubar) { menubar.ensureFocus() } @@ -54,7 +51,7 @@ public struct MenuBar: TermKitSceneElement { /// - storage: The storage to update. /// - app: The app storage. /// - updateProperties: Whether to update the view's properties. - public func update( + func update( _ storage: SceneStorage, app: Storage, updateProperties: Bool diff --git a/Sources/TermKitBackend/Scene/Window.swift b/Sources/TermKitBackend/Scene/Window.swift index 55502c4..0c1e219 100644 --- a/Sources/TermKitBackend/Scene/Window.swift +++ b/Sources/TermKitBackend/Scene/Window.swift @@ -67,4 +67,12 @@ public struct Window: TermKitSceneElement { Application.refresh() } + /// Add a menubar to the app. + /// - Parameter content: The mnu bar's content. + @SceneBuilder + public func menuBar(@ViewBuilder content: @escaping () -> Body) -> Scene { + self + MenuBar(content: content) + } + } diff --git a/Sources/TermKitBackend/TermKitBackend.docc/GettingStarted.md b/Sources/TermKitBackend/TermKitBackend.docc/GettingStarted.md new file mode 100644 index 0000000..fc0ec30 --- /dev/null +++ b/Sources/TermKitBackend/TermKitBackend.docc/GettingStarted.md @@ -0,0 +1,40 @@ +# Getting Started + +Learn how to use the TermKit backend. + +Knowledge about the Meta project is required. +Find more information [here](https://aparokshaui.github.io/meta/). + +## The App + +Define your app in the following way: + +```swift +import TermKitBackend + +@main +struct TestApp: App { + + let id = "io.github.AparokshaUI.TestApp" + var app: TermKitApp! + + var scene: Scene { + Window { + // Views (see list in documentation) + } + .menuBar { + Menu("_File") { // Menus + Button("_New") { // Buttons + print("Hi") + } + } + } + } + +} +``` + +## Widgets + +All the available widgets can be found in the documentation. +Take a look at the [sample app](https://github.com/david-swift/TermKitBackend/blob/main/Sources/TestApp/TestApp.swift) for more help. diff --git a/Sources/TestApp/TestApp.swift b/Sources/TestApp/TestApp.swift index e50b3e0..1217809 100644 --- a/Sources/TestApp/TestApp.swift +++ b/Sources/TestApp/TestApp.swift @@ -5,6 +5,7 @@ // Created by david-swift on 01.07.2024. // +@testable import Meta import TermKitBackend @main @@ -17,7 +18,6 @@ struct TestApp: App { var app: TermKitApp! var scene: Scene { - menuBar Window { VStack { Demos() @@ -29,10 +29,7 @@ struct TestApp: App { .vcenter() .infoBox("About TermKitBackend", message: aboutInfo, signal: about) } - } - - var menuBar: MenuBar { - .init { + .menuBar { fileMenu Menu("_Actions") { Button("_Hello, world!") { } @@ -86,31 +83,45 @@ struct Demos: View { } +struct ControlsModel: Model { + + var isOn = false + var fraction = 0 + var text = "Controls" + + var model: ModelData? + + func increaseFraction() { + Task { @MainActor in + setModel { $0.fraction += 1 } + } + } + +} + struct Controls: View { - @State private var isOn = false - @State private var fraction = 0 - @State private var text = "Controls" + @State private var model = ControlsModel() var view: Body { - Frame(text) { + Frame(model.text) { HStack { Button("Button (progress)") { - if fraction == 10 { - fraction = 0 + if model.fraction == 10 { + model.fraction = 0 } else { - fraction += 1 + model.increaseFraction() } } Button("Button (text)") { - text = "Hello" + model.text = "Hello" } } .frame(height: 1) - Checkbox(isOn ? "On" : "Off", isOn: $isOn) - TextField(text: $text) - .secret(isOn) - ProgressBar(value: .init(fraction), max: 10) + Checkbox(model.isOn ? "On" : "Off", isOn: $model.isOn) + TextField(text: $model.text) + .secret(model.isOn) + ProgressBar(value: .init(model.fraction), max: 10) } .frame(width: 40, height: 7) }