2.11.3 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.

Notebooks[ ]	a list of all your open notebooks
Notebooks["name"]	a list of all open notebooks with the specified name
SelectedNotebook[ ]	the notebook that is currently selected
InputNotebook[ ]	the notebook into which typed input will go
EvaluationNotebook[ ]	the notebook in which this function is being evaluated
ButtonNotebook[ ]	the notebook containing the button (if any) which initiated this evaluation

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.

Here is a notebook named Example.nb.

This creates a new modified notebook in the front end.

In[4]:=  NotebookPut[%] Out[4]=

NotebookGet[obj]	get the notebook expression corresponding to the notebook object obj
NotebookPut[expr, obj]	make expr the expression corresponding to the notebook object obj
NotebookPut[expr]	make expr the expression corresponding to the currently selected notebook

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.

Options[obj]	give a list of all options set for the notebook corresponding to notebook object obj
Options[obj, option]	give the value of a specific option
AbsoluteOptions[obj, option]	give absolute option values even when the actual setting is Automatic
SetOptions[obj, option->value]	set the value of an option

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.

SelectionMove[obj, Next, unit]	move the current selection to make it be the next unit of the specified type
SelectionMove[obj, Previous, unit]	move to the previous unit
SelectionMove[obj, After, unit]	move to just after the end of the present unit of the specified type
SelectionMove[obj, Before, unit]	move to just before the beginning of the present unit
SelectionMove[obj, All, unit]	extend the current selection to cover the whole unit of the specified type

Character	individual character
Word	word or other token
Expression	complete subexpression
TextLine	line of text
TextParagraph	paragraph of text
CellContents	the contents of the cell
Cell	complete cell
CellGroup	cell group
EvaluationCell	cell associated with the current evaluation
ButtonCell	cell associated with any button that initiated the evaluation
GeneratedCell	cell generated by the current evaluation
Notebook	complete notebook

Here is a simple notebook.

This moves the current selection within the notebook to be the next word.

In[8]:=  SelectionMove[nb, Next, Word]

This extends the selection to the complete first cell.

In[9]:=  SelectionMove[nb, All, Cell]

This puts the selection at the end of the whole notebook.

In[10]:=  SelectionMove[nb, After, Notebook]

NotebookFind[obj, data]	move the current selection to the next occurrence of the specified data in a notebook
NotebookFind[obj, data, Previous]	move to the previous occurrence
NotebookFind[obj, data, All]	make the current selection cover all occurrences
NotebookFind[obj, data, dir, elems]	search in the specified elements of each cell, going in direction dir
NotebookFind[obj, "text", IgnoreCase->True]
	do not distinguish upper- and lower-case letters in text

This moves the current selection to the position of the previous occurrence of the word cell.

In[11]:=  NotebookFind[nb, "cell", Previous]

The letter does not appear in the current notebook, so $Failed is returned, and the selection is not moved.

In[12]:=  NotebookFind[nb, "\[Alpha]", Next] Out[12]=

CellContents	contents of each cell
CellStyle	the name of the style for each cell
CellLabel	the label for each cell
CellTags	tags associated with each cell
{, , ... }	several kinds of elements

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["tag"]	locate and select cells with the specified tag in the current notebook
NotebookLocate[{"file", "tag"}]	open another notebook if necessary

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

NotebookWrite[obj, data]	write data into a notebook at the current selection
NotebookApply[obj, data]	write data into a notebook, inserting the current selection in place of the first that appears in data
NotebookDelete[obj]	delete whatever is currently selected in a notebook
NotebookRead[obj]	get the expression that corresponds to the current selection in a notebook

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.

Here is a notebook with a word of text selected.

This replaces the selected word by new text.

In[13]:=  NotebookWrite[nb, "<<inserted text>>"]

This moves the current selection to just after the first cell in the notebook.

In[14]:=  SelectionMove[nb, After, Cell]

This now inserts a text cell after the first cell in the notebook.

In[15]:=  NotebookWrite[nb, Cell["This cell contains text.", "Text"]]

This makes the current selection be the next cell in the notebook.

In[16]:=  SelectionMove[nb, Next, Cell]

This reads the current selection, returning it as an expression in the kernel.

In[17]:=  NotebookRead[nb] Out[17]=

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 spl, 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.

In[18]:=  nb = SelectedNotebook[ ] ;

This replaces the current selection by a string that contains a copy of its previous form.

In[19]:=  NotebookApply[nb, "x + 1/"]

SelectionEvaluate[obj]	evaluate the current selection in place
SelectionCreateCell[obj]	create a new cell containing just the current selection
SelectionEvaluateCreateCell[obj]	evaluate the current selection and create a new cell for the result
SelectionAnimate[obj]	animate graphics in the current selection
SelectionAnimate[obj, t]	animate graphics for t seconds

This makes the current selection be the whole contents of the cell.

In[20]:=  SelectionMove[nb, All, CellContents]

This evaluates the current selection in place.

In[21]:=  SelectionEvaluate[nb]

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.

This makes the current selection be the whole cell.

In[22]:=  SelectionMove[nb, All, Cell]

This creates a new cell, and copies the current selection into it.

In[23]:=  SelectionCreateCell[nb]

This wraps Factor around the contents of the current cell.

In[24]:=  NotebookApply[nb, "Factor[]"]

This evaluates the contents of the current cell, and creates a new cell to give the result.

In[25]:=  SelectionEvaluateCreateCell[nb]

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.

NotebookWrite[obj, data, sel]	write data into a notebook, leaving the current selection as specified by sel
NotebookApply[obj, data, sel]	write data replacing by the previous current selection, then leaving the current selection as specified by sel
SelectionEvaluate[obj, sel]	evaluate the current selection, making the new current selection be as specified by sel
SelectionCreateCell[obj, sel]	create a new cell containing just the current selection, and make the new current selection be as specified by sel
SelectionEvaluateCreateCell[obj, sel]
	evaluate the current selection, make a new cell for the result, and make the new current selection be as specified by sel

After	immediately after whatever material is inserted (default)
Before	immediately before whatever material is inserted
All	the inserted material itself
Placeholder	the first in the inserted material
None	leave the current selection unchanged

Here is a blank notebook.

In[26]:=  nb = SelectedNotebook[ ] ;

This writes 10! into the notebook, making the current selection be what was written.

In[27]:=  NotebookWrite[nb, "10!", All]

This evaluates the current selection, creating a new cell for the result, and making the current selection be the whole of the result.

In[28]:=  SelectionEvaluateCreateCell[nb, All]

This wraps FactorInteger around the current selection.

In[29]:=  NotebookApply[nb, "FactorInteger[]", All]

This evaluates the current selection, leaving the selection just before the result.

In[30]:=  SelectionEvaluate[nb, Before]

This now inserts additional text at the position of the current selection.

In[31]:=  NotebookWrite[nb, "a = "]

Options[obj, option]	find the value of an option for a complete notebook
Options[NotebookSelection[obj], option]
	find the value for the current selection
SetOptions[obj, option->value]	set the value of an option for a complete notebook
SetOptions[NotebookSelection[obj], option->value]
	set the value for the current selection

Make the current selection be a complete cell.

In[32]:=  SelectionMove[nb, All, Cell]

Put a frame around the cell that is the current selection.

In[33]:=  SetOptions[NotebookSelection[nb], CellFrame->True]

NotebookCreate[ ]	create a new notebook
NotebookCreate[options]	create a notebook with specified options
NotebookOpen["name"]	open an existing notebook
NotebookOpen["name", options]	open a notebook with specified options
SetSelectedNotebook[obj]	make the specified notebook the selected one
NotebookPrint[obj]	send a notebook to your printer
NotebookPrint[obj, "file"]	send a PostScript version of a notebook to a file
NotebookPrint[obj, "!command"]	send a PostScript version of a notebook to an external command
NotebookSave[obj]	save the current version of a notebook in a file
NotebookSave[obj, "file"]	save the notebook in a file with the specified name
NotebookClose[obj]	close a notebook

If you call NotebookCreate[ ] a new empty notebook will appear on your screen.

By executing commands like SetSelectedNotebook and NotebookOpen, you tell the Mathematica front end to change the windows you see. Sometimes you may want to manipulate a notebook without ever having it displayed on the screen. You can do this by using the option setting Visible->False in NotebookOpen or NotebookCreate.