When do I need to call setNeedsDisplay in iOS?

You should only be calling setNeedsDisplay if you override drawRect in a subclass of UIView which is basically a custom view drawing something on the screen, like lines, images, or shapes like a rectangle.

So you should call setNeedsDisplay when you make changes to few variables on which this drawing depends and for view to represent that change , you need to call this method which internally will give a call to drawRect and redraw the components.

When you add an imageView or a UIButton as a subview or make changes to any subview, you need not call this method.

Example:

You have a view that shows a moving circle, either you touch and move it, or may be timer based animation.Now for this, you will need a custom view that draws a circle at given center and with given radius.These are kept as instance variables which are modified to move the circle by changing its center or make it bigger by increasing radius of it.

Now in this case either you will modify these variables(centre or radius) in a loop and timer Or may be by your fingers in touchesEnded and touchesMoved methods.To reflect the change in this property you need to redraw this view for which you will call setNeedsDisplay.

You only really need to call -setNeedsDisplay on UIView subclasses that draw their contents with -drawRect:.

For labels and other standard controls, changing the text will automatically cause the label to redraw so you don't need to do this yourself.

setNeedsDisplay: should be called when you want to refresh your view explicitly. It just sets an internal flag, and the iOS UI system will call drawRect: at an appropriate time later.

It sounds like it should be always called when you updating any property which may change the presentation. But it's not. Almost all the standard UI controls already handled that. I believe whenever you modify the properties of standard UI components (views), setNeedsDisplay: would be triggered internally, and the affected region will be redrawn. (In all the situations you listed)

However, if you create your own view, implement its own drawRect:, and want to update that when something has been changed, you must call setNeedsDisplay: explicitly.