Giter Club home page Giter Club logo

circularprogress's Introduction

CircularProgress

Circular progress indicator for your macOS app

This package is used in production by the Gifski and HEIC Converter app.

Requirements

  • macOS 10.12+
  • Xcode 10.2+
  • Swift 5+

Install

SwiftPM

.package(url: "https://github.com/sindresorhus/CircularProgress", from: "0.3.0")

Carthage

github "sindresorhus/CircularProgress"

CocoaPods

pod 'CircularProgressMac'

Usage

Also check out the example app in the Xcode project.

Manually set the progress

import Cocoa
import CircularProgress

@NSApplicationMain
final class AppDelegate: NSObject, NSApplicationDelegate {
	@IBOutlet private var window: NSWindow!

	let circularProgress = CircularProgress(size: 200)

	func applicationDidFinishLaunching(_ notification: Notification) {
		window.contentView!.addSubview(circularProgress)

		foo.onUpdate = { progress in
			self.circularProgress.progress = progress
		}
	}
}

Specify a Progress instance

import Cocoa
import CircularProgress

@NSApplicationMain
final class AppDelegate: NSObject, NSApplicationDelegate {
	@IBOutlet private var window: NSWindow!

	let progress = Progress(totalUnitCount: 1)

	func applicationDidFinishLaunching(_ notification: Notification) {
		window.contentView!.addSubview(circularProgress)

		progress?.becomeCurrent(withPendingUnitCount: 1)
		circularProgress.progressInstance = progress
	}
}

Cancel button

If you use the .progress property, you need to opt into the cancel button by setting .isCancellable = true. You can be notified of when the button is clicked by setting the .onCancelled property to a closure.

If you use the .progressInstance property, setting a Progress object that is isCancellable, which is the default, automatically enables the cancel button.

Per default, the cancelled state is indicated by desaturing the current color and reducing the opacity. You can customize this by implementing the .cancelledStateColorHandler callback and returning a color to use for the cancelled state instead. The opacity is not automatically reduced when the callback has been set. To disable the cancelled state visualization entirely, set .visualizeCancelledState to false.

Indeterminate state

Displays a state that indicates that the remaining progress is indeterminate.

Note that the .progress property and .isIndeterminate are not tied together. You'll need to manually set .isIndeterminate = false when progress is being made again.

If you use the .progressInstance property, the isIndeterminate property will automatically be observed. The view will then switch back and forth to the indeterminate state when appropriate.

API

/**
Color of the circular progress view.

Defaults to the user's accent color. For High Sierra and below it uses a fallback color.
*/
@IBInspectable var color: NSColor = .controlAccentColor

/**
Show `✔` instead `100%`.
*/
@IBInspectable var showCheckmarkAtHundredPercent: Bool = true

/**
The progress value in the range `0...1`.

- Note: The value will be clamped to `0...1`.
- Note: Can be set from a background thread.
*/
@IBInspectable var progress: Double = 0

/**
Let a `Progress` instance update the `progress` for you.
*/
var progressInstance: Progress?

/**
Reset the progress back to zero without animating.
*/
func resetProgress() {}

/**
Cancels `Progress` if it's set and prevents further updates.
*/
func cancelProgress() {}

/**
Triggers when the progress was cancelled succesfully.
*/
var onCancelled: (() -> Void)?

/**
Returns whether the progress is finished.
*/
@IBInspectable private(set) var isFinished: Bool

/**
If the progress view is cancellable it shows the cancel button.
*/
@IBInspectable var isCancellable: Bool

/**
Displays the indeterminate state.
*/
@IBInspectable public var isIndeterminate: Bool

/**
Returns whether the progress has been cancelled.
*/
@IBInspectable private(set) var isCancelled: Bool

/**
Determines whether to visualize changing into the cancelled state.
*/
public var visualizeCancelledState: Bool = true

/**
Supply the base color to use for displaying the cancelled state.
*/
public var cancelledStateColorHandler: ((NSColor) -> NSColor)?

init(frame: CGRect) {}
init?(coder: NSCoder) {}

/**
Initialize the progress view with a width/height of the given `size`.
*/
convenience init(size: Double) {}

Related

You might also like my apps.

Maintainers

License

MIT

circularprogress's People

Contributors

boyvanamstel avatar sindresorhus avatar

Stargazers

 avatar

Watchers

 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.