Packets dealing with BoxIDs

AddBoxIDs

The packet FrontEnd`AddBoxIDs will mark a box selection with a BoxID and return a box reference to this marked box.

The option values are documented below in the section BoxReference search options

Examples

nb=CreateDocument [Cell[CellGroupData[{Cell["Blah","Subtitle"],Cell["floo","Text"],Cell[BoxData[RowBox[{"f","[",RowBox[{SuperscriptBox["ab","2",BoxID:>"foo"],"+","12"}],"]"}]],"Input"],Cell[BoxData[PaneBox[RowBox[{SuperscriptBox["xyz","q",BoxID:>{"foo","bar"}],"+","12"}],BoxID:>"Pane"]],"Input"],Cell[BoxData[GridBox[{{FractionBox[RowBox[{"r","+","t"}],"343",BoxID:>"fr"],"e"}},BoxID:>{"gr","blip"}]],"Input"]},Open]],WindowSize->{410,718},WindowMargins->{{Automatic,55},{30,Automatic}}];

Multiple BoxID Examples

nb = CreateDocument[a+(b^2)+c];
SelectionMove[nb,Before,CellContents]
SelectionMove[nb,Next,Character,2]
SelectionMove[nb,All,Character,2]

ref =MathLink`CallFrontEnd@FrontEnd`AddBoxIDs[nb]

MathLink`CallFrontEnd@FrontEnd`BoxReferenceFind[ref]

SetBoxIDs

The packet FrontEnd`SetBoxIDs will mark a box selection with a BoxID and return a box reference to this marked box.

Possible options for the packet SetBoxIDs are:

The option values are documented below in the section BoxReference search options

GetBoxIDs

The packet FrontEnd`GetBoxIDs will return a box reference to the current selection if possible.

Possible options for the packet GetBoxIDs are:

RemoveBoxIDs

The packet FrontEnd`RemoveBoxIDs will attempt to remove any BoxIDs from the first box structure matching the given box reference. The specified options control from what point we want to start searching from within the notebook, in which direction, and when we stop searching.

Possible options for the packet RemoveBoxIDs are:

The option values are documented below in the section BoxReference search options

Packets dealing with BoxReferences

BoxReferenceExists

The packet FrontEnd`BoxReferenceExists will determine if a box structure matching the given box reference exists.

Possible options for the packet BoxReferenceExists are:

The option values are documented below in the section BoxReference search options

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceExists[ FE`BoxReference [nb, {"Pane",{"foo","bar"}}]]]

BoxReferenceFind

The packet FrontEnd`BoxReferenceFind will find the first box structure matching the given box reference and set the selection to this box structure. If such a box is found BoxReferenceFind will change the notebooks selection to be the matching box structure. The specified options control from what point we want to start searching from within the notebook, in which direction, and when we stop searching.

The box reference can optionally specify a chain of BoxIDs which requires that there exist box parents of the box structure which have BoxIDs which match the BoxIDs in the box id chain. Additionally, the box reference can optionally contain an offset to parents, siblings, or children.

Possible options for the packet BoxReferenceFind are:

The option values are documented below in the section BoxReference search options

Examples

nb=CreateDocument [Cell[CellGroupData[{Cell["Blah","Subtitle", BoxID:>"fall"],Cell["floo","Text"],Cell[BoxData[RowBox[{"f","[",RowBox[{SuperscriptBox["ab","2",BoxID:>"foo"],"+","12"}],"]"}]],"Input"],Cell[BoxData[PaneBox[RowBox[{SuperscriptBox["xyz","q",BoxID:>{"foo","bar"}],"+","12"}],BoxID:>"Pane"]],"Input"],Cell[BoxData[RowBox[{"r","+","t"}]],"Input"]},Open]],WindowSize->{410,718},WindowMargins->{{Automatic,55},{30,Automatic}}];

Multiple BoxID Examples

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceFind[ FE`BoxReference [nb, {"fall"}], AutoScroll->True]]

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceFind[ FE`BoxReference [nb, {"Pane",{"foo","bar"}}], AutoScroll->True]]

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceFind[ FE`BoxReference [nb, {{"foo","bar"}}], AutoScroll->True]]

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceFind[ FE`BoxReference [nb, {{"bar","foo"}}], AutoScroll->True]]

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceFind[ FE`BoxReference [nb, {{"bar","foo"}}], AutoScroll->True,FE`SearchDirection->Backward]]

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceFind[ FE`BoxReference [nb, {{"foo"}}], AutoScroll->True,FE`SearchDirection->Backward,FE`SearchStop->"StopAtEnd",FE`SearchStart->"StartFromCurrentSelection"]]

BoxOffset Examples

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceFind[ FE`BoxReference [nb, {{"foo"}},FE`BoxOffset->{FE`BoxChild[2]}]]]

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceFind[ FE`BoxReference [nb, {{"foo"}},FE`BoxOffset->{FE`BoxParent[2]}], AutoScroll->True,FE`SearchDirection->Forward,FE`SearchStart->"StartFromCurrentSelection"]]

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceFind[ FE`BoxReference [nb, {{"foo"}},FE`BoxOffset->{FE`BoxParent[1],FE`BoxChild[2]}]]]

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceFind[ FE`BoxReference [nb, {{"foo"}},FE`BoxOffset->{FE`BoxAbsoluteSibling[2]}]]]

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceFind[ FE`BoxReference [nb, {{"foo"}},FE`BoxOffset->{FE`BoxRightSibling[2]}]]]

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceFind[ FE`BoxReference [nb, {{"foo"}},FE`BoxOffset->{FE`BoxRightSibling[3]}]]]

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceFind[ FE`BoxReference [nb, {{"foo"}},FE`BoxOffset->{FE`BoxChild[1]}]]]

Segments Examples

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceFind[ FE`BoxReference [nb, {{"foo"}},FE`BoxOffset->{FE`BoxChild[1]}]]]

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceFind[ FE`BoxReference [nb, {{"foo"}},FE`Segments->{{2,3}},FE`BoxOffset->{FE`BoxChild[1]}]]]

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceFind[ FE`BoxReference [nb, {{"foo"}}]]]

BoxAbsoluteSibling

BoxReferenceRead

The packet FrontEnd`BoxReferenceRead will return the entire box contents of the first box structure matching the given box reference. If no such box structure is found $Failed will be returned. The specified options control from what point we want to start searching from within the notebook, in which direction, and when we stop searching.

The box reference can optionally specify a chain of BoxIDs which requires that there exist box parents of the box structure which have BoxIDs which match the BoxIDs in the box id chain. Additionally, the box reference can optionally contain an offset to parents, siblings, or children.

Possible options for the packet BoxReferenceRead are:

The option values are documented below in the section BoxReference search options

Examples

nb=CreateDocument @ Cell[CellGroupData[{Cell["Blah","Subtitle"],Cell["floo","Text"],Cell[BoxData[RowBox[{"f","[",RowBox[{SuperscriptBox["ab","2",BoxID:>"foo"],"+","12"}],"]"}]],"Input"],Cell[BoxData[PaneBox[RowBox[{SuperscriptBox["xyz","q",BoxID:>{"foo","bar"}],"+","12"}],BoxID:>"Pane"]],"Input"],Cell[BoxData[RowBox[{"r","+","t"}]],"Input"]},Closed]];

Multiple BoxID Examples

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceRead[ FE`BoxReference [nb, {"Pane","foo"}], AutoScroll->True]]

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceRead[ FE`BoxReference [nb, {"Pane",{"bar","foo"}}], AutoScroll->True]]

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceRead[ FE`BoxReference [nb, {{"foo"}}], AutoScroll->True]]

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceRead[ FE`BoxReference [nb, {{"bar","foo"}}], AutoScroll->True]]

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceRead[ FE`BoxReference [nb, {{"bar","foo"}}], AutoScroll->True,FE`SearchDirection->Backward]]

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceRead[ FE`BoxReference [nb, {{"foo"}}], AutoScroll->True,FE`SearchDirection->Backward,FE`SearchStop->"StopAtEnd",FE`SearchStart->"StartFromCurrentSelection"]]

BoxOffset Examples

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceRead[ FE`BoxReference [nb, {{"foo","bar"}},FE`BoxOffset->{FE`BoxChild[2]}]]]

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceRead[ FE`BoxReference [nb, {{"foo","bar"}},FE`BoxOffset->{FE`BoxParent[2]}], AutoScroll->True,FE`SearchDirection->Forward,FE`SearchStart->"StartFromCurrentSelection"]]

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceRead[ FE`BoxReference [nb, {{"foo","bar"}},FE`BoxOffset->{FE`BoxParent[1],FE`BoxChild[2]}]]]

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceRead[ FE`BoxReference [nb, {{"foo","bar"}},FE`BoxOffset->{FE`BoxAbsoluteSibling[2]}]]]

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceRead[ FE`BoxReference [nb, {{"foo","bar"}},FE`BoxOffset->{FE`BoxRightSibling[2]}]]]

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceRead[ FE`BoxReference [nb, {{"foo","bar"}},FE`BoxOffset->{FE`BoxRightSibling[3]}]]]

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceRead[ FE`BoxReference [nb, {{"foo","bar"}},FE`BoxOffset->{FE`BoxChild[1]}]]]

Segments Examples

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceRead[ FE`BoxReference [nb, {{"foo","bar"}},FE`BoxOffset->{FE`BoxChild[1]}]]]

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceRead[ FE`BoxReference [nb, {{"foo","bar"}},FE`Segments->{{2,3}},FE`BoxOffset->{FE`BoxChild[1]}]]]

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceRead[ FE`BoxReference [nb, {{"foo","bar"}}]]]

MathLink`CallFrontEnd[UndocumentedProtoTypeBuild[]]

BoxReferenceReplace

FrontEnd`BoxReferenceReplace will replace the box structure referenced by the given box reference with the given replacement expression. If no such box structure is found $Failed will be returned. The specified options control from what point we want to start searching from within the notebook, in which direction, and when we stop searching.

The box reference can optionally specify a chain of BoxIDs which requires that there exist box parents of the box structure which have BoxIDs which match the BoxIDs in the box id chain. Additionally, the box reference can optionally contain an offset to parents, siblings, or children.

Possible options for the packet BoxReferenceReplace are:

The option values are documented below in the section BoxReference search options

Examples

nb=CreateDocument [Cell[CellGroupData[{Cell["Blah","Subtitle"],Cell["floo","Text"],Cell[BoxData[RowBox[{"f","[",RowBox[{SuperscriptBox["ab","2",BoxID:>"foo"],"+","12"}],"]"}]],"Input"],Cell[BoxData[PaneBox[RowBox[{SuperscriptBox["xyz","q",BoxID:>{"foo","bar"}],"+","12"}],BoxID:>"Pane"]],"Input"],Cell[BoxData[RowBox[{"r","+","t"}]],"Input"]},Open]],WindowSize->{410,718},WindowMargins->{{Automatic,55},{30,Automatic}}];

Multiple BoxID Examples

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceReplace[ FE`BoxReference [nb, {"Pane",{"foo","bar"}}],SuperscriptBox["bit","rod",BoxID:>{"foo","bar", "car"}]]]

MathLink`CallFrontEnd[ FrontEnd`BoxReferenceReplace[ FE`BoxReference [nb, {"Pane","bar"}], "fuf",AutoScroll->True]]

Structures

BoxReference

A box reference is a reference in a notebook to a box structure. It contains sufficient information to locate a given box (or selection) within a notebook. Each box in a notebook can contain one or more BoxIDs and the box reference refers to these BoxIDs.

BoxReference structure options are:

FE`BoxOffset directives are:

Future Notes

This is still relative.

BoxReference[nio,{NamespaceReference[name],id1,id2}]

BoxReference[nio,{NamespaceReference[name],id1,NamespaceReference[name],id2}]

Anonymous namespace

BoxReference[nio,{NamespaceReference[],id1}]

No namespace finds just the parent if it exists

BoxReference[nio,{id1}]

BoxReference[nio,{Parent[name1,name2,...],name3,name4,...}]

BoxReference[nio,{Parent[name1,Anonymous,name2,...],name3,name4,...}]

BoxReference[nio,{Parent[name1,Anonymous,name2,...],name3,name4,...}]

BoxReference[nio,{Parent[namespaceFoo],id}]

BoxReference[nio,{Parent[namespace]}]

BoxReference[nio,{Parent[id1],id2}]

Namespace[Foo,
Namespace[Bob,
FracBox[XYZBox[sdfdsf,BoxID:>"rob"],
Button[hello,
DoSomething[FillOutSelf[],{Parent[Foo],rob}]]]]]

The parent looking chain will chain through other namespaces and box ids.

Namespace[Foo,
Namespace[Bob,
FracBox[XYZBox[sdfdsf,BoxID:>"rob"],
Button[hello,
DoSomething[FillOutSelf[],{Parent[Bob,Foo],rob}]]]]]

Foo/Bob/Rob/fish

Bob/fish

Parent: searching from nio upwards for the *first* match it can find. Can match on either box ids or namespaces in any case.

FE`Parent

Foo`Bob`fish

Namespace[Foo,{box1WithIdfish,boxWith2Idfish}]

Foo`fish

For anonymous namespaces:

https : // mathematica . stackexchange . com/questions/155157/dynamiclocation - usage

FE`Anonymous

BoxReference[nio,{FE`Parent[],name1,name2}]

BoxReference[nio,{}]

Namespace[Foo,
Namespace[Bob,
FracBox[XYZBox[sdfdsf,BoxID:>"fish"],
Button[hello,
DoSomething[FillOutSelf[],{Up[Bob,Foo],"fish"}]]],PublicNames->"fish"]]

Namespace[Foo,
Namespace[Bob,
FracBox[XYZBox[sdfdsf,BoxID:>"fish"],
Button[hello,
DoSomething[FillOutSelf[],{Parent[Foo],"fish"}]]],PublicNames->"fish"]]

Namespace[Foo,
Namespace[Bob,
FracBox[XYZBox[sdfdsf,BoxID:>"fish"],
Button[hello,
DoSomething[FillOutSelf[],{Parent[Transistor,Circuit],tracksymbol345,Parent[Inductor],}]]],PublicNames->"fish"]]

Namespace[Foo,
Namespace[Bob,
FracBox[XYZBox[sdfdsf,BoxID:>"fish"],
Button[hello,
DoSomething[FillOutSelf[],{ParentNamespace[Foo],ParentBoxID[id],"fish"}]]],PublicNames->"fish"]]

Namespace[Foo,
Namespace[Bob,
FracBox[XYZBox[sdfdsf,BoxID:>"fish"],
Button[hello,
DoSomething[FillOutSelf[],{DistantParentNamespace[Foo],NamespaceReference[Bob],"fish"}]]],PublicNames->"fish"]]

Namespace[Foo,
Namespace[Bob,
FracBox[XYZBox[sdfdsf,BoxID:>"rob"],
Button[hello,
DoSomething[FillOutSelf[],{DistantParent[Foo],rob}]]]]]

Row[{Name}

How do we do absolute reference

BoxReference[nb,{Parent[name],id1,id2}]

BoxReference[nio,{NamespaceReference[name],id1,id2}]

Examples

FE`BoxReference[nb,{(Subscript[id, 1]),(Subscript[id, 2]),…},opts]

FE`BoxReference[nb,{foo,{bar,blob},linkOne},opts]

FE`BoxReference[nb,{foo,bar,{linkOne,myLink}},opts]

FE`BoxReference[nb,{foo,{blob,bar,mmug},{linkOne,myLink}}]

FE`BoxReference[nb,{Chapter1,ChapterRef[1,2,47],{linkOne,myLink}},opts]

FE`BoxReference[nb,foo,FE`BoxOffsets->{RightSibiling[2]},FE`Segments->{2,4}]

The following offset specifies that after finding the box structure which matches the BoxID chain specified in the box reference, use a box relative to this matching box. Ie for the example below the offset box is the second child of the first child of the third absolute sibling of the parent of the parent of the matched box. That box is the box all operations are done on eg, returning the contents, replacing the contents, removing, or adding box id's, etc.

FE`BoxOffset->{FE`Parent[2],FE`AbsoluteSibling[3],FE`Child[1,2]}

BoxReference search options

The various functions BoxReferenceExists, BoxReferenceFind, BoxReferenceRead, BoxReferenceReplace all search for box structures which match a given box reference. They share common options as follows.

Possible values for FE`SearchStart are:

Possible values for FE`SearchStop are:

Possible values for FE`SearchDirection are:

Possible values for FE`SelectionUpdate are:

Similar and adjacent functionality

CellObject, NotebookObject, UUIDs

ExpressionUUIDs are part of the front end and every cell has a unique uuid. CellObject and NotebookObject are based around these UUIDs.

CellIDs

This is some text

Select the first cell after the initial selection position:

Each cell can have a unique cell ID.

A particular Cell can be located via Cells[CellID->id]

Developer`CellInformation

Developer`CellInformation will return the information about the current selection, including CursorPosition and range selection.

SelectionMove[nb=EvaluationNotebook[],All,Notebook];
Developer`CellInformation[nb]

FrontEnd`SelectionObject

The identifier FrontEnd`SelectionObject is used in conjunction with CurrentValue to indicate that the options for only the current notebook selection should be set.

Dynamic@CurrentValue[FrontEnd`SelectionObject,FontFamily]

FrontEnd`UndocumentedBoxInformationPacket

This packet will give information on all of the bounding boxes of the current selection. This is heavily used in automated testing

MathLink`CallFrontEnd@FrontEnd`UndocumentedBoxInformationPacket@nb

FrontEnd`GetSelectionBoundingBoxes

MathLink`CallFrontEnd@ FrontEnd`GetSelectionBoundingBoxes @ nb

Changes coming

In the next version after Mathematica version 14.0.0 the following changes will be taking place

Cells can have BoxIDs

BoxIDs on BoxDataBoxs are written out when showing the expression