Skip to content

IQKeyboardManager 6.0.0 Migration Guide

Jump to bottom
Mohd Iftekhar Qurashi edited this page Mar 13, 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 then 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.

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 library 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 full screen UITextView pinned with top layout guide and/or bottom layout guide, and you might be thinking that the textView will not go above/below of layout guide then for IQKeyboardManager new approach, it doesn't work, and layout margins/guides are ignored and your UITextView will move upward and might hide from top position. This issue needs to be handle by IQKeyboardManager using manipulating contentInset property of UITextView. But as always, it needs some time to implement.

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