UIButton system vs. custom in terms of colors, images, states, etc?

Question

What's the difference between UIButtonType custom, and system. How will a property such as adjustsImageWhenHighlighted affect the image(s) I supply?

What happens if I only supply some images and not others?

Answer 1

TL;DR

If you want to supply a single image, your best bet is a System button which automatically lightens the image in the disabled and highlighted states.

If you want more control over the images, you should use a Custom button and supply up to 4 images.

---

It's very confusing because there are many properties that affect the appearance of a button:

• buttonType (2): Let's just stick with system or custom. There are many more to choose from.
• isSelected (2)
• isHighlighted (2)
• isEnabled (2)
• adjustsImageWhenHighlighted (2)
• adjustsImageWhenDisabled (2)
• setImage(_,for:) (4)

Even with just these limited amount of properties, there are 256 (2^8) different combinations for a button. Just displaying let alone reasoning about all the options is a difficult task.

Furthermore, there are several other factors that affect the appearance of a button which are beyond the scope of this answer:

• tintColor
• backgroundImage
• setTitleColor(UIColor?, for: UIControlState)
• setTitleShadowColor(UIColor?, for: UIControlState)
• reversesTitleShadowWhenHighlighted: Bool
• setBackgroundImage(UIImage?, for: UIControlState)
• showsTouchWhenHighlighted
• setAttributedTitle(NSAttributedString?, for: UIControlState)

Assuming we only pay attention to the properties outlined above, here are 64 of the 256 possibilities:

I used these as the images:

Some notes about naming:

• "System" and "Custom" refer to the buttonType.
• "1 image" means there's only a single image defined for the normal state (red).
• "4 images" means there's an image defined for each of normal (red), highlighted (orange), selected (green), and disabled (purple) states.
• ID means adjustsImageWhenHighlighted=true and adjustsImageWhenDisabled=true
• id means adjustsImageWhenHighlighted=false and adjustsImageWhenDisabled=false
• seh means isSelected=false isEnabled=false isHighlighted=false
• SEH means isSelected=true isEnabled=true isHighlighted=true
• Any other combination follows the same pattern. E.g. sEh means isSelected=false isEnabled=true isHighlighted=false.

Some observations:

• In all 8 cases, the first two rows are always the same. This means the highlighted state is ignored when isEnabled=false. This makes sense.
• The Se state always fallback to the normal image. It doesn't use a shade of the S state.
• System buttons respect the tintColor in the title, selected indicator, and image (if it's a template image). (Not pictured.)
• Custom buttons respect the tintColor only in the image (if it's a template image). (Not pictured.)
• adjustsImageWhenHighlighted=false seems to be ignored for System buttons in the non-selected state!
• When you initialize a button with UIButton(), the default buttonType is custom.
• Although you can customize the selected, enabled, and highlighted states in a storyboard, the storyboard preview is not accurate. You must run your app to see the actual depiction of the state.
• If you're subclassing UIButton, you're forced to use the custom type.
• While testing, I noticed that if the button image's size is small (e.g. 28x28), tapping the image doesn't show the highlighted state. Instead you need to tap and hold, then drag outside of the image's frame, then you can move your finger over the button again.