Check(box) Mate

Today we're going to use CheckBoxes, and show how to use some general features of Widgetry along the way.

What we want to do is create a user interface with 4 CheckBoxes. They will be labeled "Disable", "Hide", "Turn On" and "Example". We'll then hook up "Disable" to disable/enable the Example CheckBox, "Hide" to hide/show the Example CheckBox and "Turn On" to check/un-check the Example CheckBox.

We'll start off with a UserInterface subclass, we'll name CheckBoxWork, and give it four instance variables, one each for each CheckBox:

	Smalltalk defineClass: #CheckBoxWork
		superclass: #{Widgetry.UserInterface}
		indexedType: #none
		private: false
		instanceVariableNames: 'disable hide turnOn example '
		classInstanceVariableNames: ''
		imports: 'private Widgetry.* '
		category: '(none)'

We'll start off with a simple #createInterface, which creates and adds each CheckBox and puts them in the window:

	createInterface

		disable := CheckBox new.
		disable addComponent: (DisplayLabel string: '&Disable').
		disable frame inset: 10 @ 10.
		disable frame extent: 100 @ 30.
		self addComponent: disable.
		hide := CheckBox new.
		hide addComponent: (DisplayLabel string: '&Hide').
		hide frame inset: 10 @ 50.
		hide frame extent: 100 @ 30.
		self addComponent: hide.
		turnOn := CheckBox new.
		turnOn addComponent: (DisplayLabel string: '&Turn On').
		turnOn frame inset: 10 @ 90.
		turnOn frame extent: 100 @ 30.
		self addComponent: turnOn.
		example := CheckBox new.
		example addComponent: (DisplayLabel string: '&Example').
		example frame inset: 10 @ 130.
		example frame extent: 100 @ 30.
		self addComponent: example.

And this is what our window looks like:

The above is pretty boring in that it repeats the same basic code four times. However, there are a few notes. Like with a Button, we use #addComponent: to add a label to a CheckBox. This is really a bit of polymorphism sugar, in that unlike with windows you really don't add any pane to a CheckBox, just a DisplayLabel. Also note that just like all UI frameworks, adding a "&" to a DisplayLabel's text puts an underline on the next character in that string.

Some standard behavior we see: When the window starts up, the first widget added to the window is in focus. Because we added "&" to the labels, if we press "Alt-D" or H or T or E, it will change focus to the appropriate CheckBox, and it toggles it. Finally, pressing Tab or BackTab cycles through the widgets.

Dippity-Do

Now, we'll create a #hookupInterface method, to add the behavior for actually affecting our Example CheckBox:

	hookupInterface

		disable when: ValueChanged send: #changeEnablement to: self.
		hide when: ValueChanged send: #changeVisiblity to: self.
		turnOn when: ValueChanged send: #changeCheck to: self.

A CheckBox broadcasts the following Announcements: ValueAboutToChange, ValueChanging, ValueChanged, TurnedOn and TurnedOff.

When a check box's check is changed, it first broadcasts ValueAboutToChange, before the change takes place, and that is vetoable. Then, it broadcasts ValueChanging before the change, then ValueChanged after the change, and finally, TurnedOn or TurnedOff, depending on the final state of the CheckBox.

In our case, we only really care about after the change has taken place.

If we re-open our CheckBoxWork, and try to click any of the first three check boxes, we get errors, saying in effect we haven't created the #change.... method(s). So, here they are. Style note: I usually put these methods into a protocol named 'announcement handlers':

	changeEnablement

		example beEnabled: disable isChecked not.

	changeVisiblity

		example beVisible: hide isChecked not.

	changeCheck

		example beChecked: turnOn isChecked.

As you see, we like Hamlet. A lot of the simple toggle APIs in Widgetry have to be / not to be naming. Here, we use the isChecked test of each of the CheckBoxes, to change the state of the example CheckBox.

Here's a look at it with some of the checks checked:

You'll notice that even though the example CheckBox is disabled, you can turn it on or off programmatically, but of course, not with the mouse or via the Alt-E shortcut. You can even hide the CheckBox, and update it's state from the others.

Extra Credit

Let's make sure that if example is checked via the keyboard or the mouse, that Turn On is updated to match:

	hookupInterface

		disable when: ValueChanged send: #changeEnablement to: self.
		hide when: ValueChanged send: #changeVisiblity to: self.
		turnOn when: ValueChanged send: #changeCheck to: self.
		example when: ValueChanged send: #updateTurnOn to: self
		
	updateTurnOn
	
		turnOn beChecked: example isChecked.