Merge pull request #42 from chenhaiteng/refactor/documentation-works

chenhaiteng · Jan 24, 2024 · 5087caa · 5087caa
2 parents f635c43 + 920ff03
commit 5087caa
Show file tree

Hide file tree

Showing 39 changed files with 556 additions and 60 deletions.
diff --git a/Markdown/Rings/ArcStack.md b/Markdown/Rings/ArcStack.md
@@ -0,0 +1,33 @@
+## ArcStack
+
+### Preview:
+ArcStack is based on the [Layout](https://developer.apple.com/documentation/swiftui/layout) protocol. It arranges views along the given arc.
+
+![Demo](../../Sources/Rings/Documentation.docc/Resources/ArcStack.gif)
+
+### Usage:
+Create an ArcStack
+```swift
+ArcStack {
+    Image(systemName:"star")
+    Text("arc view 1")
+    Text("arc view 2")
+    // other views...
+}
+```
+
+Create an ArcStack which is located on top leading corner:
+```swift
+ArcStack(anchor: .topLeading) {
+    // put views
+}
+```
+
+Layout views in an ArcStack with specified range:
+```swift
+ArcStack(range: 0...0.5) { // layout views in half of the arc
+    // put views
+}
+```
+
+For other usages, please refer to the preview in source code.
diff --git a/Markdown/Rings/ArchimedeanSpiralText.md b/Markdown/Rings/ArchimedeanSpiralText.md
@@ -1,8 +1,8 @@
-#  ArchimedeanSpiralText
+## ArchimedeanSpiralText
 
-## Preview:
+### Preview:
 
-![ArchimedeanSpiralTextDemo](https://user-images.githubusercontent.com/1284944/117950922-3ef10e80-b346-11eb-9da1-50b0f87990a2.gif)
+![Demo](../../Sources/Rings/Documentation.docc/Resources/ArchimedeanSpiralText.gif)
 
 ### Usage:
 ```swift

diff --git a/Markdown/Rings/ClockIndex.md b/Markdown/Rings/ClockIndex.md
@@ -1,8 +1,9 @@
-##  ClockIndex
+## ClockIndex
 
-![ClockIndex Demo Classic](https://user-images.githubusercontent.com/1284944/116664495-26d6d200-a9cb-11eb-906c-7ffe659dcfbc.gif)
+### Preview:
+![Demo](../../Sources/Rings/Documentation.docc/Resources/ClockIndex.gif)
 
-<img width="598" alt="earchly_clock_demo" src="https://user-images.githubusercontent.com/1284944/116664737-73baa880-a9cb-11eb-97e1-afcb49dfcfcd.png">
+![Demo](../../Sources/Rings/Documentation.docc/Resources/EarchlyClock.png)
 
 ### Usage:
 

diff --git a/Markdown/Rings/HandAiguille.md b/Markdown/Rings/HandAiguille.md
@@ -1,7 +1,7 @@
 ## HandAiguille
 
 ### Preview
-https://user-images.githubusercontent.com/1284944/117106480-83aeff80-adb2-11eb-8e82-d77d9569dcca.mov
+![Demo](../../Sources/Rings/Documentation.docc/Resources/HandAiguille.gif)
 
 ### Usage: 
 ```swift

diff --git a/Markdown/Rings/Knob.md b/Markdown/Rings/Knob.md
@@ -1,10 +1,10 @@
-##  Knob
+## Knob
 
-### Preview
+### Preview:
 
-![Knob Demo](https://user-images.githubusercontent.com/1284944/120065810-e2138900-c0a5-11eb-8324-2fe340bb578f.gif)
+![Demo](../../Sources/Rings/Documentation.docc/Resources/Knob.gif)
 
-### Usage
+### Usage:
 
 Following shows a basic Knob drawing value along the circumference.
 ```swift
@@ -17,7 +17,7 @@ Following shows a basic Knob drawing value along the circumference.
             }
     }.frame(width: 100.0, height: 100.0)    // setup knob size
 ```
-![Demo1](KnobDemo1.gif)
+![Demo1](../../Sources/Rings/Documentation.docc/Resources/KnobDemo1.gif)
 
 ---
 
@@ -37,7 +37,7 @@ By adding a ring layer, it makes a Knob which has a circular track.
             }
     }.frame(width: 100.0, height: 100.0)
 ```
-![Demo2](KnobDemo2.gif)
+![Demo2](../../Sources/Rings/Documentation.docc/Resources/KnobDemo2.gif)
 
 Also, it can make the knob and its track much richer by adjusting each layer. For more detail, see [ArcKnobLayer](KnobComponents/Layers/ArcKnobLayer.md)
 
@@ -50,10 +50,10 @@ Finally, it can apply images on knob.
         ImageKnobLayer(Image("SimpleKnob"))
     }.frame(width: 150, height: 150)    
 ```
-<img src="https://user-images.githubusercontent.com/1284944/120066082-61ee2300-c0a7-11eb-97e5-4a64b0bd4e8e.gif" alt="drawing" width="200"/>
+![Demo](../../Sources/Rings/Documentation.docc/Resources/ImageKnob.gif)
 
 And the image sample is following:
 
-<img src="https://user-images.githubusercontent.com/1284944/120066145-ac6f9f80-c0a7-11eb-9a46-20245ca15933.png" alt="drawing" width="200"/>
+![Demo](../../Sources/Rings/Documentation.docc/Resources/ImageKnobBG.png)
 
 
diff --git a/Markdown/Rings/KnobComponents/Layers/ArcKnobLayer.md b/Markdown/Rings/KnobComponents/Layers/ArcKnobLayer.md
@@ -1,12 +1,12 @@
-# ArcKnobLayer
+## ArcKnobLayer
 
-### Preview
+### Preview:
 
-![Demo](ArcKnobDemo.gif)
+![Demo](../../../Sources/Rings/Documentation.docc/Resources/ArcKnobDemo.gif)
 
 From left to right, those are fixed arc with gradient, non-fixed arc with gradient, and fixed arc with custom style and gradient color.
 
-### Usage
+### Usage:
 
 #### Non-fixed arc:
 ```swift

diff --git a/Markdown/Rings/RingStack.md b/Markdown/Rings/RingStack.md
@@ -0,0 +1,50 @@
+## RingStack
+
+### Preview:
+RingStack is based on the [Layout](https://developer.apple.com/documentation/swiftui/layout) protocol. It arranges views along a circle.
+
+![Demo](../../Sources/Rings/Documentation.docc/Resources/RingStack.gif)
+
+### Usage:
+Following code snippets placing views in a circle which radius depends on its frame:
+```swift
+RingStack {
+    Image(systemName: "star")
+    Image(systemName: "moon")
+    Image(systmeName: "sun.min")
+}
+```
+
+To specify those views into a fixed sized circle:
+```swift
+RingStack(radius: 100.0) {
+    Image(systemName: "star")
+    Image(systemName: "moon")
+    Image(systmeName: "sun.min")
+}.frame(width: 300.0, height: 300.0)
+```
+
+To layout views with offsets:
+```swift
+RingStack(center: UnitPoint(x:0.7, y:0.0)) {
+    // placing views here
+}
+```
+
+Apply rotation on whole RingStack:
+```swift
+RingStack(phase: Angle(degrees: 45.0)) {
+    // placing views here
+}
+```
+
+Also, it can support [ForEach](https://developer.apple.com/documentation/swiftui/foreach) syntax as following:
+```swift
+@State var numberCount: Int
+RingStack {
+    ForEach(1..<numberCount, id: \.self)  { num in
+        Text("\(num)")
+    }
+}
+```
+For more usages, please refer to the preview in source code.
diff --git a/Markdown/Rings/RingText.md b/Markdown/Rings/RingText.md
@@ -1,6 +1,8 @@
-##  RingText
+## RingText
 
-![RingDemo](RingTextDemo.gif)
+### Preview:
+
+![Demo](../../Sources/Rings/Documentation.docc/Resources/RingTextDemo.gif)
 
 ### Usage:
 
@@ -60,7 +62,7 @@ In additional, you can apply different layout based on some state:
 ```
 
 4. Debug layout with RingText's blue print:
-```
+```swift
   RingText(radius: 40.0, text: "1234567890").showBlueprint(true)
 ```
 
diff --git a/Markdown/Rings/SphericText.md b/Markdown/Rings/SphericText.md
@@ -1,8 +1,10 @@
 ## SphericText
 
-![Spheric Text Demo](https://user-images.githubusercontent.com/1284944/118671827-60f8fe00-b82a-11eb-9f0f-821841867cba.gif)
+### Preview:
 
-### Usage
+![Demo](../../Sources/Rings/Documentation.docc/Resources/SphericText.gif)
+
+### Usage:
 
 ```swift
 // Create SphericText with String

diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-![Screen Shot 2021-06-15 at 13 01 13](https://user-images.githubusercontent.com/1284944/121996229-c6fd8480-cdda-11eb-9c3e-345681b3e641.png)
+![Icon](Sources/Rings/Documentation.docc/Resources/RingsIcon.png)
 
 # Rings ![GitHub](https://img.shields.io/github/license/chenhaiteng/Rings?style=plastic) ![GitHub release (latest by date)](https://img.shields.io/github/v/release/chenhaiteng/Rings) 
 
@@ -8,6 +8,8 @@
 
 It includes following controls, click to see what it looks like:
 
+* **[RingStack](#ringstack)**
+* **[ArcStack](#arcstack)**
 * **[RingText](#ringtext)**
 * **[ClockIndex](#clockindex)**
 * **[HandAiguille](#handaiguille)**
@@ -21,15 +23,15 @@ and following functions are in progress:
 
 ---
 ## Installation:
-Rings is published with Swift Package Manager, you can get more information at ![Swift Package Manager(GitHub)](https://github.com/apple/swift-package-manager), ![Package Manager(swift.org)](https://swift.org/package-manager/), and ![Swift Packages(Apple)](https://developer.apple.com/documentation/swift_packages)
+Rings is published with Swift Package Manager, you can get more information at [Swift Package Manager(GitHub)](https://github.com/apple/swift-package-manager), [Package Manager(swift.org)](https://swift.org/package-manager/), and [Swift Packages(Apple)](https://developer.apple.com/documentation/swift_packages)
 
 ### Install Rings Step by Step
 #### - Add to Xcode(To use this package in your application):
 
 1. File > Swift Packages > Add Package Dependency...
 2. Choose Project you want to add Rings
 3. Paste repository https://github.com/chenhaiteng/Rings.git
-4. Rules > Version: Up to Next Major 0.1.0
+4. Rules > Version: Up to Next Major 0.4.0
 It's can also apply Rules > Branch : main to access latest code.
 If you want try some experimental features, you can also apply Rules > Branch : develop
 
@@ -42,7 +44,7 @@ If you want try some experimental features, you can also apply Rules > Branch :
 #### - Add to SPM package(To use this package in your library/framework):
 ```swift
 dependencies: [
-    .package(name: "Rings", url: "https://github.com/chenhaiteng/Rings.git", from: "0.1.0")
+    .package(name: "Rings", url: "https://github.com/chenhaiteng/Rings.git", from: "0.4.0")
     // To specify branch, use following statement to instead of.
     // .package(name: "Rings", url: "https://github.com/chenhaiteng/Rings.git", .branch("branch_name"))
 ],
@@ -54,50 +56,63 @@ targets: [
 ```
 ---
 
+## RingStack
+
+### What it looks like
+![Demo](Sources/Rings/Documentation.docc/Resources/RingStack.gif)
+
+### [How to use it](Markdown/Rings/RingStack.md)
+
+## ArcStack
+
+### What it looks like
+![Demo](Sources/Rings/Documentation.docc/Resources/ArcStack.gif)
+
+### [How to use it](Markdown/Rings/ArcStack.md)
+
 ## RingText
 
 ### What it looks like
-![RingDemo](Markdown/Rings/RingTextDemo.gif)
+![RingDemo](Sources/Rings/Documentation.docc/Resources/RingTextDemo.gif)
 
-### ![How to use it](Markdown/Rings/RingText.md)
+### [How to use it](Markdown/Rings/RingText.md)
 
 ## ClockIndex
 
 ### What it looks like
-![ClockIndex Demo Classic](https://user-images.githubusercontent.com/1284944/116664495-26d6d200-a9cb-11eb-906c-7ffe659dcfbc.gif)
+![Demo](Sources/Rings/Documentation.docc/Resources/ClockIndex.gif)
 
-<img width="598" alt="earchly_clock_demo" src="https://user-images.githubusercontent.com/1284944/116664737-73baa880-a9cb-11eb-97e1-afcb49dfcfcd.png">
+![Demo](Sources/Rings/Documentation.docc/Resources/EarchlyClock.png)
 
-### ![How to use it](Markdown/Rings/ClockIndex.md)
+### [How to use it](Markdown/Rings/ClockIndex.md)
 
 ## HandAiguille
 
 ### What it looks like:
-![HandAguille](https://user-images.githubusercontent.com/1284944/118101511-47128200-b40a-11eb-870f-90ac2f2a302a.gif)
+![Demo](Sources/Rings/Documentation.docc/Resources/HandAiguille.gif)
 
-### ![How to use it](Markdown/Rings/HandAiguille.md)
+### [How to use it](Markdown/Rings/HandAiguille.md)
 
 ## ArchimedeanSpiralText
 
 ### What it looks like:
-![ArchimedeanSpiralTextDemo](https://user-images.githubusercontent.com/1284944/117950922-3ef10e80-b346-11eb-9da1-50b0f87990a2.gif)
+![Demo](Sources/Rings/Documentation.docc/Resources/ArchimedeanSpiralText.gif)
 
-### ![How to use it](Markdown/Rings/ArchimedeanSpiralText.md)
+### [How to use it](Markdown/Rings/ArchimedeanSpiralText.md)
 
 ## SphericText
 
 ### What it looks like:
-![Spheric Text Demo](https://user-images.githubusercontent.com/1284944/118671827-60f8fe00-b82a-11eb-9f0f-821841867cba.gif)
+![Demo](Sources/Rings/Documentation.docc/Resources/SphericText.gif)
 
-### ![How to use it](Markdown/Rings/SphericText.md)
+### [How to use it](Markdown/Rings/SphericText.md)
 
 ## Knob
 
 ### What it looks like:
-![Knob Demo](https://user-images.githubusercontent.com/1284944/120065810-e2138900-c0a5-11eb-8324-2fe340bb578f.gif)
-
+![Demo](Sources/Rings/Documentation.docc/Resources/Knob.gif)
 
-### ![How to use it](Markdown/Rings/Knob.md)
+### [How to use it](Markdown/Rings/Knob.md)
 
 ---
 # License

diff --git a/Sources/Rings/ArcStack.swift b/Sources/Rings/ArcStack.swift
@@ -177,26 +177,35 @@ fileprivate struct ArcStackComponent<V: View>: View {
 }
 
 @available(iOS 16.0, macOS 13.0, watchOS 9.0, tvOS 16.0, *)
-struct ArcStack<Content: View> : View {
+public struct ArcStack<Content: View> : View {
     let radius: Double
     let anchor: UnitPoint
     let range: ClosedRange<Double>
     let direction: RingLayoutDirection
 
     let content: () -> Content
-    var body: some View {
-        _ArcStack(radius: radius, anchor: anchor, range: range, direction: direction) {
-            content().variadic { children in
-                ForEach(0..<children.endIndex, id: \.self) { index in
-                    ArcStackComponent {
-                        children[index]
+    public var body: some View {
+        GeometryReader { geo in
+            _ArcStack(radius: radius >= 0 ? radius : max(min(geo.width, geo.height), 0.0)/2.0, anchor: anchor, range: range, direction: direction) {
+                content().variadic { children in
+                    ForEach(0..<children.endIndex, id: \.self) { index in
+                        ArcStackComponent {
+                            children[index]
+                        }
                     }
                 }
-            }
-        }
+            }.frame(width: geo.width, height: geo.height, alignment: anchor.alignment).border(.white)
+        }.border(.gray)
     }
-
-    init(radius: Double = 100.0,
+    /// Creates an instance with the given radius, anchor point, arc range, and layout direction.
+    ///
+    /// - Parameters:
+    ///   - radius: The radius of the circle which the subviews are arranged around. If the radius `<` 0.0, or it's not specified, the arc size depends on its frame.
+    ///   - anchor: Specifies the anchor location of the arc. If the anchor is not on the boundary, it layouts views similiar to ``RingStack``
+    ///   - range: The range to plcae views in the arc.
+    ///   - direction: The guide for placing the subviews in this stack.
+    ///   - content: A view builder that creates the content of this stack.
+    public init(radius: Double = -1.0,
          anchor: UnitPoint = .bottom,
          range: ClosedRange<Double> = 0.0...1.0,
          direction: RingLayoutDirection = .none,
@@ -250,7 +259,7 @@ struct ArcStackPreview : View {
                         } label: {
                             Image(systemName: "moon")
                         }
-                    }.animation(.easeInOut(duration: 1.0), value: anchor).frame(width: Self.arcSize, height: Self.arcSize, alignment: .bottom)
+                    }.animation(.easeInOut(duration: 1.0), value: anchor).frame(width: Self.arcSize, height: Self.arcSize)
                 }
                 ZStack(alignment:.leading) {
                     ArcStack(radius: expandRadius, anchor: anchor, range: 0.0...1.0, direction: .none) {
@@ -274,7 +283,7 @@ struct ArcStackPreview : View {
                         } label: {
                             Image(systemName: arcStateImage).resizable().frame(width: 20.0, height: 20.0)
                         }.buttonStyle(.borderedProminent)
-                    }.frame(width: Self.arcSize, height: Self.arcSize, alignment: anchor.alignment)
+                    }.frame(width: Self.arcSize, height: Self.arcSize)
                 }.border(.blue.opacity(0.5))
             }
             Divider()