RVS_Checkbox

INTRODUCTION

This project is a robust, Swift-only, high-quality, “drop-in replacement” for the traditional UISwitch, provided by Apple. It derives from UISwitch, and provides almost exactly the same API as UISwitch.

It is implemented with no dependencies.

Integrating RVS_Checkbox into your application is as simple as adding a UISwitch or UIView in Interface Builder, and specifying it to be an instance of RVS_Checkbox.

You may also create instances of RVS_Checkbox programmatically.

This is the online project documentation for this project

WHAT PROBLEM DOES THIS SOLVE?

The classic UISwitch:

Is a great UI element, and is used in place of the classic “checkbox” for Mac:

Which doesn’t actually work as well, in the “fat finger” world of iOS UI.

So, What’s the Problem?

The issue is that the UISwitch is a big, rather awkwardly-shaped element. It is “lozenge”-shaped, and always horizontal, so can require a bit of creativity, when it comes to fitting it into a UI. Also, it has a specific design aesthetic, and can be difficult to customize (to be fair, Apple doesn’t encourage us to customize **ANY* UI, so that’s no surprise).*

Because of the horizontal aspect of the control, it is fairly “natural” to have the label to the left:

…or the right:

But it looks “awkward” to have it below the switch:

This is especially true, if you use “label buttons,” like I do (run the test harness, to see them in action). It is also a bit “weird,” as the slider appearance seems to ask for a swipe gesture, as opposed to a tap gesture (which is really what we want). That means that the gesture also requires some “mental runway.” The RVS_Checkbox allows a square aspect, and a directionless (tap) affordance, like a regular checkbox.

UISwitch also has a strictly “binary” action. If you have three choices, you are expected to use a UISegmentedControl, which is actually quite sensible. Apple obviously put a lot of research into their UX, and there’s a good reason for this. Mobile interfaces are a compromise, at best.

Why Does the RVS_Checkbox Solve This Problem?

Glad you asked. The RVS_Checkbox comes with a “built-in” appearance: A fairly “classic” appearance that uses the built-in SF Symbols to mimic the way the Mac checkboxes appear.

You can also add your own images.

Additionally, RVS_Checkbox brings the “three-state” checkbox that is found in the Mac, to iOS. That means it is possible to have an “OFF,” “ON,” and “indeterminate” mode (I call it “CLEAR”). The default appearence is the circular checkbox, and the default mode is “binary,” like UISwitch.

Here are what the images look like (the color is controlled by the tintColor property of the control):

	Default SF Symbols (TINTED RED)	User-Provided (TEMPLATE)	User-Provided (FULL COLOR)
ON
OFF
CLEAR

The “Default” images are SF Symbols images, that are “baked into” the class, and the “User-Provided” images are three arbitrary images that can be added in the storyboard, or assigned directly. They can be template, or full-color.

The images will resize with the control, but will retain their aspect (Aspect fit mode).

REQUIREMENTS

RVS_Checkbox is a UIKit/Cocoa Touch framework UIControl.

It is designed for native Swift application development.

This requires iOS/iPadOS version 17.0 or above.

DEPENDENCIES

There are no dependencies for the module. If you will be running the test harness, you will need to load the RVS_Generic_Swift_Toolbox project, as well.

INSTALLATION

The control is provided as a Swift Package Manager package, and can also be installed using Carthage.

The URL for the SPM module, is git@github.com:RiftValleySoftware/RVS_Checkbox.git.

Once the package has been added to your project, remember to import it, when you use it:

import RVS_Checkbox

If you are using Carthage, then you should add the following line to your Cartfile:

github "RiftValleySoftware/RVS_Checkbox"

Then, open Terminal, and navigate to the top of the project directory, and type this into Terminal:

carthage update

It will create a directory at the same level as the Cartfile, called “Carthage.” Inside of this directory, will be another directory, called “Checkouts.” Inside of that directory, will be another one, called “RVS_Checkbox.” You want to go into “Sources/RVS_Checkout,” and access the RVS_Checkbox.swift file. Drag a reference to this into your project, and associate it with your app build target.

Once you have the reference, then you won’t need to import the module.

USAGE

Storyboard Usage

In Interface Builder/Storyboard Editor, simply drag in a UISwitch or UIView reference, and rename the class to “RVS_Checkbox.” The inspectable elements should be immediately available in the Attributes Inspector.

Manifest for the Attributes Inspector Screen:

• On Image: An image that is displayed as the control, when it is “On.”

• Off Image: An image that is displayed as the control, when it is “Off.”

• Clear Image: An image that is displayed as the control, when it is “Clear” (as a three-state).

• Is Three-State: If this is On (default is Off), then the switch will have three states: “On,” “Off,” and “Clear.” If it is off, then the control will only have “On,” and “Off.”

• Use Off Image: If this is On (default is Off, unless no Clear Image is provided), then, when a three-state control displays a “Clear” state, it will use the “Off” Image.

• Use Haptics: If this is On (Default is On), then the control will use subtle haptics, just like the UISwitch. If set programmatically, haptics are not executed.

If you do not supply at least both an On Image and an Off Image, the default SF Symbols will be used.

It also has the standard UISwitch attributes, but “On Tint” and “Thumb Tint” are ignored.

You use the UIView.tintColor to set the color of template images (or the default SF Symbols version).

You cannot set different colors, for different states (but you can use custom full-color images).

Programmatic Usage

You should create an instance of the RVS_Checkbox class (or a subclass that you define). It can have the same init arguments as UISwitch.

Once the class has been instantiated, you can add images, set states, or set it into an AutoLayout position (as with any other UIView subclass).

Examples of both types of usage are available in the test harness app.

LICENSE

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

The Great Rift Valley Software Company: https://riftvalleysoftware.com