Toggle Checklist Items

[adryan]

G'day, all

I hope things go well for you all in 2022.

I thought I'd kick things off with a feature request.

What I would like is a command to Toggle Checklist Items, such that the bullets of selected Items in a checklist are toggled between a Box that is checked and one that is unchecked.

As things stand, List Style Properties affect every Item in a List. As far as I am aware, you can't just change them for a single Item, with or without the Macro Language. But I suggest that checklists are a special type of List, and one should have the ability to change the bullet of individual Items without affecting any of the other properties associated with that Item or with any of the other Items in the List.

Without this bullet-toggling capability, checklists in NWP are really only useful when printed (presumably with all Boxes unchecked). In fact, I generally avoid creating NWP checklists and instead use the Special Characters Palette to change the Box variant, which is somewhat inconvenient. The capability I am proposing would give NWP checklists much greater utility.

Cheers,
Adrian

[martin]

Happy 2022 and thanks for the feature request Adrian! Having a built-in list style feature to check/uncheck list items would be useful. I believe this idea has come up before. I'll verify that we have the idea filed and add your vote that we consider adding such a feature.

In the meantime the best approach is probably to use a custom list style for this purpose. The list bullets can be customized for each list level to alternate between an unchecked box and a checkmarked box, i.e. ☐ and ☑. In this way you can use indent/outdent commands (e.g. press the Tab key) to quickly check/uncheck list items.

I'll attach an example document to show this technique. You can easily add/copy/drag this list style into your documents if it's useful. I hope it helps

[adryan]

G'day, Martin et al

Thanks for that, Martin. A very interesting approach.

There are, however, a couple of problems. First, the Tab insertion/deletion must be at the beginning of a List Item if it is to effect change in the check status. Second, employing Tabs in this way is somewhat at odds with our usual understanding of how they function.

Nevertheless I discern the germ of a solution here.

First, the Increase Indent and Decrease Indent commands (towards the bottom of the Format Menu) effect the desired results in conjunction with Martin's List Style. They are applicable with the cursor positioned anywhere in a List Item, and they have easily remembered keyboard shortcuts.

Next, the Macro Language contains a command for reading the Level of a List Item. This is a read-only command, but it should be possible to write a Macro that reads the Level of a List Item in which the cursor is positioned, and then invokes the Increase Indent or Decrease Indent command, depending on whether the Level is odd or even. This would have the effect of toggling the Level and hence the check status of the associated Box. Ideally, the Macro would operate on all List Items selected, toggling each appropriately. Naming the Macro along the lines I suggested in my previous posting and assigning it a mnemonic shortcut would complete the solution.

Readers will appreciate that it is far too early in the year for me to apply myself to the devising of such a Macro. So, with such generosity of spirit as remains after the festive season, I offer the idea to others who may have found their Christmas stockings somewhat — er — deficient.

Cheers,
Adrian

[martin]

First, the Tab insertion/deletion must be at the beginning of a List Item if it is to effect change in the check status.

That's not entirely true. If one or more paragraphs are fully selected you can also press Tab (or Shift + Tab) to indent/outdent the list items, and thus toggle whether or not they are checked.

Second, employing Tabs in this way is somewhat at odds with our usual understanding of how they function
...
First, the Increase Indent and Decrease Indent commands (towards the bottom of the Format Menu) effect the desired results

Correct, or you could also use other means of changing the list level, e.g. the List palette's level buttons.

it should be possible to write a Macro that reads the Level of a List Item in which the cursor is positioned, and then invokes the Increase Indent or Decrease Indent command, depending on whether the Level is odd or even. This would have the effect of toggling the Level and hence the check status of the associated Box. Ideally, the Macro would operate on all List Items selected, toggling each appropriately

Here's a macro that should do what you want:

Code: Select all

$selection = TextSelection.active
$level = $selection.displayTypingAttributes.listLevel
If ($level % 2) == 0
	Menu "Format:Decrease Indent"
Else
	Menu "Format:Increase Indent"
End

That macro's only limitation is that it assumes the selection's list levels are uniform. The macro probably won't do what you want if you have a selection encompassing multiple paragraphs with mixed checked/unchecked list items.

[adryan]

G'day, Martin et al

Yes, that works well, albeit with the limitation you mention. I guess everything besides the first line needs to be incorporated in a loop that addresses each of the constituent selections in turn (with "$selection" in that second line replaced with something more appropriate). Is that easy enough to do?

Cheers,
Adrian

[martin]

Yes, that works well, albeit with the limitation you mention. I guess everything besides the first line needs to be incorporated in a loop that addresses each of the constituent selections in turn (with "$selection" in that second line replaced with something more appropriate). Is that easy enough to do?

You've got the right idea, and while the loop isn't particularly simple to write, it's also not too difficult. This macro should do the trick for you:

Code: Select all

$doc = Document.active
# expand selection to full paragraph(s) and process all selections
Menu "Select Paragraph"
$selections = $doc.textSelections
ForEach $selection in $selections
	$text = $selection.text
	$at = $selection.location
	While ($at == $selection.location) || ($at < $selection.bound)
		# select a single paragraph
		$range = $text.rangeOfParagraphAtIndex($at)
		$paragraphSelection = TextSelection.new($text, $range)
		$doc.setSelection($paragraphSelection)
		# toggle the paragraph's list checkbox/level
		$level = $paragraphSelection.displayTypingAttributes.listLevel
		If ($level % 2) == 0
			Menu "Format:Decrease Indent"
		Else
			Menu "Format:Increase Indent"
		End
		$at = $range.bound
	End
End
# select all affected paragraphs
$doc.setSelection($selections)

[adryan]

G'day, Martin et al

Check!

That does the trick. I tried a few things in my Macro-naïve way, but they didn't work in all situations, whereas this seems to.

So thanks for that, Martin. This is a great addition to the Macro collection — one I will actually use quite frequently.

Cheers,
Adrian

[adryan]

G'day, Martin et al

I'm just so pleased with this. I now have a Custom Toolbar Item called "Toggle" with its ticked checkbox icon positioned adjacent to the List icon. Très chic!

I might just observe that Martin's scheme should be easily modifiable for other purposes, just by choosing different pairs of bullets in the List Style definition. One is, however, limited to the collection of pre-defined bullets. So it might be desirable to add such things as on/off radio buttons and thumbs up/down to this collection at some stage.

Thanks again, Martin.

Cheers,
Adrian

[martin]

I'm just so pleased with this. I now have a Custom Toolbar Item called "Toggle" with its ticked checkbox icon positioned adjacent to the List icon. Très chic!

That's wonderful! I'm very glad to hear it

One is, however, limited to the collection of pre-defined bullets

That's definitely not true. You can configure Nisus Writer list styles to use any bullet characters you want. There is a pre-defined list of easily accessible suggestions, but you can insert any characters you like, e.g. your "checkbox" list could toggle between and if you wanted.

[adryan]

G'day, Martin et al

I had looked in vain to see how one could add a custom bullet to the pre-defined collection, including in the User Guide. I had hoped to find a customizing option in the drop-down menu in the Lists Palette, but there is none.

With Martin now assuring us it can be done, I've had another look. In fact, all one needs to do is select and paste over the character showing in the Bullet field of the List Style Properties, without regarding it as a drop-down menu. Easy! I am somewhat at a loss as to how I missed this, as there are visual cues that the field is modifiable. Must be too early in the year….

Anyway, thumbs up!

Cheers,
Adrian

[adryan]

G'day, all

I've taken the liberty of extending Martin's code so that it now allows cycling through an arbitrary number of bullets in selected List Items.

Code: Select all

# The code here extends Martin’s code for toggling Checkmarks in List Items. It allows cycling through an arbitrary number of bullets in selected List Items.

# Alter the number in the following line as appropriate.
$bullets = 3

$doc = Document.active
# Expand selection to full paragraph(s) and process all selections.
Menu "Select Paragraph"
$selections = $doc.textSelections
ForEach $selection in $selections
	$text = $selection.text
	$at = $selection.location
	While ($at == $selection.location) || ($at < $selection.bound)
		# Select a single paragraph.
		$range = $text.rangeOfParagraphAtIndex($at)
		$paragraphSelection = TextSelection.new($text, $range)
		$doc.setSelection($paragraphSelection)
		$level = $paragraphSelection.displayTypingAttributes.listLevel
		# Cycle the paragraph's list bullet/level.
		If ($level % $bullets) == 0
			For $counter = 1 to ($bullets - 1)
				Menu "Format:Decrease Indent"
			End
		Else
			Menu "Format:Increase Indent"
		End
		$at = $range.bound
	End
End
# Select all affected paragraphs.
$doc.setSelection($selections)

The attached file shows a List with bullets that represent the usual three traffic light colors. Successive invocations of a Macro containing the above code will cycle through the colors. Remember that, in the absence of any other intervening operations, Cmd-R offers a convenient way of repeating a Macro command.

Traffic Lights.rtf

(26.57 KiB) Downloaded 190 times

Traffic lights may not have much utility at deeper levels of a List, but here they might represent Abundant, Endangered and Extinct.

Given that bullet alteration is now so easy, a note of caution is perhaps warranted. Just make sure the bullet you end up with in a List Item is the one you intended there and that you haven't cycled just a bit too far. Errors could have serious consequences if bullets represented such things as political party affiliation, immunization status, dietary preference, assignment grade or (with appropriate emoji) spell to cast.

Cheers,
Adrian

[martin]

Traffic lights may not have much utility at deeper levels of a List, but here they might represent Abundant, Endangered and Extinct.

Given that bullet alteration is now so easy, a note of caution is perhaps warranted. Just make sure the bullet you end up with in a List Item is the one you intended there and that you haven't cycled just a bit too far. Errors could have serious consequences if bullets represented such things as political party affiliation, immunization status, dietary preference, assignment grade or (with approprate emoji) spell to cast.

Hah, well the traffic lights are fun, thanks for sharing Adrian!

Aside from the novelty of emoji list bullets, using list levels to categorize bits of text isn't totally frivolous. It's easy to use the Formatting Examiner palette's selection commands to quickly select all text using the same list style level so you can process or extract them, e.g. copy all similarly categorized list items to a separate document.

[adryan]

G'day, all

I've been thinking about this and doing some more experiments, and I think some clarification is in order.

I realize now that I was in error in my first posting on this topic when I said that List Style Properties affect every Item in a List. In actual fact, they affect every Item at the same Level as the one selected. The Level is displayed in the Lists and Formatting Examiner Palettes.

If you simply alter the Level of a List Item, the Item assumes the List Style Properties associated with the new Level. Other Items remain unchanged. The Increase List Level and Decrease List Level commands in the Format Menu act only on the particular Item(s) selected. If more than one Item is selected, each is changed in a relative way: they do not necessarily all assume the same characteristics.

However, if you alter the List Style Properties associated with a particular List Item, all other Items at the same Level will have their List Style Properties altered in the same manner. It's as well to be aware of this because it might not be quite what you expect. You might expect altering the List Style Properties in the Lists Palette to affect only the Item selected, and that more "global" alteration would require manipulation of the Style Sheet. But in fact they both have this "global" effect.

These considerations lie behind Martin's very cunning method for cycling bullets in individual List Items. You can't change the bullet for an individual Item by changing the List Style Properties associated with the Item because that will change the bullet for all Items at the same Level — and indeed, in all Lists in a document. But you can change the Level of an individual Item without changing the Level of any other Item. This will effectively change the List Style Properties of the Item without affecting the List Style Properties of any other Item. By defining sets of Levels whose List Style Properties differ only in the bullets associated with them, Martin is able to set the scene for a Macro to cycle through the bullet options for a particular List Item.

Sorry about the length of this explication, but the "global" stuff I referred to was not obvious to me, so knowing about it may be of service to others.

I note, too, that the Format commands I alluded to earlier are modal. If the cursor is positioned in a List, they are displayed as Increase List Level and Decrease List Level. If the cursor is situated in "ordinary" text, they are displayed as Increase Indent and Decrease Indent. So it is probably more appropriate to use the two former appellations in the Macro.

Finally, observe that the Macro takes no cognizance of the bullet characters used in a List: that is a function of the Style definitions in the document containing the List. But it is important to realize that, once the number of bullet options is chosen in the Macro, the Macro is set for that number. So you would need to have separate Macros in your Macros folder to accommodate bullet dyads, triads, etc.

Cheers,
Adrian

[martin]

That's exactly right Adrian. List styles work like other styles (e.g. Heading 1), in that they enforce consistent formatting across an entire document. Conceptually you can simply think of each list level like a nested micro style. Modifying the formatting and other properties (e.g. list bullets) of a particular list level will affect all text using that list style's level for the whole document.