Action Extensions Quick Start Guide
For iOS, tvOS, watchOS and macOS development with Swift and Xcode Sample AppsOpen SourceAction Extensions
Action Extensions provide several useful features to common, built-in Cocoa, Cocoa Touch and Swift data types such as converting UIColor
/NSColor
to/from hex strings (for example #FF0000
), creating UIImage
/NSImage
instances from Base64 encoded strings stored in Data
or NSData
objects and encoding UIImages
/NSImages
as Base64 strings or Data
objects.
The following extensions are available:
- Color Extensions – Extends
UIColor/NSColor
to support the Action Data controls and adds convenience methods for working with colors in aCodable
,Encodable
orDecodable
class. - Data Extensions – Extends
Data
to support the Action Data controls and adds convenience methods for working with data properties in aCodable
,Encodable
orDecodable
class. - Image Extensions – Extends
UIImage/NSImage
to support the Action Data controls and adds convenience methods for working with image properties in aCodable
,Encodable
orDecodable
class. - String Extensions – Extends
String
to support the Action Data controls and adds convenience methods for working withUIImage/NSImage
andUIColor/NSColor
properties in aCodable
,Encodable
orDecodable
class.
Color Extensions
Extends UIColor/NSColor
to support the Action Data controls and adds convenience methods for working with colors in a Codable
, Encodable
or Decodable
class.
The ~= Operator
Sets a UIColor/NSColor
from a hex string in the format rrggbb
or rrggbbaa
where:
rr
– Specifies the red component as a hex value in the range 00 to FF.gg
– Specifies the green component as a hex value in the range 00 to FF.bb
– Specifies the blue component as a hex value in the range 00 to FF.aa
– Specifies the alpha component as a hex value in the range 00 to FF.
The hex string can optionally start with the prefix of #
.
Examples:
// Assign a color from a string in iOS, tvOS or watchOS
let color: UIColor ~= "#FF0000"
// Assign a color from a string in macOS
let color: NSColor ~= "#FF0000"
fromHex Initializer
Initializes a UIColor/NSColor
from a hex string in the format rrggbb
or rrggbbaa
where:
rr
– Specifies the red component as a hex value in the range 00 to FF.gg
– Specifies the green component as a hex value in the range 00 to FF.bb
– Specifies the blue component as a hex value in the range 00 to FF.aa
– Specifies the alpha component as a hex value in the range 00 to FF.
The hex string can optionally start with the prefix of #
.
Examples:
// Assign a color from a string in iOS, tvOS or watchOS
let color = UIColor(fromHex: "#FF0000")
// Assign a color from a string in macOS
let color = NSColor(fromHex: "#FF0000")
toHex Function
Converts a UIColor/NSColor
to a hex string in the format rrggbb
or rrggbbaa
where:
rr
– Specifies the red component as a hex value in the range 00 to FF.gg
– Specifies the green component as a hex value in the range 00 to FF.bb
– Specifies the blue component as a hex value in the range 00 to FF.aa
– Specifies the alpha component as a hex value in the range 00 to FF.
The hex string can optionally start with the prefix of #
.
Examples:
// Assign a color from a string in iOS, tvOS or watchOS
let colorHex = UIColor.red.toHex();
let colorHexShort = UIColor.red.toHex(withPrefix: false, includeAlpha: false);
// Assign a color from a string in macOS
let colorHex = NSColor.red.toHex();
let colorHexShort = NSColor.red.toHex(withPrefix: false, includeAlpha: false);
Data Extensions
Extends Data
to support the Action Data controls and adds convenience methods for working with data properties in a Codable
, Encodable
or Decodable
class.
The ~= Operator
Sets the Data
instance from the given UIImage/NSImage
instance.
Examples:
// Assign data from an image in iOS, tvOS or watchOS
let imageData: Data ~= UIImage(named: "Background.png")
// Assign data from an image in macOS
let imageData: Data ~= NSImage(named: "Background.png")
The uiImage/nsImage Property
Attempts to create a UIImage/NSImage
from the data stored in the current Data
instance. Returns the Image if it can be created else returns nil
.
Examples:
// Assign data from an image in iOS, tvOS or watchOS
let imageData: Data ~= UIImage(named: "Background.png")
if let image = imageData.uiImage {
...
}
// Assign data from an macOS
let imageData: Data ~= NSImage(named: "Background.png")
if let image = imageData.nsImage {
...
}
Image Extensions
Extends UIImage/NSImage
to support the Action Data controls and adds convenience methods for working with image properties in a Codable
, Encodable
or Decodable
class.
The ~= Operator
Sets the UIImage/NSImage
from the given Base 64 encoded String
instance or Sets the UIImage/NSImage
from the given Data
instance.
Examples:
// Assign an image from Base 64 encoded String in iOS, tvOS or watchOS
let imageString = UIImage(named: "Background.png").toString()
let image: UIImage ~= imageString
// Assign an image from Base 64 encoded Data in iOS, tvOS or watchOS
let imageData = UIImage(named: "Background.png").toData()
let image: UIImage ~= imageData
// Assign an image from Base 64 encoded String in macOS
let imageString = NSImage(named: "Background.png").toString()
let image: NSImage ~= imageString
// Assign an image from Base 64 encoded Data in macOS
let imageData = NSImage(named: "Background.png").toData()
let image: NSImage ~= imageData
The toString Function
Converts the UIImage/NSImage
to a String
representation encoded in Base 64.
Examples:
// Assign an image to Base 64 encoded String in iOS, tvOS or watchOS
let imageString = UIImage(named: "Background.png").toString()
// Assign an image to Base 64 encoded String in macOS
let imageString = NSImage(named: "Background.png").toString()
The toData Function
Converts the UIImage/NSImage
to a Data
representation.
Examples:
// Assign an image to Base 64 encoded Data in iOS, tvOS or watchOS
let imageData = UIImage(named: "Background.png").toString()
// Assign an image to Base 64 encoded Data in macOS
let imageData = NSImage(named: "Background.png").toString()
The fromString Initializer
Creates a new UIImage/NSImage
instance from a Base 64 encoded string.
Examples:
// Assign an image from Base 64 encoded String in iOS, tvOS or watchOS
let imageString = UIImage(named: "Background.png").toString()
let image = UIImage(fromString: imageString)
// Assign an image from Base 64 encoded String in macOS
let imageString = NSImage(named: "Background.png")
let image = NSImage(fromString: imageString)
The pngData Property (macOS Only)
Returns the image as data in the png format.
Example:
// Get png Data from image
let data = NSImage(named: "Background.png").pngData
The jpgData Property (macOS Only)
Returns the image as data in the jpeg format.
Example:
// Get jpeg Data from image
let data = NSImage(named: "Background.png").jpgData
String Extensions
Extends String
to support the Action Data controls and adds convenience methods for working with UIImage/NSImage
and UIColor/NSColor
properties in a Codable
, Encodable
or Decodable
class.
The ~= Operator
Sets the String
from the given UIColor/NSColor
where the color is converted to a hex string in the format #rrggbbaa
or sets the String
from the given UIImage/NSImage
where the image is converted to a PNG representation and Base 64 encoded.
Examples:
// Get the hex representation of a color in iOS, tvOS and watchOS.
let hex: String ~= UIColor.white
// Get the Base 64 representation of an image in iOS, tvOS and watchOS.
let hex: String ~= UIImage(named: "Background.png")
// Get the hex representation of a color in macOS.
let hex: String ~= NSColor.white
// Get the Base 64 representation of an image in macOS.
let hex: String ~= NSImage(named: "Background.png")
The uiColor/nsColor Property
Attempts to convert the String
into a UIColor/NSColor
if it is in the format rrggbb
or rrggbbaa
where:
rr
– Specifies the red component as a hex value in the range 00 to FF.gg
– Specifies the green component as a hex value in the range 00 to FF.bb
– Specifies the blue component as a hex value in the range 00 to FF.aa
– Specifies the alpha component as a hex value in the range 00 to FF.
Examples:
// Get the hex representation of a color in iOS, tvOS and watchOS.
let hex: String ~= UIColor.white
let color = hex.uiColor
// Get the hex representation of a color in macOS.
let hex: String ~= NSColor.white
let color = hex.nsColor
The uiImage/nsImage Property
If the String
contains a Base 64 encoded representation of an image it is returns as a UIImage/NSImage
, else nil
is returned.
Examples:
// Get the Base 64 representation of an image in iOS, tvOS and watchOS.
let hex: String ~= UIImage(named: "Background.png")
let image = hex.uiImage
// Get the Base 64 representation of an macOS.
let hex: String ~= NSImage(named: "Background.png")
let image = hex.nsImage
The fromColor Initializer
Initializes a String
instance from a given UIColor/NSColor
stored in the format #rrggbbaa
where:
rr
– Specifies the red component as a hex value in the range 00 to FF.gg
– Specifies the green component as a hex value in the range 00 to FF.bb
– Specifies the blue component as a hex value in the range 00 to FF.aa
– Specifies the alpha component as a hex value in the range 00 to FF.
Examples:
// Get the hex representation of a color in iOS, tvOS and watchOS.
let hex = String(fromColor: UIColor.white)
// Get the hex representation of a color in macOS.
let hex = String(fromColor: NSColor.white)
The fromImage Initializer
Initializes a String
instance from a given UIImage/NSImage
where the image is converted to a PNG representation and Base 64 encoded.
Examples:
// Get the Base 64 representation of an image in iOS, tvOS and watchOS.
let hex = String(fromImage: UIImage(named: "Background.png"))
// Get the Base 64 representation of an image in macOS.
let hex = String(fromImage: NSImage(named: "Background.png"))
The typeName Function
Returns a pretty-printed type name (minus the module name) for the given value.
Example:
// Assigns a pretty type name
let name = String.typeName(of: "<module>")
The height Property
Returns the draw height of the string in the given font constrained to the given width.
Example:
// Get a string height in iOS, tvOS and watchOS
let font = UIFont.systemFont(ofSize: 34, weight: UIFontWeightThin)
let text = "Hello World"
let height = text.height(withConstrainedWidth: 250, font: font)
// Get a string height in macOS
let font = NSFont.systemFont(ofSize: 34, weight: NSFontWeightThin)
let text = "Hello World"
let height = text.height(withConstrainedWidth: 250, font: font)
The width Property
Returns the draw width of the string in the given font constrained to the given height.
Example:
// Get a string height in iOS, tvOS and watchOS
let font = UIFont.systemFont(ofSize: 34, weight: UIFontWeightThin)
let text = "Hello World"
let height = text.width(withConstrainedHeight: 50, font: font)
// Get a string height in macOS
let font = NSFont.systemFont(ofSize: 34, weight: NSFontWeightThin)
let text = "Hello World"
let height = text.width(withConstrainedHeight: 50, font: font)
The bounds Property
Returns the drawing bounds of the string in the given font constrained to the given maximum bounds.
Example:
// Get a string height in iOS, tvOS and watchOS
let font = UIFont.systemFont(ofSize: 34, weight: UIFontWeightThin)
let text = "Hello World"
let bounds = text.bounds(withConstrainedSize: GGSize(width: 250, height: 50), font: font)
// Get a string height in iOS, tvOS and watchOS
let font = NSFont.systemFont(ofSize: 34, weight: NSFontWeightThin)
let text = "Hello World"
let bounds = text.bounds(withConstrainedSize: GGSize(width: 250, height: 50), font: font)