From 035c5d64417e96249d137267de3c72afc676e760 Mon Sep 17 00:00:00 2001 From: Daniel Saidi Date: Thu, 15 Feb 2024 08:40:28 +0100 Subject: [PATCH] Adjust component documentation --- .../Commands/RichTextCommand+ShareMenu.swift | 8 ++++-- .../RichTextViewComponent+Alignment.swift | 14 ++++------ .../RichTextViewComponent+Attributes.swift | 14 +++++----- .../RichTextViewComponent+Colors.swift | 10 +++---- .../RichTextViewComponent+Font.swift | 3 ++- .../RichTextViewComponent+Images.swift | 8 +++--- .../RichTextViewComponent+Indent.swift | 1 - .../RichTextViewComponent+Paragraph.swift | 2 +- .../RichTextViewComponent+Pasting.swift | 20 ++++++++------ .../RichTextViewComponent+Ranges.swift | 2 +- .../RichTextViewComponent+Styles.swift | 8 +++--- .../RichTextViewComponent+Superscript.swift | 10 +++---- .../Component/RichTextViewComponent.swift | 26 ++++++++----------- 13 files changed, 65 insertions(+), 61 deletions(-) diff --git a/Sources/RichTextKit/Commands/RichTextCommand+ShareMenu.swift b/Sources/RichTextKit/Commands/RichTextCommand+ShareMenu.swift index d42e93d6e..f52997a4c 100644 --- a/Sources/RichTextKit/Commands/RichTextCommand+ShareMenu.swift +++ b/Sources/RichTextKit/Commands/RichTextCommand+ShareMenu.swift @@ -95,9 +95,13 @@ public extension RichTextCommand { private extension RichTextCommand.ShareMenu { - var hasExportFormats: Bool { !exportFormats.isEmpty } + var hasExportFormats: Bool { + !exportFormats.isEmpty + } - var hasShareFormats: Bool { !shareFormats.isEmpty } + var hasShareFormats: Bool { + !shareFormats.isEmpty + } } private extension RichTextCommand.ShareMenu { diff --git a/Sources/RichTextKit/Component/RichTextViewComponent+Alignment.swift b/Sources/RichTextKit/Component/RichTextViewComponent+Alignment.swift index cb00a83ab..aebe4535a 100644 --- a/Sources/RichTextKit/Component/RichTextViewComponent+Alignment.swift +++ b/Sources/RichTextKit/Component/RichTextViewComponent+Alignment.swift @@ -3,7 +3,7 @@ // RichTextKit // // Created by Daniel Saidi on 2022-05-29. -// Copyright © 2022-2023 Daniel Saidi. All rights reserved. +// Copyright © 2022-2024 Daniel Saidi. All rights reserved. // import Foundation @@ -16,21 +16,17 @@ import AppKit public extension RichTextViewComponent { - /// Get the rich text alignment at current range. + /// Get the text alignment at the current range. var richTextAlignment: RichTextAlignment? { guard let style = richTextParagraphStyle else { return nil } return RichTextAlignment(style.alignment) } - /// Set the rich text alignment at current range. - /// - /// This function does not use ``RichTextAttributeWriter`` - /// since the text views require affecting text storage. + /// Set the text alignment at the current range. /// /// > Important: This function will affect the next line - /// of text if we grab `richTextParagraphStyle` and make - /// the alignment change to it, instead of creating this - /// brand new paragraph style. + /// if it changes the `richTextParagraphStyle` value, so + /// it instead creates a brand new paragraph style. func setRichTextAlignment( _ alignment: RichTextAlignment ) { diff --git a/Sources/RichTextKit/Component/RichTextViewComponent+Attributes.swift b/Sources/RichTextKit/Component/RichTextViewComponent+Attributes.swift index e9c9df5a6..421ca6d6f 100644 --- a/Sources/RichTextKit/Component/RichTextViewComponent+Attributes.swift +++ b/Sources/RichTextKit/Component/RichTextViewComponent+Attributes.swift @@ -3,14 +3,14 @@ // RichTextKit // // Created by Daniel Saidi on 2022-05-29. -// Copyright © 2022-2023 Daniel Saidi. All rights reserved. +// Copyright © 2022-2024 Daniel Saidi. All rights reserved. // import Foundation public extension RichTextViewComponent { - /// Get all rich text attributes at current range. + /// Get all attributes at the current range. var richTextAttributes: RichTextAttributes { if hasSelectedRange { return richTextAttributes(at: selectedRange) @@ -25,14 +25,14 @@ public extension RichTextViewComponent { #endif } - /// Get a certain rich text attribute at current range. + /// Get a certain attribute at the current range. func richTextAttribute( _ attribute: RichTextAttribute ) -> Value? { richTextAttributes[attribute] as? Value } - /// Set a certain rich text attribute at current range. + /// Set a certain attribute at the current range. func setRichTextAttribute( _ attribute: RichTextAttribute, to value: Any @@ -44,8 +44,10 @@ public extension RichTextViewComponent { } } - /// Set certain attributes at current range. - func setRichTextAttributes(_ attributes: RichTextAttributes) { + /// Set certain attributes at the current range. + func setRichTextAttributes( + _ attributes: RichTextAttributes + ) { attributes.forEach { attribute, value in setRichTextAttribute(attribute, to: value) } diff --git a/Sources/RichTextKit/Component/RichTextViewComponent+Colors.swift b/Sources/RichTextKit/Component/RichTextViewComponent+Colors.swift index f983782a8..7a51dc8bf 100644 --- a/Sources/RichTextKit/Component/RichTextViewComponent+Colors.swift +++ b/Sources/RichTextKit/Component/RichTextViewComponent+Colors.swift @@ -3,14 +3,14 @@ // RichTextKit // // Created by Daniel Saidi on 2022-05-30. -// Copyright © 2022-2023 Daniel Saidi. All rights reserved. +// Copyright © 2022-2024 Daniel Saidi. All rights reserved. // import Foundation public extension RichTextViewComponent { - /// Get a certain rich text color at current range. + /// Get a certain color at the current range. func richTextColor( _ color: RichTextColor ) -> ColorRepresentable? { @@ -18,7 +18,7 @@ public extension RichTextViewComponent { return richTextAttribute(attribute) } - /// Get a certain rich text color at a certain range. + /// Get a certain color at a certain range. func richTextColor( _ color: RichTextColor, at range: NSRange @@ -27,7 +27,7 @@ public extension RichTextViewComponent { return richTextAttribute(attribute, at: range) } - /// Set a certain rich text color at current range. + /// Set a certain color at the current range. func setRichTextColor( _ color: RichTextColor, to val: ColorRepresentable @@ -37,7 +37,7 @@ public extension RichTextViewComponent { setRichTextAttribute(attribute, to: val) } - /// Set a certain rich text color at a certain range. + /// Set a certain colors at a certain range. func setRichTextColor( _ color: RichTextColor, to val: ColorRepresentable, diff --git a/Sources/RichTextKit/Component/RichTextViewComponent+Font.swift b/Sources/RichTextKit/Component/RichTextViewComponent+Font.swift index 249567243..8a39a6d38 100644 --- a/Sources/RichTextKit/Component/RichTextViewComponent+Font.swift +++ b/Sources/RichTextKit/Component/RichTextViewComponent+Font.swift @@ -7,7 +7,8 @@ // /// These functions may seem complicated, but it is the only -/// way that seems to work correctly, so far. +/// way that seems to work correctly, so far. Perhaps it can +/// be simplified in 1.0, after removing all deprecated code. /// /// I previously grabbed the `typingAttributes` and took the /// `.font` attribute from it, then took its `fontDescriptor` diff --git a/Sources/RichTextKit/Component/RichTextViewComponent+Images.swift b/Sources/RichTextKit/Component/RichTextViewComponent+Images.swift index 851e9d1ab..b70b3d8f9 100644 --- a/Sources/RichTextKit/Component/RichTextViewComponent+Images.swift +++ b/Sources/RichTextKit/Component/RichTextViewComponent+Images.swift @@ -3,7 +3,7 @@ // RichTextKit // // Created by Daniel Saidi on 2022-06-05. -// Copyright © 2022-2023 Daniel Saidi. All rights reserved. +// Copyright © 2022-2024 Daniel Saidi. All rights reserved. // import Foundation @@ -18,7 +18,7 @@ import AppKit public extension RichTextViewComponent { - /// Get the attachment max size for a certain image. + /// Get the max image attachment size. var imageAttachmentMaxSize: CGSize { let maxSize = imageConfiguration.maxImageSize let insetX = 2 * textContentInset.width @@ -40,7 +40,9 @@ public extension RichTextViewComponent { } /// Get the attachment size for a certain image. - func attachmentSize(for image: ImageRepresentable) -> CGSize { + func attachmentSize( + for image: ImageRepresentable + ) -> CGSize { attributedString.attachmentSize( for: image, maxSize: imageAttachmentMaxSize diff --git a/Sources/RichTextKit/Component/RichTextViewComponent+Indent.swift b/Sources/RichTextKit/Component/RichTextViewComponent+Indent.swift index fdb81f854..819f58871 100644 --- a/Sources/RichTextKit/Component/RichTextViewComponent+Indent.swift +++ b/Sources/RichTextKit/Component/RichTextViewComponent+Indent.swift @@ -27,7 +27,6 @@ public extension RichTextViewComponent { /// /// Unlike some other attributes, this attribute applies /// to the entire paragraph, not just the selected range. - /// It therefore needs special treatment. func stepRichTextIndent( points: CGFloat ) { diff --git a/Sources/RichTextKit/Component/RichTextViewComponent+Paragraph.swift b/Sources/RichTextKit/Component/RichTextViewComponent+Paragraph.swift index 2ec5a5b4e..f65ad1523 100644 --- a/Sources/RichTextKit/Component/RichTextViewComponent+Paragraph.swift +++ b/Sources/RichTextKit/Component/RichTextViewComponent+Paragraph.swift @@ -18,7 +18,7 @@ import AppKit public extension RichTextViewComponent { - /// Get the rich text paragraph style at current range. + /// Get the paragraph style at the current range. var richTextParagraphStyle: NSMutableParagraphStyle? { richTextAttribute(.paragraphStyle) } diff --git a/Sources/RichTextKit/Component/RichTextViewComponent+Pasting.swift b/Sources/RichTextKit/Component/RichTextViewComponent+Pasting.swift index 17b80d3ae..c5fff1b16 100644 --- a/Sources/RichTextKit/Component/RichTextViewComponent+Pasting.swift +++ b/Sources/RichTextKit/Component/RichTextViewComponent+Pasting.swift @@ -3,7 +3,7 @@ // RichTextKit // // Created by Daniel Saidi on 2022-06-05. -// Copyright © 2022-2023 Daniel Saidi. All rights reserved. +// Copyright © 2022-2024 Daniel Saidi. All rights reserved. // import Foundation @@ -19,12 +19,13 @@ import AppKit public extension RichTextViewComponent { /** - Paste an image into the text view, at a certain index. + Paste an image into the rich text, at a certain index. - For now, pasting will automatically insert the image as - a compressed jpeg. We should expand this to allow us to - define format, compression etc. For now, it's hardcoded - and a future TODO. + Pasting images only works on iOS, tvOS and macOS. Other + platform will trigger an assertion failure. + + > Todo: This automatically inserts images as compressed + jpeg. We should make it more configurable. - Parameters: - image: The image to paste. @@ -47,9 +48,12 @@ public extension RichTextViewComponent { /** Paste images into the text view, at a certain index. + + This will automatically insert an image as a compressed + jpeg. We should make it more configurable. - Pasting images only works on iOS, tvOS and macOS. Other - platform will trigger an assertion failure. + > Todo: This automatically inserts images as compressed + jpeg. We should make it more configurable. - Parameters: - images: The images to paste. diff --git a/Sources/RichTextKit/Component/RichTextViewComponent+Ranges.swift b/Sources/RichTextKit/Component/RichTextViewComponent+Ranges.swift index 57f3aadb3..ae7fb0601 100644 --- a/Sources/RichTextKit/Component/RichTextViewComponent+Ranges.swift +++ b/Sources/RichTextKit/Component/RichTextViewComponent+Ranges.swift @@ -2,7 +2,7 @@ // RichTextViewComponent+Ranges.swift // RichTextKit // -// Created by Daniel Saidi on 2024-02-14. +// Created by Dominik Bucher // import Foundation diff --git a/Sources/RichTextKit/Component/RichTextViewComponent+Styles.swift b/Sources/RichTextKit/Component/RichTextViewComponent+Styles.swift index fae2ba33a..5dd59a773 100644 --- a/Sources/RichTextKit/Component/RichTextViewComponent+Styles.swift +++ b/Sources/RichTextKit/Component/RichTextViewComponent+Styles.swift @@ -3,14 +3,14 @@ // RichTextKit // // Created by Daniel Saidi on 2022-05-29. -// Copyright © 2022-2023 Daniel Saidi. All rights reserved. +// Copyright © 2022-2024 Daniel Saidi. All rights reserved. // import Foundation public extension RichTextViewComponent { - /// Get all rich text styles at current range. + /// Get all styles at the current range. var richTextStyles: [RichTextStyle] { let attributes = richTextAttributes let traits = richTextFont?.fontDescriptor.symbolicTraits @@ -25,7 +25,7 @@ public extension RichTextViewComponent { richTextStyles.contains(style) } - /// Set a certain rich text style at current range. + /// Set a certain style at the current range. func setRichTextStyle( _ style: RichTextStyle, to newValue: Bool @@ -45,7 +45,7 @@ public extension RichTextViewComponent { } } - /// Set a certain rich text style at current range. + /// Toggle a certain style at the current range. func toggleRichTextStyle( _ style: RichTextStyle ) { diff --git a/Sources/RichTextKit/Component/RichTextViewComponent+Superscript.swift b/Sources/RichTextKit/Component/RichTextViewComponent+Superscript.swift index 2c880e5f0..ff8118d1a 100644 --- a/Sources/RichTextKit/Component/RichTextViewComponent+Superscript.swift +++ b/Sources/RichTextKit/Component/RichTextViewComponent+Superscript.swift @@ -2,15 +2,15 @@ // RichTextViewComponent+Color.swift // RichTextKit // -// Created by Daniel Saidi on 2022-05-30. -// Copyright © 2022-2023 Daniel Saidi. All rights reserved. +// Created by Daniel Saidi on 2024-02-14. +// Copyright © 2024 Daniel Saidi. All rights reserved. // import Foundation public extension RichTextViewComponent { - /// Get the rich text superscript level at current range. + /// Get the superscript level at the current range. var richTextSuperscriptLevel: Int? { #if macOS richTextAttribute(.superscript) @@ -19,7 +19,7 @@ public extension RichTextViewComponent { #endif } - /// Set the rich text superscript level at current range. + /// Set the superscript level at the current range. func setRichTextSuperscriptLevel(to val: Int) { #if macOS setRichTextAttribute(.superscript, to: val) @@ -28,7 +28,7 @@ public extension RichTextViewComponent { #endif } - /// Step the rich text font size at current range. + /// Step the superscript level at the current range. func stepRichTextSuperscriptLevel(points: Int) { let currentSize = richTextSuperscriptLevel ?? 0 let newSize = currentSize + points diff --git a/Sources/RichTextKit/Component/RichTextViewComponent.swift b/Sources/RichTextKit/Component/RichTextViewComponent.swift index 1f3b4d5a1..c8f22bd55 100644 --- a/Sources/RichTextKit/Component/RichTextViewComponent.swift +++ b/Sources/RichTextKit/Component/RichTextViewComponent.swift @@ -3,7 +3,7 @@ // RichTextKit // // Created by Daniel Saidi on 2022-05-22. -// Copyright © 2022-2023 Daniel Saidi. All rights reserved. +// Copyright © 2022-2024 Daniel Saidi. All rights reserved. // import CoreGraphics @@ -17,18 +17,18 @@ import AppKit /** - This protocol defines a platform-agnostic api that's shared - by the UIKit and AppKit ``RichTextView`` components. + This protocol provides a common interface for the UIKit and + AppKit ``RichTextView`` components. - By implementing and using this protocol in the library, the - library doesn't have to do a bunch of `#if` checks. + By implementing this protocol, the library does not have to + do a bunch of `#if` platform checks within the code. + + This component can read and write many different attributes + from and to its rich text, using the underlying features of + ``RichTextAttributeReader`` and ``RichTextAttributeWriter``. The protocol implements and extends many other protocols to provide more features for components with more capabilities. - - The protocol for instance extends ``RichTextAttributeReader`` - and ``RichTextAttributeWriter`` and adds new functions that - don't require a `range`, since it can use the current range. */ public protocol RichTextViewComponent: AnyObject, RichTextPresenter, @@ -52,9 +52,6 @@ public protocol RichTextViewComponent: AnyObject, var isFirstResponder: Bool { get } /// The text view's layout manager, if any. - /// - /// This is optional and renamed since UIKit will have a - /// non-otional manager and AppKit an optional one. var layoutManagerWrapper: NSLayoutManager? { get } /// The text view's mutable attributed string, if any. @@ -64,9 +61,6 @@ public protocol RichTextViewComponent: AnyObject, var textContentInset: CGSize { get set } /// The text view's text storage, if any. - /// - /// This is optional and renamed since UIKit will have a - /// non-otional storage and AppKit an optional one. var textStorageWrapper: NSTextStorage? { get } /// The text view current typing attributes. @@ -81,6 +75,7 @@ public protocol RichTextViewComponent: AnyObject, format: RichTextDataFormat ) + // MARK: - Functions /// Show an alert with a title, message and button text. @@ -105,6 +100,7 @@ public protocol RichTextViewComponent: AnyObject, func undoLatestChange() } + // MARK: - Public Extension public extension RichTextViewComponent {