GitHub - malcommac/SwiftRichString: Elegant & painless Attributed Strings in...
source link: https://github.com/malcommac/SwiftRichString
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
README.md
★★ Star me to follow the project! ★★
Created by Daniele Margutti - danielemargutti.com
SwiftRichString is a lightweight library which allows to create and manipulate attributed strings easily both in iOS, macOS, tvOS and even watchOS. It provides convenient way to store styles you can reuse in your app's UI lements, allows complex tag-based strings rendering and also includes integration with Interface Builder.
If you manipulate NSAttributedString
in Swift, SwiftRichString allows you to keep your code manteniable, readable and easy to evolve.
Features Highlights
Want to know what SwiftRichString can do in your app? Lets take a look to these feature highlights!
1. Easy Styling
The main concept behind this lib is the Style
: a style is just a collection of text attributes you can apply to a string. The following example show how to create a style an produce an attributed string with it:
let style = Style { $0.font = SystemFonts.AmericanTypewriter.font(size: 25) // just pass a string, one of the SystemFonts or an UIFont $0.color = "#0433FF" // you can use UIColor or HEX string! $0.underline = (.patternDot, UIColor.red) $0.alignment = .center } let attributedText = "Hello World!".set(style: style) // et voilà!
2. Global Styles & Interface Builder Integration
Styles can be also registered globally and reused in your app.
Just define your own style and register using Styles.register()
function:
let myStyle = Style { // define style's attributes... } Styles.register("MyStyle", style: style)
Now you can reuse it everything in your app; SwiftRichString exposes a styleName
property for the most common text containers and you can set it directly in Interface Builder:
3. Complex Rendering with tag-based strings
SwiftRichString allows you to render complex strings by parsing text's tags: each style will be identified by an unique name (used inside the tag) and you can create a StyleGroup
which allows you to encapsulate all of them and reuse as you need (clearly you can register it globally).
// Create your own styles let normal = Style { $0.font = SystemFonts.Helvetica_Light.font(size: 15) } let bold = Style { $0.font = SystemFonts.Helvetica_Bold.font(size: 20) $0.color = UIColor.red $0.backColor = UIColor.yellow } let italic = normal.byAdding { $0.traitVariants = .italic } // Create a group which contains your style, each identified by a tag. let myGroup = StyleGroup(base: normal, ["bold": bold, "italic": italic]) // Use tags in your plain string let str = "Hello <bold>Daniele!</bold>. You're ready to <italic>play with us!</italic>" self.label?.attributedText = str.set(style: myGroup)
That's the result!
--
Other Libraries You May Like
I'm also working on several other projects you may like. Take a look below:
Library Description SwiftDate The best way to manage date/timezones in Swift Hydra Write better async code: async/await & promises FlowKit A new declarative approach to table/collection managment. Forget datasource & delegates. SwiftRichString Elegant & Painless NSAttributedString in Swift SwiftLocation Efficient location manager SwiftMsgPack Fast/efficient msgPack encoder/decoder
--
Documentation
Are you using SwiftRichString 1.x in your project? Don't miss to take a look at Migration section of the documentation. You can still use the 1.x release by using tagged version 1.1.0.
Table Of Contents
Full changelog is available in CHANGELOG.md file.
- Versions (1.x, 2.x and old Swift 3.x branch)
- Introduction to
Style
,StyleGroup
&StyleRegEx
- The
StyleManager
- Assign style using Interface Builder
- All properties of
Style
Other info:
Versions
SwiftRichString 2.x branch (current). The latest version is 2.0.1. SwiftRichString 1.x branch (supported). Use 1.1.0 tag. Its compatible with Swift 4.x. Swift 3.x (no longer mantained). Use 0.9.1 release.Introduction to Style
, StyleGroup
, StyleRegEx
Introduction
Style
: apply style to strings or attributed strings
StyleGroup
: Apply styles for tag-based complex string
The following code defines a group where:
we have defined a base style. Base style is the style applied to the entire string and can be used to provide a base ground of styles you want to apply to the string. we have defined two other styles namedh1
and h2
; these styles are applied to the source string when parser encounter some text enclosed by these tags.
StyleRegEx
: Apply styles via regular expressions
String & Attributed String concatenation
You can also use +
operator to add a style to a plain or attributed string:
Apply styles to String
& Attributed String
Strings Instance Methods
set(style: String, range: NSRange? = nil)
: apply a globally registered style to the string (or a substring) by producing an attributed string.
set(styles: [String], range: NSRange? = nil)
: apply an ordered sequence of globally registered styles to the string (or a substring) by producing an attributed string.
set(style: StyleProtocol, range: NSRange? = nil)
: apply an instance of Style
or StyleGroup
(to render tag-based text) to the string (or a substring) by producting an attributed string.
set(styles: [StyleProtocol], range: NSRange? = nil)
: apply a sequence of Style
/StyleGroup
instance in order to produce a single attributes collection which will be applied to the string (or substring) to produce an attributed string.
AttributedString Instance Methods
Similar methods are also available to attributed strings.
There are three categories of methods:
set
methods replace any existing attributes already set on target.
add
add attributes defined by style/styles list to the target
remove
remove attributes defined from the receiver string.
add(style: String, range: NSRange? = nil)
: add to existing style of string/substring a globally registered style with given name.
add(styles: [String], range: NSRange? = nil)
: add to the existing style of string/substring a style which is the sum of ordered sequences of globally registered styles with given names.
add(style: StyleProtocol, range: NSRange? = nil)
: append passed style instance to string/substring by altering the receiver attributed string.
add(styles: [StyleProtocol], range: NSRange? = nil)
: append passed styles ordered sequence to string/substring by altering the receiver attributed string.
set(style: String, range: NSRange? = nil)
: replace any existing style inside string/substring with the attributes defined inside the globally registered style with given name.
set(styles: [String], range: NSRange? = nil)
: replace any existing style inside string/substring with the attributes merge of the ordered sequences of globally registered style with given names.
set(style: StyleProtocol, range: NSRange? = nil)
: replace any existing style inside string/substring with the attributes of the passed style instance.
set(styles: [StyleProtocol], range: NSRange? = nil)
: replace any existing style inside string/substring with the attributes of the passed ordered sequence of styles.
removeAttributes(_ keys: [NSAttributedStringKey], range: NSRange)
: remove attributes specified by passed keys from string/substring.
remove(_ style: StyleProtocol)
: remove attributes specified by the style from string/substring.
Fonts & Colors in Style
For Color this mean you can create valid color instance from HEX strings:
Clearly you can still pass instances of both colors/fonts.
Derivating a Style
The StyleManager
Register globally available styles
Now you can use it everywhere inside the app; you can apply it to a text just using its name:
or you can assign body
string to the styledText
via Interface Builder designable property.
Defer style creation on demand
Assign style using Interface Builder
SwiftRichString can be used also via Interface Builder.
UILabel
UITextView
UITextField
has three additional properties:
styleName: String
(available via IB): you can set it to render the text already set via Interface Builder with a style registered globally before the parent view of the UI control is loaded.
style: StyleProtocol
: you can set it to render the text of the control with an instance of style instance.
styledText: String
: use this property, instead of attributedText
to set a new text for the control and render it with already set style. You can continue to use attributedText
and set the value using .set()
functions of String
/AttributedString
.
Assigned style can be a Style
, StyleGroup
or StyleRegEx
:
Style
the entire text of the control is set with the attributes defined by the style.
if style is a StyleGroup
a base attribute is set (if base
is valid) and other attributes are applied once each tag is found.
if style is a StyleRegEx
a base attribute is set (if base
is valid) and the attribute is applied only for matches of the specified pattern.
Otherwise you can set values manually:
Properties available via Style
class
The following properties are available:
PROPERTY
TYPE
DESCRIPTION
size
CGFloat
font size in points
font
FontConvertible
font used in text
color
ColorConvertible
foreground color of the text
backColor
ColorConvertible
background color of the text
underline
(NSUnderlineStyle?,ColorConvertible?)
underline style and color (if color is nil foreground is used)
strikethrough
(NSUnderlineStyle?,ColorConvertible?)
strikethrough style and color (if color is nil foreground is used)
baselineOffset
Float
character’s offset from the baseline, in point
paragraph
NSMutableParagraphStyle
paragraph attributes
lineSpacing
CGFloat
distance in points between the bottom of one line fragment and the top of the next
paragraphSpacingBefore
CGFloat
distance between the paragraph’s top and the beginning of its text content
paragraphSpacingAfter
CGFloat
space (measured in points) added at the end of the paragraph
alignment
NSTextAlignment
text alignment of the receiver
firstLineHeadIndent
CGFloat
distance (in points) from the leading margin of a text container to the beginning of the paragraph’s first line.
headIndent
CGFloat
The distance (in points) from the leading margin of a text container to the beginning of lines other than the first.
tailIndent
CGFloat
this value is the distance from the leading margin, If 0 or negative, it’s the distance from the trailing margin.
lineBreakMode
LineBreak
mode that should be used to break lines
minimumLineHeight
CGFloat
minimum height in points that any line in the receiver will occupy regardless of the font size or size of any attached graphic
maximumLineHeight
CGFloat
maximum height in points that any line in the receiver will occupy regardless of the font size or size of any attached graphic
baseWritingDirection
NSWritingDirection
initial writing direction used to determine the actual writing direction for text
lineHeightMultiple
CGFloat
natural line height of the receiver is multiplied by this factor (if positive) before being constrained by minimum and maximum line height
hyphenationFactor
Float
threshold controlling when hyphenation is attempted
ligatures
Ligatures
Ligatures cause specific character combinations to be rendered using a single custom glyph that corresponds to those characters
speaksPunctuation
Bool
Enable spoken of all punctuation in the text
speakingLanguage
String
The language to use when speaking a string (value is a BCP 47 language code string).
speakingPitch
Double
Pitch to apply to spoken content
speakingPronunciation
String
shouldQueueSpeechAnnouncement
Bool
Spoken text is queued behind, or interrupts, existing spoken content
headingLevel
HeadingLevel
Specify the heading level of the text
numberCase
NumberCase
"Configuration for the number case, also known as ""figure style"""
numberSpacing
NumberSpacing
"Configuration for number spacing, also known as ""figure spacing"""
fractions
Fractions
Configuration for displyaing a fraction
superscript
Bool
Superscript (superior) glpyh variants are used, as in footnotes_.
subscript
Bool
Subscript (inferior) glyph variants are used: v_.
ordinals
Bool
Ordinal glyph variants are used, as in the common typesetting of 4th.
scientificInferiors
Bool
Scientific inferior glyph variants are used: H_O
smallCaps
Set<SmallCaps>
Configure small caps behavior.
stylisticAlternates
StylisticAlternates
Different stylistic alternates available for customizing a font.
contextualAlternates
ContextualAlternates
Different contextual alternates available for customizing a font.
kerning
Kerning
Tracking to apply.
traitVariants
TraitVariant
Describe trait variants to apply to the font
Migration from 1.x
AStyleProtocol
is now a common entry point for every style definition; both Style
and StyleGroup
are conform to this protocol which is the central repository to make actions on text (in 1.x String
and AttributedString
act directly to parse text).
Style
some properties of the class has a different (but quite equal) name, changed to better reflect the purpose of the attribute. Some attributes like underline
or striketought
are now tuple of elements instead of different properties.
Style
are now anonymous; you don't need to assign a name to a style; only if you need to parse tag-based text you need to group used styles in a StyleGroup
instance where you define the name/id of each tag.
There is not any parseTag
function; just pass the StyleGroup
as parameter to render a text and the tag-based parsing will be done automatically.
There is not any default style; StyleGroup
implements a base
style used to render common attributes of your text. You can also use Styles
to register globally available StyleProtocol
instances and use them in your app.
In order to simplify our APIs some init methods of Style
are now removed. You should not miss them, but let me know via PR in case.
Requirements
SwiftRichString is compatible with Swift 4.x. All Apple platforms are supported:
iOS 8.0+ macOS 10.10+ watchOS 2.0+ tvOS 11.0+Installation
Install via CocoaPods
CocoaPods is a dependency manager for Objective-C, which automates and simplifies the process of using 3rd-party libraries like SwiftRichString in your projects. You can install it with the following command:
$ sudo gem install cocoapods
CocoaPods 1.0.1+ is required to build SwiftRichString.
Install via Podfile
To integrate SwiftRichString into your Xcode project using CocoaPods, specify it in your Podfile
:
source 'https://github.com/CocoaPods/Specs.git' platform :ios, '8.0' target 'TargetName' do use_frameworks! pod 'SwiftRichString' end
Then, run the following command:
$ pod install
Carthage
Carthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks.
You can install Carthage with Homebrew using the following command:
$ brew update $ brew install carthage
To integrate SwiftRichString into your Xcode project using Carthage, specify it in your Cartfile
:
github "malcommac/SwiftRichString"
Run carthage
to build the framework and drag the built SwiftRichString.framework
into your Xcode project.
Contributing
Issues and pull requests are welcome! Contributors are expected to abide by the Contributor Covenant Code of Conduct.
Copyright
SwiftRichString is available under the MIT license. See the LICENSE file for more info.
Daniele Margutti: [email protected], @danielemargutti
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK