This is documentation for Mathematica 5, which was
based on an earlier version of the Wolfram Language.
View current documentation (Version 11.1)

Documentation / Mathematica / The Mathematica Book / Principles of Mathematica / Manipulating Notebooks /

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.

Here is a button.

In[1]:= ButtonBox["Expand[SelectionPlaceholder]"] // DisplayForm

Out[1]//DisplayForm=

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.

Basic ButtonBox objects.

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.

Standard settings for the ButtonStyle option.

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.

Options that affect the action of buttons.

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.

Possible settings for the ButtonSource option.

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.

Settings for the ButtonEvaluator option.

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.

Expressions to be executed directly in the front end.

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.