Manipulating Notebooks from the Kernel

If you want to do simple operations on Mathematica notebooks, then you will usually find it convenient just to use the interactive capabilities of the standard Mathematica front end. But if you want to do more complicated and systematic operations, then you will often find it better to use the kernel.

the notebook containing the button (if any) which initiated this evaluation

Functions that give the notebook objects corresponding to particular notebooks.

Within the Mathematica kernel, notebooks that you have open in the front end are referred to by notebook objects of the form NotebookObject[fe, id]. The first argument of NotebookObject specifies the FrontEndObject for the front end in which the notebook resides, while the second argument gives a unique serial number for the notebook.

creates a notebook corresponding to expr and makes it the currently selected notebook in the front end

Exchanging whole notebook expressions between the kernel and front end.

If you want to do extensive manipulations on a particular notebook you will usually find it convenient to use NotebookGet to get the whole notebook into the kernel as a single expression. But if instead you want to do a sequence of small operations on a notebook, then it is often better to leave the notebook in the front end, and then to send specific commands from the kernel to the front end to tell it what operations to do.

Mathematica is set up so that anything you can do interactively to a notebook in the front end you can also do by sending appropriate commands to the front end from the kernel.

Within any open notebook, the front end always maintains a current selection. The selection can consist for example of a region of text within a cell or of a complete cell. Usually the selection is indicated on the screen by some form of highlighting. The selection can also be between two characters of text, or between two cells, in which case it is usually indicated on the screen by a vertical or horizontal insertion bar.

You can modify the current selection in an open notebook by issuing commands from the kernel.

In setting up large notebooks, it is often convenient to insert tags which are not usually displayed, but which mark particular cells in such a way that they can be found using NotebookFind. You can set up tags for cells either interactively in the front end, or by explicitly setting the CellTags option for a cell.

NotebookLocate is typically the underlying function that Mathematica calls when you follow a hyperlink in a notebook. The Insert ► Hyperlink menu item sets up the appropriate NotebookLocate as part of the script for a particular hyperlink button.

get the expression that corresponds to the current selection in a notebook

Writing and reading in notebooks.

NotebookWrite[obj, data] is similar to a Paste operation in the front end: it replaces the current selection in your notebook by data. If the current selection is a cell NotebookWrite[obj, data] will replace the cell with data. If the current selection lies between two cells, however, then NotebookWrite[obj, data] will create an appropriate new cell or cells.

NotebookWrite[obj, data] just discards the current selection and replaces it with data. But particularly if you are setting up palettes, it is often convenient first to modify data by inserting the current selection somewhere inside it. You can do this using selection placeholders and NotebookApply. The first time the character "", entered as \[SelectionPlaceholder] or Esc spl Esc, appears anywhere in data, NotebookApply will replace this character by the current selection.

Here is a simple notebook with the current selection being the contents of a cell.

SelectionEvaluate allows you to take material from a notebook and send it through the kernel for evaluation. On its own, however, SelectionEvaluate always overwrites the material you took. But by using functions like SelectionCreateCell you can maintain a record of the sequence of forms that are generated—just like in a standard Mathematica session.

Functions like NotebookWrite and SelectionEvaluate by default leave the current selection just after whatever material they insert into your notebook. You can then always move the selection by explicitly using SelectionMove. But functions like NotebookWrite and SelectionEvaluate can also take an additional argument which specifies where the current selection should be left after they do their work.