Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/Boris-Em/BEMCheckBox

Tasteful Checkbox for iOS. (Check box)
https://github.com/Boris-Em/BEMCheckBox

checkbox checkmark ios ui

Last synced: about 1 month ago
JSON representation

Tasteful Checkbox for iOS. (Check box)

Host: GitHub
URL: https://github.com/Boris-Em/BEMCheckBox
Owner: Boris-Em
License: mit
Created: 2015-09-03T05:58:18.000Z (over 9 years ago)
Default Branch: master
Last Pushed: 2023-08-03T23:24:15.000Z (over 1 year ago)
Last Synced: 2024-12-02T19:42:48.475Z (about 1 month ago)
Topics: checkbox, checkmark, ios, ui
Language: Swift
Homepage:
Size: 3.41 MB
Stars: 2,628
Watchers: 48
Forks: 288
Open Issues: 26
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE

Awesome Lists containing this project

awesome-ios-star - BEMCheckBox - Tasteful Checkbox for iOS. (Check box) (UI / Button)
Awesome-iOS - BEMCheckBox - Beautiful, highly customizable, animated checkboxes for iOS. (UI Components)
awesome-ios - BEMCheckBox - Tasteful Checkbox for iOS. (Check box) (UI / Button)
awesome - BEMCheckBox - 一个可以很容易地为iOS创建漂亮的、高度可定制的动画复选框。 (OOM-Leaks-Crash / CheckBox)

README

# BEMCheckBox
[![Build Status](https://travis-ci.org/Boris-Em/BEMCheckBox.svg)](https://travis-ci.org/Boris-Em/BEMCheckBox)
[![Version](https://img.shields.io/cocoapods/v/BEMCheckBox.svg?style=flat)](http://cocoadocs.org/docsets/BEMCheckBox)
[![License](https://img.shields.io/cocoapods/l/BEMCheckBox.svg?style=flat)](http://cocoadocs.org/docsets/BEMCheckBox)
[![Platform](https://img.shields.io/cocoapods/p/BEMCheckBox.svg?style=flat)](http://cocoadocs.org/docsets/BEMCheckBox)
[![Carthage Compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)

**BEMCheckBox** is an open source library making it easy to create beautiful, highly customizable, animated checkboxes for iOS.

## Table of Contents

* [**Project Details**](#project-details)
* [Requirements](#requirements)
* [License](#license)
* [Support](#support)
* [Sample App](#sample-app)
* [React Native](#react-native)
* [NativeScript](#nativescript)
* [Xamarin](#xamarin)
* [**Getting Started**](#getting-started)
* [Installation](#installation)
* [Setup](#setup)
* [**Documentation**](#documentation)
* [Enabling / Disabling the Checkbox](#enabling--disabling-the-checkbox)
* [Reloading](#reloading)
* [Group / Radio Button Functionality](#group--radio-button-functionality)
* [Delegate](#delegate)
* [Customization](#customization)

## Project Details
Learn more about the **BEMCheckBox** project, licensing, support etc.

### Requirements
- Requires iOS 7 or later. The sample project is optimized for iOS 9.
- Requires Automatic Reference Counting (ARC).
- Optimized for ARM64 Architecture.

### License
See the [License](https://github.com/Boris-Em/BEMCheckBox/blob/master/LICENSE). You are free to make changes and use this in either personal or commercial projects. Attribution is not required, but highly appreciated. A little "Thanks!" (or something to that affect) is always welcome. If you use **BEMCheckBox** in your app, please let us know!

### Support
[![Gitter chat](https://badges.gitter.im/Boris-Em/BEMCheckBox.png)](https://gitter.im/Boris-Em/BEMCheckBox)
Join us on [Gitter](https://gitter.im/Boris-Em/BEMCheckBox) if you need any help or want to talk about the project.

### Sample App
The iOS Sample App included with this project demonstrates one way to correctly setup and use **BEMCheckBox**. It also offers the possibility to customize the checkbox within the app.

### React Native
**BEMCheckBox** can be used with React Native: [React-Native-BEMCheckBox](https://github.com/torifat/react-native-bem-check-box)

### NativeScript
**BEMCheckBox** can be used with NativeScript: [NativeScript-BEMCheckBox](https://github.com/nstudio/nativescript-checkbox)

### Xamarin
**BEMCheckBox** can also be used with Xamarin: [XPlugins.iOS.BEMCheckBox](https://github.com/saturdaymp/XPlugins.iOS.BEMCheckBox)

## Getting Started
It only takes a few simple steps to install and setup **BEMCheckBox** to your project.

### Installation

#### Swift Package Manager
Add `https://github.com/Boris-Em/BEMCheckBox` as a dependency to your Package.swift file or select `File -> Swift Packages -> Add Package Dependency...` in Xcode.

#### CocoaPods
The easiest way to install **BEMCheckBox** is to use CocoaPods. To do so, simply add the following line to your `Podfile`:

pod 'BEMCheckBox'

#### Carthage
[Carthage](https://github.com/Carthage/Carthage) is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks.

Run `carthage update` after adding **BEMCheckBox** to your Cartfile to build the framework. Drag the built `BEMCheckBox.framework` into your Xcode project.

#### Manually
Finally, you can install **BEMCheckBox** manually. Simply drag and drop the *Classes* folder into your Xcode project. When you do so, make sure to check the "*Copy items into destination group's folder*" box.

### Setup
Setting up **BEMCheckBox** to your project couldn't be more simple. It is modeled after `UISwitch`. In fact, you could just replace instances of `UISwitch` by **BEMCheckBox** in your project!
Here are the steps to follow to get everything up and running:

1. Import `"BEMCheckBox.h"` to the header of your view controller:

```objective-c
#import "BEMCheckBox.h"
```

2. **BEMCheckBox** can either be initialized programatically (through code) or with Interface Builder (Storyboard file). Use the method that makes the most sense for your project.

**Programmatical Initialization**
Just add the following code to your implementation (usually in the `viewDidLoad` method of your View Controller).

```objective-c
BEMCheckBox *myCheckBox = [[BEMCheckBox alloc] initWithFrame:CGRectMake(0, 0, 50, 50)];
[self.view addSubview:myCheckBox];
```

**Interface Builder Initialization**
1 - Drag a `UIView` to your `UIViewController`.
2 - Change the class of the new `UIView` to `BEMCheckBox`.
3 - Select the `BEMCheckBox` and open the Attributes Inspector. Most of the customizable properties can easily be set from the Attributes Inspector. The Sample App demonstrates this capability.

## Documentation
All of the methods and properties available for **BEMCheckBox** are documented below.

### Enabling / Disabling the Checkbox
##### The `on` Property
Just like `UISwitch`, **BEMCheckBox** provides the boolean property `on` that allows you to retrieve and set (without animation) a value determining wether the BEMCheckBox object is `on` or `off`. Defaults to `NO`.
Example usage:
```objective-c
self.myCheckBox.on = YES;
```
##### `setOn:animated:`
Just like `UISwitch`, **BEMCheckBox** provides an instance method `setOn:animated:` that sets the state of the checkbox to On or Off, optionally animating the transition.
Example usage:
```objective-c
[self.myCheckBox setOn:YES animated:YES];
```

### Reloading
The instance method `reload` lets you redraw the entire checkbox, keeping the current `on` value.
Example usage:
```objective-c
[self.myCheckBox reload]
```

### Group / Radio Button Functionality
**BEMCheckBox**es can easily be grouped together to form radio button functionality. This will automatically manage the state of each checkbox in the group, so that only one is selected at a time, and can optionally require that the group has a selection at all times.

```objective-c
self.group = [BEMCheckBoxGroup groupWithCheckBoxes:@[self.checkBox1, self.checkBox2, self.checkBox3]];
self.group.selectedCheckBox = self.checkBox2; // Optionally set which checkbox is pre-selected
self.group.mustHaveSelection = YES; // Define if the group must always have a selection
```

To see which checkbox is selected in that group, just ask for it:
```objective-c
BEMCheckBox *selection = self.group.selectedCheckBox;
```

To manually update the selection for a group, just set it:
```objective-c
self.group.selectedCheckBox = self.checkBox1;
```

### Delegate
**BEMCheckBox** uses a delegate to receive check box events. The delegate object must conform to the `BEMCheckBoxDelegate` protocol, which is composed of two optional methods:

- `didTapCheckBox:`
Sent to the delegate every time the check box gets tapped, after its properties are updated (`on`), but before the animations are completed.

- `animationDidStopForCheckBox:`
Sent to the delegate every time the check box finishes being animated.

### Customization
**BEMCheckBox** is exclusively customizable though properties.
The following diagram provides a good overview:

##### Apparence Properties
`lineWidth` - CGFloat
The width of the lines of the check mark and box. Defaults to 2.0.

`hideBox` - BOOL
BOOL to control if the box should be hidden or not. Setting this property to `YES` will essentially turn the checkbox into a check mark. Defaults to `NO`.

`boxType` - BEMBoxType
The type of box to use. See `BEMBoxType` for possible values. Defaults to `BEMBoxTypeCircle`.

`tintColor` - UIColor
The color of the box when the checkbox is Off.

`onCheckColor` - UIColor
The color of the check mark when it is On.

`onFillColor` - UIColor
The color of the inside of the box when it is On.

`onTintColor` - UIColor
The color of the line around the box when it is On.

##### Animations
`animationDuration` - CGFloat
The duration in seconds of the animations. Defaults to `0.5`.

`onAnimationType` - BEMAnimationType
The type of animation to use when the checkbox gets checked. Defaults to `BEMAnimationTypeStroke`. See `BEMAnimationType` bellow for possible values.

`offAnimationType` - BEMAnimationType
The type of animation to use when the checkbox gets unchecked. Defaults to `BEMAnimationTypeStroke`. See `BEMAnimationType` bellow for possible values.

`BEMAnimationType`
The possible values for `onAnimationType` and `offAnimationType`.
- `BEMAnimationTypeStroke`

- `BEMAnimationTypeFill`

- `BEMAnimationTypeBounce`

- `BEMAnimationTypeFlat`

- `BEMAnimationTypeOneStroke`

- `BEMAnimationTypeFade`