Manipulating Notebooks from the Kernel

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

Functions that give the notebook objects corresponding to particular notebooks.

Within the Wolfram Language kernel, notebooks that you have open in the front end are referred to by notebook objects of the form (RefLink[NotebookObject, paclet:ref/NotebookObject])[fe,id]. The first argument of (RefLink[NotebookObject, paclet:ref/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 finds the corresponding notebook object in the front end:

Notebooks["Example.nb"]

This gets the expression corresponding to the notebook into the kernel:

NotebookGet[First[%]]

This replaces every occurrence of the string "Section" by (StringTypeLink["Text", paclet:ref/format/Text]):

%/."Section"->"Text"

This creates a new modified notebook in the front end:

NotebookPut[%]

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 (RefLink[NotebookGet, paclet:ref/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.

The Wolfram Language 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.

Finding and setting options for notebooks.

This gives the setting of the (RefLink[WindowSize, paclet:ref/WindowSize]) option for your currently selected notebook:

Options[InputNotebook[],WindowSize]

This changes the size of the currently selected notebook on the screen:

SetOptions[InputNotebook[],WindowSize->{250,100}]

Alternatively, use (RefLink[CurrentValue, paclet:ref/CurrentValue]) to directly get the value of the (RefLink[WindowSize, paclet:ref/WindowSize]) option:

CurrentValue[InputNotebook[],WindowSize]

This changes the option using (RefLink[CurrentValue, paclet:ref/CurrentValue]) with a simple assignment:

CurrentValue[InputNotebook[], WindowSize]={400,300}

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.

Moving the current selection in a notebook.

Units used in specifying selections.

Here is a simple notebook.

This sets nb to be the notebook object corresponding to the current input notebook:

nb=InputNotebook[];

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

SelectionMove[nb,Next,Word]

This extends the selection to the complete first cell:

SelectionMove[nb,All,Cell]

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

SelectionMove[nb,After,Notebook]

Searching the contents of a notebook.

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

NotebookFind[nb,"cell",Previous]

The letter α does not appear in the current notebook, so (RefLink[$Failed, paclet:ref/$Failed]) is returned, and the selection is not moved:

NotebookFind[nb,"α",Next]

Possible elements of cells to be searched by (RefLink[NotebookFind, paclet:ref/NotebookFind]).

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 (RefLink[NotebookFind, paclet:ref/NotebookFind]). You can set up tags for cells either interactively in the front end, or by explicitly setting the (RefLink[CellTags, paclet:ref/CellTags]) option for a cell.

Globally locating cells in notebooks.

(RefLink[NotebookLocate, paclet:ref/NotebookLocate]) is typically the underlying function that the Wolfram Language calls when you follow a hyperlink in a notebook. The (MenuGrayLink[Insert, paclet:ref/menuitem/Hyperlink]) ▶ (MenuGrayLink[Hyperlink, paclet:ref/menuitem/Hyperlink]) menu item sets up the appropriate (RefLink[NotebookLocate, paclet:ref/NotebookLocate]) as part of the script for a particular hyperlink button.

Writing and reading in notebooks.

(RefLink[NotebookWrite, paclet:ref/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 (RefLink[NotebookWrite, paclet:ref/NotebookWrite])[obj,data] will replace the cell with data. If the current selection lies between two cells, however, then (RefLink[NotebookWrite, paclet:ref/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:

NotebookWrite[nb,"<<inserted text>>"]

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

SelectionMove[nb,After,Cell]

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

NotebookWrite[nb,Cell["This cell contains text.","Text"]]

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

SelectionMove[nb,Next,Cell]

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

NotebookRead[nb]

(RefLink[NotebookWrite, paclet:ref/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 (RefLink[NotebookApply, paclet:ref/NotebookApply]). The first time the character "■", entered as ∖[SelectionPlaceholder] or Esc spl Esc, appears anywhere in data, (RefLink[NotebookApply, paclet:ref/NotebookApply]) will replace this character by the current selection.

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

nb=InputNotebook[];

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

NotebookApply[nb,"x + 1/\[SelectionPlaceholder]"]

Operations on the current selection.

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

SelectionMove[nb,All,CellContents]

This evaluates the current selection in place:

SelectionEvaluate[nb]

(RefLink[SelectionEvaluate, paclet:ref/SelectionEvaluate]) allows you to take material from a notebook and send it through the kernel for evaluation. On its own, however, (RefLink[SelectionEvaluate, paclet:ref/SelectionEvaluate]) always overwrites the material you took. But by using functions like (RefLink[SelectionCreateCell, paclet:ref/SelectionCreateCell]) you can maintain a record of the sequence of forms that are generated—just like in a standard Wolfram System session.

This makes the current selection be the whole cell:

SelectionMove[nb,All,Cell]

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

SelectionCreateCell[nb]

This wraps (RefLink[Factor, paclet:ref/Factor]) around the contents of the current cell:

NotebookApply[nb,"Factor[\[SelectionPlaceholder]]"]

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

SelectionEvaluateCreateCell[nb]

Functions like (RefLink[NotebookWrite, paclet:ref/NotebookWrite]) and (RefLink[SelectionEvaluate, paclet:ref/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 (RefLink[SelectionMove, paclet:ref/SelectionMove]). But functions like (RefLink[NotebookWrite, paclet:ref/NotebookWrite]) and (RefLink[SelectionEvaluate, paclet:ref/SelectionEvaluate]) can also take an additional argument which specifies where the current selection should be left after they do their work.

Performing operations and specifying what the new current selection should be.

Specifications for the new current selection.

Here is a blank notebook:

nb=InputNotebook[];

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

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:

SelectionEvaluateCreateCell[nb,All]

This wraps (RefLink[FactorInteger, paclet:ref/FactorInteger]) around the current selection:

NotebookApply[nb,"FactorInteger[\[SelectionPlaceholder]]",All]

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

SelectionEvaluate[nb,Before]

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

NotebookWrite[nb,"a = "]

Finding and setting options for whole notebooks and for the current selection.

Make the current selection be a complete cell:

SelectionMove[nb,All,Cell]

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

SetOptions[NotebookSelection[nb],CellFrame->True]

Operations on whole notebooks.

If you call (RefLink[CreateWindow, paclet:ref/CreateWindow])[] a new empty notebook will appear on your screen.

By executing commands like (RefLink[SetSelectedNotebook, paclet:ref/SetSelectedNotebook]) and (RefLink[NotebookOpen, paclet:ref/NotebookOpen]), you tell the Wolfram System 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 (RefLink[Visible, paclet:ref/Visible])->(RefLink[False, paclet:ref/False]) in (RefLink[NotebookOpen, paclet:ref/NotebookOpen]) or (RefLink[CreateWindow, paclet:ref/CreateWindow]).