What's the UIScrollView contentInset property for?

Question

Can someone explain to me what the contentInset property in a UIScrollView instance is used for? And maybe provide an example?

Answer 1

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.