Skip to content

IQKeyboardManager 6.0.0 Migration Guide

Jump to bottom
Mohd Iftekhar Qurashi edited this page Apr 2, 2018 · 8 revisions

IQKeyboardManager 6.0.0 is the major release. To keep this library clean and less painful, 6.0.0 removes some of the tweaks and handle them internally for you.

This guide is provided in order to ease the transition of existing applications using lower version than 6.0.0, as well as explain the design and structure of new and changed functionality.

Older Approach

To maintain distance between keyboard and textField, IQKeyboardManager always find top most view controller which is in view hierarchy. For example:-

--UIWindow
----UINavigationController
------UILayoutContainerView
--------ViewController
----------UIView
------------UITextField1
------------UITextField2
------------UITextField3

In above case IQKeyboardManager do frame manipulations with UILayoutContainerView which is actually view of UINavigationController. So if IQKeyboardManager change it's frame then UINavigationBar and whole content moves upward to maintain distance between keyboard and textField.

With old approach IQKeyboardManager save reference of ViewController (most of the time UINavigationController or UITabBarController) and save it's initial frame (CGRect). At the end IQKeyboardManager restore ViewController's view frame to it's initial frame, but sometimes it was also causing some frame issues if orientation changes occurs in the middle.

With iOS11, changing UILayoutContainerView frame was also internally doing changes with layout guides, navigation bar. This causes more bugs. If we pinned any constraint with any layout or margin guides then this approach was not dealing well with that case and we need to introduce IQLayoutGuideConstraint to handle those cases, but it's an unnecessary work for developer while IQKeyboardManager should handle more and more cases automatically.

New Approach

To maintain distance between keyboard and textField, now IQKeyboardManager find the nearest UIViewController object which might either be independent or part of UINavigationController, UITabBarController, UISplitViewController. For example:-

--UIWindow
----UINavigationController
------UILayoutContainerView
--------ViewController
----------UIView
------------UITextField1
------------UITextField2
------------UITextField3

In above case IQKeyboardManager find the ViewController as the optimal UIViewController for doing all frame manipulations without disturbing UINavigationController or UILayoutContainerView.

IQKeyboardManager now save reference of nearest optimal ViewController (most of the time UIViewController) and save it's initial origin point (CGPoint). At the end IQKeyboardManager restore ViewController's view origin poing to it's initial origin point.

From now IQKeyboardManager does not move Navigation bar. Amazingly this new approach handle layout guide constraints issues in far better way than previous, and now we don't have to do any IQLayoutGuideConstraint tweaks since it just handle automatically.

Renamed API's

  • sharedManager() renamed to shared for standard naming convension. From now use it like IQKeyboardManager.shared.enable = true
  • viewController() renamed to viewContainingController() due to method name conflict with other third party SDK's. Please see #595 for more info detail.

Removed/Deprecated API's

  • IQLayoutGuideConstraint: This property was introduce to handle constraints related issues we were getting due to pinning with top layout guide, bottom layout guide, safe area, layout margin guides.
  • preventShowingBottomBlankSpace: This property was introduce to handle a case where textField is outside view's bound. Usually at the bottom. Now this property is removed and this case will always handle.
  • shouldFixInteractivePopGestureRecognizer: This property was introduce to fix an issue with Interactive Pop Gesture Recognizer, where gesture was changing UILayoutContainerView's frame without notifying anything. But as of now, we aren't manipulating any frame changes of UILayoutContainerView, there is no need of this tweak.
  • canAdjustAdditionalSafeAreaInsets: This property was introduce recently to handle safe area related changes automatically. Setting this to YES allowing IQKeyboardManager to change additionalSafeAreaInsets. But new approach handles safe area, layout guide, layout margins related changes in a better way (automatically), there is no need of this property.

Files Removed

  • IQUIWindow+Hierarchy

Migration Guide

  • Remove all references of IQLayoutGuideConstraint from storyboard.
  • If your application changing preventShowingBottomBlankSpace shouldFixInteractivePopGestureRecognizer canAdjustAdditionalSafeAreaInsets then remove those lines since they are doing nothing now. They are deprecated.
  • If somewhere in your application, the UINavigationBar hides when your textField becomes first responder, and you have some action buttons on your navigation bar, and you are dependent on IQKeyboardManager to hide navigation bar then please change your app logic since from now IQKeyboardManager does not change navigation bar position.

Known issues

  • IQKeyboardManager moves UIView of optimal UIViewController, and with new approach, layout margins or layout guides looks to be ignored when changing it's frame. So if you have a Chat Screen kind of UI where you have a UITableView at the top and UITextField/UITextView at the bottom and UITextField/UITextView becomes first responder, then these kind of situations can't be handle with IQKeyboardManager because UITextField/UITextView becomes first responder but IQKeyboardManager never knows there is UITableView the top and that shouldn't be move upward. I would suggest you to disable IQKeyboardManager in that particular viewController and implement your own solution to achieve same kind of result.

Help

If you have any additional questions around migration, feel free to open a documentation issue on Github to get more clarity added to this guide.

Clone this wiki locally