What's the UIScrollView contentInset property for?

Question

It sets the distance of the inset between the content view and the enclosing scroll view.

Obj-C

aScrollView.contentInset = UIEdgeInsetsMake(0, 0, 0, 7.0);

Swift 5.0

aScrollView.contentInset = UIEdgeInsets(top: 0, left: 0, bottom: 0, right: 7.0)

Here's a good iOS Reference Library article on scroll views that has an informative screenshot (fig 1-3) - I'll replicate it via text here:

  _|←_cW_→_|_↓_
   |       | 
---------------
   |content| ↑
 ↑ |content| contentInset.top
cH |content|
 ↓ |content| contentInset.bottom
   |content| ↓
---------------
  _|_______|___ 
             ↑


   (cH = contentSize.height; cW = contentSize.width)

The scroll view encloses the content view plus whatever padding is provided by the specified content insets.

While jball's answer is an excellent description of content insets, it doesn't answer the question of when to use it. I'll borrow from his diagrams:

  _|←_cW_→_|_↓_
   |       | 
---------------
   |content| ↑
 ↑ |content| contentInset.top
cH |content|
 ↓ |content| contentInset.bottom
   |content| ↓
---------------
   |content|    
-------------↑-

That's what you get when you do it, but the usefulness of it only shows when you scroll:

  _|←_cW_→_|_↓_
   |content| ← content is still visible
---------------
   |content| ↑
 ↑ |content| contentInset.top
cH |content|
 ↓ |content| contentInset.bottom
   |content| ↓
---------------
  _|_______|___ 
             ↑

That top row of content will still be visible because it's still inside the frame of the scroll view. One way to think of the top offset is "how much to shift the content down the scroll view when we're scrolled all the way to the top"

To see a place where this is actually used, look at the build-in Photos app on the iphone. The Navigation bar and status bar are transparent, and the contents of the scroll view are visible underneath. That's because the scroll view's frame extends out that far. But if it wasn't for the content inset, you would never be able to have the top of the content clear that transparent navigation bar when you go all the way to the top.

Content insets solve the problem of having content that goes underneath other parts of the User Interface and yet still remains reachable using scroll bars. In other words, the purpose of the Content Inset is to make the interaction area smaller than its actual area.

Consider the case where we have three logical areas of the screen:

TOP BUTTONS

TEXT

BOTTOM TAB BAR

and we want the TEXT to never appear transparently underneath the TOP BUTTONS, but we want the Text to appear underneath the BOTTOM TAB BAR and yet still allow scrolling so we could update the text sitting transparently under the BOTTOM TAB BAR.

Then we would set the top origin to be below the TOP BUTTONS, and the height to include the bottom of BOTTOM TAB BAR. To gain access to the Text sitting underneath the BOTTOM TAB BAR content we would set the bottom inset to be the height of the BOTTOM TAB BAR.

Without the inset, the scroller would not let you scroll up the content enough to type into it. With the inset, it is as if the content had extra "BLANK CONTENT" the size of the content inset. Blank text has been "inset" into the real "content" -- that's how I remember the concept.

It's used to add padding in UIScrollView

Without contentInset, a table view is like this:

Then set contentInset:

tableView.contentInset = UIEdgeInsets(top: 20, left: 0, bottom: 0, right: 0)

The effect is as below:

Seems to be better, right?

And I write a blog to study the contentInset, criticism is welcome.