2.11.6 Button Boxes and Active Elements in Notebooks

Within any cell in a notebook it is possible to set up ButtonBox objects that perform actions whenever you click on them. ButtonBox objects are the way that palette buttons, hyperlinks and other active elements are implemented in Mathematica notebooks.

When you first enter a ButtonBox object in a cell, it will behave just like any other expression, and by clicking on it you can select it, edit it, and so on. But if you set the Active option for the cell, say by choosing the Cell Active item in the Cell Properties menu, then the ButtonBox will become active, and when you click on it, it will perform whatever action you have specified for it.

When the button appears in an active cell, it will paste its contents whenever you click on it.

Here is a typical palette.

In the expression corresponding to the palette each button corresponds to a ButtonBox object.

ButtonBox[boxes]	a button that will paste its contents when it appears in an active cell
ButtonBox[boxes, Active->True]	a button that will always be active
ButtonBox[boxes, ButtonStyle->"style"]
	a button whose properties are taken from the specified style

By setting the ButtonStyle you can specify defaults both for how a button will be displayed, and what its action will be. The notebook front end provides a number of standard ButtonStyle settings, which you can access from the Create Button and Edit Button menu items.

"Paste"	paste the contents of the button (default)
"Evaluate"	paste then evaluate in place what has been pasted
"EvaluateCell"	paste then evaluate the whole cell
"CopyEvaluate"	copy the current selection into a new cell, then paste and evaluate in place
"CopyEvaluateCell"	copy the current selection into a new cell, then paste and evaluate the whole cell
"Hyperlink"	jump to a different location in the notebook

Here is the expression corresponding to a CopyEvaluateCell button.

This is what the button looks like.

Here is a notebook with a selection made.

This is what happens when one then clicks on the button.

option	default value
ButtonFunction	(pasting function)	the function to apply when the button is clicked
ButtonSource	Automatic	where to get the first argument of the button function from
ButtonData	Automatic	the second argument to supply to the button function
ButtonEvaluator	None	where to send the button function for evaluation
ButtonNote	None	what to display in the window status line when the cursor is over the button

A particular ButtonStyle setting will specify defaults for all other button options. Some of these options will affect the display of the button, as discussed in Section 2.9.11. Others affect the action it performs.

What ultimately determines the action of a button is the setting for the ButtonFunction option. This setting gives the Mathematica function which is to be executed whenever the button is clicked. Typically this function will be a combination of various notebook manipulation commands.

Thus, for example, in its most basic form, a Paste button will have a ButtonFunction given effectively by NotebookApply[SelectedNotebook[ ], #]&, while a Hyperlink button will have a ButtonFunction given effectively by NotebookLocate[#2]&.

When a button is clicked, two arguments are supplied to its ButtonFunction. The first is specified by ButtonSource, and the second by ButtonData.

Typically ButtonData is set to be a fixed expression, defined when the button was first created. ButtonSource, on the other hand, usually changes with the contents of the button, or the environment in which the button appears.

Automatic	ButtonData if it is set, otherwise ButtonContents
ButtonContents	the expression displayed on the button
ButtonData	the setting for the ButtonData option
CellContents	the contents of the cell in which the button appears
Cell	the whole cell in which the button appears
Notebook	the whole notebook in which the button appears
n	the expression n levels up from the button in the notebook

For a simple Paste button, the setting for ButtonSource is typically ButtonContents. This means that whatever is displayed in the button will be what is passed as the first argument of the button function. The button function can then take this argument and feed it to NotebookApply, thereby actually pasting it into the notebook.

By using settings other than ButtonContents for ButtonSource, you can create buttons which effectively pull in various aspects of their environment for processing. Thus, for example, with the setting ButtonSource->Cell, the first argument to the button function will be the expression that represents the whole cell in which the button appears. By having the button function manipulate this expression you can then make the button have a global effect on the whole cell, say by restructuring it in some specified way.

None	the front end
Automatic	the current kernel
"name"	a kernel with the specified name

Once the arguments to a ButtonFunction have been found, and an expression has been constructed, there is then the question of where that expression should be sent for evaluation. The ButtonEvaluator option for a ButtonBox allows you to specify this.

In general, if the expression involves a range of Mathematica functions, then there will be no choice but to evaluate it in an actual Mathematica kernel. But if the expression involves only simple notebook manipulation commands, then it may be possible to execute the expression directly in the front end, without ever involving the kernel. You can specify that this should be done by setting the option ButtonEvaluator->None.

FrontEndExecute[expr]	execute an expression in the front end
FrontEnd`NotebookApply[ ... ], etc.	front end versions of notebook commands

As discussed in the previous section, the standard notebook front end can handle only a limited set of commands, all identified as being in the FrontEnd` context. But these commands are sufficient to be able to implement all of the actions associated with standard button styles such as Paste, EvaluateCell and Hyperlink.

Note that even if an expression is sent to the front end, it will be executed only if it is wrapped in a FrontEndExecute.