winapicommon-controls

Need help understanding LVITEM state and stateMask

I'm confused. The LVITEM structure states:

state

Type: UINT

Indicates the item's state, state image, and overlay image. The stateMask member indicates the valid bits of this member.

Bits 0 through 7 of this member contain the item state flags. This can be one or more of the item state values.

So my question is, what are bits 0 through 7 for? They appear not to indicate what is used by the other bits, otherwise the stateMask wouldn't be needed.

Solution

  • MSDN tells you exactly what the bits in state are:

    Bits 0 through 7 of this member contain the item state flags. This can be one or more of the item state values.

    Bits 8 through 11 of this member specify the one-based overlay image index. ... To isolate these bits, use the LVIS_OVERLAYMASK mask.

    Bits 12 through 15 of this member specify the state image index. To isolate these bits, use the LVIS_STATEIMAGEMASK mask.

    It does not make sense to set the bottom bits to LVIS_*MASK, only the other LVIS_* states. stateMask specifies which bits in state are required/valid when you query or set the state.

    The bit layout of state and stateMask is the same and if someone hands you a LVITEM you would calculate the valid bits as valid = lvi.state & lvi.stateMask. If the state bits you care about are not set in stateMask you would have to query the listview for those bits.

    In the source code for the listview the query code might look something like this:

    void ListView::GetItemState(LVITEM&lvi, int idx)
{
  lvi.state = 0;
  if ((lvi.stateMask & LVIS_CUT) && isItemInCutState(idx, lvi)) lvi.state |= LVIS_CUT;
  if ((lvi.stateMask & LVIS_...) && ...
}