org: Checkboxes
5.6 Checkboxes
==============
Every item in a plain list(1) (
Plain lists) can be made into a
checkbox by starting it with the string ‘[ ]’. This feature is similar
to TODO items (TODO Items), but is more lightweight. Checkboxes
are not included in the global TODO list, so they are often great to
split a task into a number of simple steps. Or you can use them in a
shopping list. To toggle a checkbox, use ‘C-c C-c’, or use the mouse
(thanks to Piotr Zielinski’s ‘org-mouse.el’).
Here is an example of a checkbox list.
* TODO Organize party [2/4]
- [-] call people [1/3]
- [ ] Peter
- [X] Sarah
- [ ] Sam
- [X] order food
- [ ] think about what music to play
- [X] talk to the neighbors
Checkboxes work hierarchically, so if a checkbox item has children
that are checkboxes, toggling one of the children checkboxes will make
the parent checkbox reflect if none, some, or all of the children are
checked.
The ‘[2/4]’ and ‘[1/3]’ in the first and second line are cookies
indicating how many checkboxes present in this entry have been checked
off, and the total number of checkboxes present. This can give you an
idea on how many checkboxes remain, even without opening a folded entry.
The cookies can be placed into a headline or into (the first line of) a
plain list item. Each cookie covers checkboxes of direct children
structurally below the headline/item on which the cookie appears(2).
You have to insert the cookie yourself by typing either ‘[/]’ or ‘[%]’.
With ‘[/]’ you get an ‘n out of m’ result, as in the examples above.
With ‘[%]’ you get information about the percentage of checkboxes
checked (in the above example, this would be ‘[50%]’ and ‘[33%]’,
respectively). In a headline, a cookie can count either checkboxes
below the heading or TODO states of children, and it will display
whatever was changed last. Set the property ‘COOKIE_DATA’ to either
‘checkbox’ or ‘todo’ to resolve this issue.
If the current outline node has an ‘ORDERED’ property, checkboxes
must be checked off in sequence, and an error will be thrown if you try
to check off a box while there are unchecked boxes above it.
The following commands work with checkboxes:
‘C-c C-c (org-toggle-checkbox)’
Toggle checkbox status or (with prefix arg) checkbox presence at
point. With a single prefix argument, add an empty checkbox or
remove the current one(3). With a double prefix argument, set it
to ‘[-]’, which is considered to be an intermediate state.
‘C-c C-x C-b (org-toggle-checkbox)’
Toggle checkbox status or (with prefix arg) checkbox presence at
point. With double prefix argument, set it to ‘[-]’, which is
considered to be an intermediate state.
− If there is an active region, toggle the first checkbox in the
region and set all remaining boxes to the same status as the
first. With a prefix arg, add or remove the checkbox for all
items in the region.
− If the cursor is in a headline, toggle checkboxes in the
region between this headline and the next (so _not_ the entire
subtree).
− If there is no active region, just toggle the checkbox at
point.
‘M-S-<RET> (org-insert-todo-heading)’
Insert a new item with a checkbox. This works only if the cursor
is already in a plain list item (Plain lists).
‘C-c C-x o (org-toggle-ordered-property)’
Toggle the ‘ORDERED’ property of the entry, to toggle if checkboxes
must be checked off in sequence. A property is used for this
behavior because this should be local to the current entry, not
inherited like a tag. However, if you would like to track the
value of this property with a tag for better visibility, customize
‘org-track-ordered-property-with-tag’.
‘C-c # (org-update-statistics-cookies)’
Update the statistics cookie in the current outline entry. When
called with a ‘C-u’ prefix, update the entire file. Checkbox
statistic cookies are updated automatically if you toggle
checkboxes with ‘C-c C-c’ and make new ones with ‘M-S-<RET>’. TODO
statistics cookies update when changing TODO states. If you delete
boxes/entries or add/change them by hand, use this command to get
things back into sync.
---------- Footnotes ----------
(1) With the exception of description lists. But you can allow it by
modifying ‘org-list-automatic-rules’ accordingly.
(2) Set the option ‘org-checkbox-hierarchical-statistics’ if you want
such cookies to count all checkboxes below the cookie, not just those
belonging to direct children.
(3) ‘C-u C-c C-c’ on the _first_ item of a list with no checkbox will
add checkboxes to the rest of the list.
Info Catalog
org: Breaking down tasks
org: TODO Items