Chapters

Hide chapters

Catalyst by Tutorials

Third Edition · iOS 15 · Swift 5.6 · Xcode 13.3

Section I: Making a Great iPad App

Section 1: 7 chapters
Show chapters Hide chapters

9. The Mouse
Written by Andy Pereira

Heads up... You're reading this book for free, with parts of this chapter shown beyond this point as scrambled text.

Just like a keyboard, the mouse is a toolset that you may not have encountered if you’ve focused solely on iOS development. Catalyst makes working with the mouse easy since it provides a familiar pattern, and it gives you a great amount of control in the process.

In this chapter, you’ll learn to implement PointerStyleProvider and UIHoverGestureRecognizer to show a shadow effect or to change the default mouse pointer, when hovering over a diary entry in the sample app. You’ll also learn to accessorize your mouse pointers using UIPointAccessory that’s new in iOS 15. You’ll look at the differences between iOS/iPadOS and touch targets in macOS.

Getting Started

Open the starter project for this chapter. Build and run for iPadOS. If you’re using the simulator, you can capture your cursor inside the simulator to act as though it were an external device. Do this by selecting Capture Pointer in the simulator toolbar:

Capture mouse in the simulator.
Capture mouse in the simulator.

Add a few entries and then move your mouse around the app. Not much is happening, aside from seeing the cursor changing from an arrow to an iBeam if you hover over the top of the text view.

On iPadOS and macOS, you can give your users more feedback when the cursor moves over items.

Pointer Style Providers

On iPadOS, your cursor behaves a bit different from that of macOS. When hovering over buttons, you’ll notice that the button or touch target captures the cursor, and gives a unique appearance to help indicate where a touch can occur.

if let button = reusableView.viewWithTag(1) as? UIButton {
  button.pointerStyleProvider = { button, effect, _ in
    var rect = button.bounds
    rect = button.convert(
      rect, to: effect.preview.target.container
    )
    let style = UIPointerStyle(
      effect: effect, shape: .roundedRect(rect)
    )
    return style
  }
}
Camera button's effect on hovering mouse over it.
Yekisa wavwem'f iwruxr uc jivinilm ceamo ufur um.

Adding Effects With Hover Gesture Recognizer

Next, you’ll use UIHoverGestureRecognizer to add some more effects for iPadOS, as well as macOS.

addHoverGesture()
private func addHoverGesture() {
  let hoverGesture = UIHoverGestureRecognizer(
    target: self,
    action: #selector(hovering(_:))
  )
  contentView.addGestureRecognizer(hoverGesture)
}
@objc private func hovering(
  _ recognizer: UIHoverGestureRecognizer
) {
  // 1
  guard !isSelected else { return }
  // 2
  switch recognizer.state {
  // 3
  case .began, .changed:
    backgroundColor = .secondarySystemBackground
  // 4
  case .ended:
    backgroundColor = .none
  default:
    break
  }
}
Entry cell's effect on hovering mouse over it.
Ixlbx nucl'h oznuhn ad himoneqf caote apob ap.

let hoverGesture = UIHoverGestureRecognizer(
  target: self,
  action: #selector(self.hovering(_:))
)
reusableView.addGestureRecognizer(hoverGesture)
@objc private func hovering(
  _ recognizer: UIHoverGestureRecognizer
) {
  #if targetEnvironment(macCatalyst)
  switch recognizer.state {
  case .began, .changed:
    NSCursor.pointingHand.set()
  case .ended:
    NSCursor.arrow.set()
  default:
    break
  }
  #endif
}
Camera button's effect on macOS.
Pikivo hohdaj'y eggesx uz nahES.

A Few Notes on Elements and Haptics

Keep in mind that the interface guidelines for iOS state that you should keep touch targets for interactive elements to a minimum of 44pt × 44pt. The cursor gives you a lot more flexibility when your app is running on macOS. If you’re creating macOS-specific UI elements, you can use smaller elements if it makes sense for your app.

Accessorize

New to iOS 15, UIPointAccessory allows you to add custom views to the cursor, providing additional context for users. You can use predefined shapes, or custom bezier paths.

if let button = reusableView.viewWithTag(1) as? UIButton {
  button.pointerStyleProvider = { button, effect, _ in
    var rect = button.bounds
    rect = button.convert(
      rect, to: effect.preview.target.container
    )
    let style = UIPointerStyle(
      effect: effect, shape: .roundedRect(rect)
    )
    style.accessories = [
      .init(.path(.plusPath), position: .bottomRight)
    ]
    return style
  }
}
Camera button's new accessory.
Ritare duhzer'k dig oxsaylujg.

Key Points

  • You can use PointerStyleProvider to respond to cursor events on iPadOS.
  • Add hovering to views by adding a hover gesture recognizer to give your user more visual feedback.
  • Hover gesture recognizers work similarly to other gesture recognizers.
  • You can access NSCursor on macOS with Catalyst.
  • Point accessories using UIPointAccessory help you provide more context for mouse users.

Where to Go From Here?

In this chapter, you learned how easy it is to get started responding to mouse hover events and the differences between iOS touch targets versus macOS.

Have a technical question? Want to report a bug? You can ask questions and report bugs to the book authors in our official book forum here.
© 2024 Kodeco Inc.

You're reading for free, with parts of this chapter shown as scrambled text. Unlock this book, and our entire catalogue of books and videos, with a Kodeco Personal Plan.

Unlock now