Notebook

Notebook winName, keyword =value [, keyword =value ]...

The Notebook operation sets various properties of the named notebook window. Notebook also inserts text and graphics. See Notebooks for general information.

Notebook returns an error if the notebook is open for read-only. Keywords that don't materially change the notebook, including findText, findPicture, selection, visible, magnification, userKillMode, showRuler and rulerUnits, are still permitted. See Notebook Read/Write Properties for further information.

Parameters

winName is either kwTopWin for the top notebook window, the name of a notebook window or a host-child specification (an hcSpec) such as Panel0#nb0. See Subwindow Syntax for details on host-child specifications.

If winName is an hcSpec, the host window or subwindow must be a control panel. Graphs and page layouts are not supported as hosts for notebook subwindows.

The parameters to the Notebook operation are of the form keyword =value where keyword says what to do and value is a parameter or list of parameters. Igor limits the parameters that you specify to legal values before applying them to the notebook.

The parameters are classified into related groups of keywords.

Selection Examples

// select all text in notebook
Notebook Notebook1 selection={startOfFile, endOfFile}	
// move selection to the start of the notebook and display the selection
Notebook Notebook1 selection={startOfFile,startOfFile}, findText={"",1}
// move selection to the end of the notebook and display the selection
Notebook Notebook1 selection={endOfFile,endOfFile}, findText={"",1}
// select all of paragraph 3
Notebook Notebook1 selection={(3,0), (4,0)}
// select all of paragraph 3 and display the selection
Notebook Notebook1 selection={(3,0), (4,0)}, findText={"",1}
// select all of current paragraph except for trailing CR, if any
Notebook Notebook1 selection={startOfParagraph, endOfChars}
// select the first occurrence of "Hello" in the document and display the selection
Notebook Notebook1 selection={startOfFile,startOfFile}, findText={"Hello",1}
// select the first picture in the document
Notebook Notebook1 selection={startOfFile,startOfFile}, findPicture={"",1}


modify it	(analogous to manually adjusting a ruler)
redefine it	(analogous to the Redefine Ruler dialog)
create it	(analogous to the Define New Ruler dialog)
apply it	(analogous to selecting a ruler name from ruler pop-up menu).

Tabs Example

The following puts a left tab at 1 inch, a center tab at 3 inches and a decimal tab at 5 inches:

Notebook Notebook1 tabs={1*72, 3*72 + 8192, 5*72 + 3*8192}

Notebook document property parameters

This section of Notebook relates to setting the document properties of the notebook.

adopt=a

Adopts a notebook if it is a file saved to disk. Adopting a notebook makes it part of the packed experiment file, which becomes more self-contained; if you send the experiment to a colleague you will not need to send a notebook file.

a =0:	Checks only whether the notebook is adoptable. Sets V_flag to 0 if the notebook is already adopted or to 1 if it is adoptable.
a =1:	Adopts the notebook (breaks the link to the file on disk). Sets V_flag to 1 if the adoption succeeded or to 0 if it did not (was already adopted, or some error).

backRGB=(r,g,b[,a])

Sets background color. r, g and b are values from 0 to 65535. The default is opaque white. Alpha (a) is accepted but ignored.

changeableByCommandOnly=c

The changeableByCommandOnly property is used to prevent manual modifications to the notebook but allow modifications using commands.

c =0:	Turn changeableByCommandOnly off.
c =1:	Turn changeableByCommandOnly on.

See Notebook Read/Write Properties for details.

defaultTab=dtwp

dtwp is the default tab width in points.

The defaultTab keyword sets the default tab mode to 1 meaning that the default tab width for all paragraphs is specified in units of points. See the defaultTab2 keyword for further discussion.

defaultTab2={mode,dtwp,dtws}

Controls the width of default tab stops.

The defaultTab2 keyword was added in Igor Pro 9.00.

mode is defined as follows:

1:	Points mode: The default tab width for all paragraphs is specified in units of points by dtwp.
2:	Spaces mode: The default tab width for all paragraphs is specified in units of spaces by dtws.
3:	Mixed mode: The default tab width for paragraphs controlled by proportional fonts is specified in units of points by dtwp. The default tab width for paragraphs controlled by monospace fonts is specified in units of spaces by dtws.

Specify -1 for mode to leave the mode unchanged.

The space character unit used in mode 2 and in mode 3 for monospace fonts is the width of a space character in the ruler font for a given paragraph. Plain text notebooks have only one ruler so the space character width is the same for all paragraphs. Formatted text notebooks can have many rulers and each has an associated space character width.

dtwp is the default tab width in points. It is used in mode 1 and in mode 3 for proportional fonts. Specify -1 for dtwp to leave the default tab width in points unchanged.

dtws is the default tab width in spaces. It is used in mode 2 and in mode 3 for monospace fonts. Specify -1 for dtwp to leave the default tab width in spaces unchanged.

See Notebook Default Tabs for further discussion.

magnification=m

Specifies the desired magnification in percent (between 25 and 500). Otherwise, m can be one of these special values:

m =1:	Default magnification.
m =2:	Default magnification.
	In Igor Pro 6 this specified the no-longer-supported Fit Width mode.
m =3:	Default magnification.
	In Igor Pro 6 this specified the no-longer-supported Fit Page mode.

pageMargins={left, top, right, bottom }

Sets page margins in points. left, top, right and bottom are distances from the respective edges of the physical page.

This setting overrides the margins set via the the page setup dialog and the PrintSettings operation margins keyword.

rulerUnits=r

r =0:	Points.
r =1:	Inches.
r =2:	Centimeters..

startPage=sp

sets starting page number for printing.

showRuler=s

s =0:	Hide ruler
s =1:	Show ruler.

statusWidth=sw

As of Igor 7, because of changes to the layout of notebook windows, this keyword does nothing.

In Igor 6, it set the width in points of status area at left of the horizontal scroll bar.

userKillMode=k

Specifies window behavior when the user attempts to close it.

k =0:	Normal with dialog (default).
k =1:	Kills with no dialog.
k =2:	Disables killing.
k =3:	Hides the window.

writeBOM=w

Sets the document's writeBOM property which determines if Igor writes a byte order mark when saving the notebook. This applies to plain text notebooks only and is ignored for formatted text notebooks.

w =-1:	Does not change writeBOM flag.
w =0:	Sets writeBOM to false.
w =1:	Sets writeBOM to true.

See Byte Order Marks for details.

This keyword was added in Igor Pro 7.00.

writeProtect=wp

The write-protect property is used to prevent inadvertent manual changes to the notebook.

wp =0:	Turn write-protect off.
wp =1:	Turn write-protect on.

See Notebook Read/Write Properties for details.

Notebook headers and footers

You can turn headers and footers on and off and position headers and footers using the keywords in this section.

There is currently no way to set headers and footers except manually through the Document Settings dialog. You may be able to use stationery files to create files with specific headers and footers.


footerControl={defaultFooter, firstFooter, evenOddFooter }
	defaultFooter is 1 to turn the default footer on, 0 to turn it off.
	firstFooter is 1 to turn the first page footer on, 0 to turn it off.
	evenOddFooter is 1 to turn different footers for even and odd pages on, 0 to use the same footer for even and odd pages.
footerPos=pos	pos is the position of the footer relative to the bottom of the page in points.
headerControl={defaultHeader, firstHeader, evenOddHeader }
	defaultHeader is 1 to turn the default header on, 0 to turn it off.
	firstHeader is 1 to turn the first page header on, 0 to turn it off.
	evenOddHeader is 1 to turn different headers for even and odd pages on, 0 to use the same header for even and odd pages.
headerPos=pos	pos is the position of the header relative to the top of the page in points.

Notebook miscellaneous property parameters

This section of Notebook relates to setting miscellaneous properties of the notebook.

autoSave=v

v = 0:	Notebook subwindow contents will not be saved in recreation macros.
v = 1:	Notebook subwindow contents will be saved in recreation macros (default).

This affects notebook subwindows in control panels only. Use autoSave=0 if you do not want the notebook's contents to be saved and restored when the control panel is recreated. Otherwise the notebook subwindow's contents will be restored when recreated.

frameInset= i

Specifies the number of pixels by which to inset the frame of a notebook subwindow. Does not affect a normal notebook window.

This keyword was added in Igor Pro 7.00.

frameStyle= f

Specifies the frame style for a notebook subwindow. Does not affect a normal notebook window.

f =0:	None
f =1:	Single
f =2:	Double
f =3:	Triple
f =4:	Shadow
f =5:	Indented
f =6:	Raised
f =7:	Text well

The last three styles are fake 3D and will look best if the background color behind the subwindow is a light shade of gray.

This keyword was added in Igor Pro 7.00.

status={messageStr, flags }

Sets the message in the status area at the bottom left of the notebook window.

flags is interpreted bitwise. Message is erased when:

bit 0:	Selection changes.
bit 1:	Window is activated.
bit 2:	Window is deactivated.
bit 3:	Document is modified.

If all bits are zero, the message stays until a new message comes along. All other bits are reserved for future use and should be zero. To set bit 0 and bit 3, use 2⁰+2³ = 9 for flags. See Setting Bit Parameters for details about bit settings.

updating={flags, r }

Sets parameters related to the updating of special characters.

flags is interpreted bitwise:

bit 0:	Suppress automatic periodic updating of date and time special characters. By default this bit is set so date and time special characters are updated only when the user explicitly requests it or during printing when they appear in headers and footers.
bit 1:	Allow manual updating of special characters via the specialUpdate keyword or via the Special menu. By default this is cleared so manual updating is not allowed.

All other bits are reserved for future use and should be zero.

r is the update rate in seconds for updating date and time special characters.

These settings have no effect on the updating of special characters in headers or footers. These characters are always automatically updated when the document is printed.

We recommend that you leave automatic updating off (set bit 0 of the flags parameter to 1) so that updating occurs only via the specialUpdate keyword or via the Special menu.

visible=v

v = 0:	Hides notebook.
v = 1:	Shows notebook but does not make it top window.
v = 2:	Shows notebook and makes it top window.

Accessing notebook contents

getData=mode

Causes Igor to return the contents of the notebook in the S_value variable. The contents are binary data in a private Igor format encoded as text. The only use for this keyword is to transfer data from one notebook to another by calling getData followed by setData.

mode = 1:	Stores in S_value plain text or formatted text data, depending on the type of the notebook, from the entire notebook.
mode = 2:	Stores in S_value plain text data, regardless of the type of the notebook, from the entire notebook.
mode = 3:	Stores in S_value plain text or formatted text data, depending on the type of the notebook, from the notebook selection only.
mode = 4:	Stores in S_value plain text data, regardless of the type of the notebook, from the notebook selection only.

See the Notebook In Panel example experiment for examples using getData and setData.

Writing notebook text parameters

This section of Notebook relates to inserting text at the current selection in the notebook.

text=textStr

inserts the text at the current selection.

Before the text is inserted, Igor converts escape sequences in textStr as follows:

\r	Carriage return
\n	Line feed
\t	Tab
"	Double-quote
'	Single-quote
\	Backslash

Then, it checks for illegal characters. The only character code that is illegal is zero (ASCII NUL character). If it finds an illegal character, Igor generates an error and does not insert the text.

setData=dataStr

Inserts the data at the current selection.

dataStr is either a regular string expression or the result returned by Notebook getData.

zData=dataStr

This keyword is used by Igor during the recreation of a notebook subwindow in a control panel. dataStr is encoded binary data created by Igor when the recreation macro was generated. It represents the contents of the notebook subwindow in a format private to Igor.

zDataEnd=1

This keyword is used by Igor during the recreation of a notebook subwindow in a control panel. It marks the end of encoded binary data created by Igor when the recreation macro was generated.

Writing notebook graphics parameters

This section of Notebook relates to inserting graphics at the current selection in the notebook.

These graphics keywords are allowed for formatted text files only, not for plain text files.

convertToPNG=x

Converts all pictures in the current selection to the cross-platform PNG format. If the picture is already PNG, it does nothing.

x is the resolution expansion factor, an integer from 1 to 16 times screen resolution. x is clipped to legal limits.

frame=f

Sets the frame used for the picture and insertPicture keywords.

f =0:	No frame (default).
f =1:	Single frame
f =2:	Double frame
f =3:	Triple border
f =4:	Shadow frame

insertPicture={pictureName, pathName, filePath, options }

Inserts a picture from a file specified by pathName and filePath. The supported graphics file formats are listed under Inserting Pictures.

pictureName is the special character name (see Special Character Names) to use for the inserted notebook picture or $"" to automatically assign a name.

pathName is the name of an Igor symbolic path created via NewPath or $"" to use no path.

filePath is a full path to the file to be loaded or a partial path or simple file name relative to the specified symbolic path.

If pathName and filePath do not fully specify a file, an Open File dialog is displayed from which the user can choose the file to be inserted.

options is a bitwise parameter defined as follows:

Bit 0: ::If set, an Open File dialog is displayed even if the

Bit 1:

Determines what to do in the event of a name conflict. If set, the existing special character with the conflicting name is overwritten. If cleared, a unique name is created and used as the special character name for the inserted picture.

All other bits are reserved and must be set to zero.

See Setting Bit Parameters for details about bit settings.

The variable V_flag is set to 1 if the picture was inserted or to 0 otherwise, for example, if the user canceled from the Open File dialog.

The string variable S_name is set to the special character name of the picture that was inserted or to "" if no picture was inserted.

The string variable S_fileName is set to the full path of the file that was inserted or to "" if no picture was inserted.

picture={objectSpec, mode, flags [, expansion ] }

Inserts a picture based on the specified object.

objectSpec is usually just an object name, which is the name of a graph, table, page layout, Gizmo plot, or picture from Igor's picture gallery (Misc→Pictures). See further discussion below.

mode specifies the format of the picture as follows:

mode	Windows
-9	SVG
-8	PDF
-7	TIFF
-6	JPEG
-5	PNG

-4::Device-independent bitmap

-2::8X Enhanced metafile

-1::8X Enhanced metafile

0	8X Enhanced metafile
1	8X Enhanced metafile
2	8X Enhanced metafile
4	8X Enhanced metafile
8	8X Enhanced metafile

Modes -6, -7, -8, and -9 require Igor Pro 7.00 or later.

In Igor 7 and 8, mode=-8 produced EMF. As of Igor Pro 9.00, it produces PDF. If you were using -8 for EMF, change your code to use -2.

Mode -2 (EMF) is recommended for platform-specific graphics. Mode -5 (PNG) is recommended for platform-independent bitmap graphics. Mode -8 (PDF) is recommended for platform-independent vector graphics but see the note above about -8 on Windows.

If objectSpec names a Gizmo window, only modes -5, -6 or -7 are allowed.

Modes -2 through 8 are supported for backward compatibility. In previous versions of Igor, they selected other formats that are now obsolete.

See Exporting Graphics (Windows), and Metafile Formats for further discussion of these formats.

flags is interpreted bitwise:

bit 0:

0 for black and white, 1 for color.

For color, set flags = 2⁰ = 1. All other bits are reserved for future use and should be zero. See Setting Bit Parameters for details about bit settings.

expansion is optional and requires Igor Pro 7.00 or later. It affects only modes -5, -6, and -7.

expansion sets the expansion factor over screen resolution. expansion must be an integer between 1 and 8 and is usually 1, 2, 4 or 8. The default value is 1.

scaling={h, v }

Sets the scaling used for the selected picture or the picture and insertPicture keywords.

h is horizontal scaling of picture in percent.

v is vertical scaling of picture in percent.

When using the picture keyword, you may include a coordinate specification after the object name in objectSpec. For example:

Notebook Notebook1 picture={Layout0(100, 50, 500, 700), 1, 1}

The coordinates are in points. A coordinate specification of (0, 0, 0, 0) behaves the same as no coordinate specification at all.

If the object is a graph, the coordinate specification determines the width and height of the graph. If you omit the coordinate specification, Igor takes the width and height from the graph window.

If the object is a layout, the coordinate specification identifies a section of the layout. If you omit the coordinate specification, Igor selects a section of the layout that includes all objects in the layout plus a small margin.

For any other kind of object, Igor ignores the coordinate specification if it is present.

The scaling and frame keywords apply to the selected picture, if any. If no picture is selected, they affect the insertion of a picture using the picture or insertPicture keywords. For example, this command inserts a picture of Graph0 with 50% scaling and a double frame:

Notebook Test1 scaling={50, 50}, frame=2, picture={Graph0, 1, 1}

If no picture is selected and no picture is inserted, scaling and frame have no effect.

InsertPicture Example

Function InsertPictureFromFile(nb)
	String nb		// Notebook name or "" for top notebook

	if (strlen(nb) == 0)
		nb = WinName(0, 16, 1)
	endif

	if (strlen(nb) == 0)
		Abort "There are no notebooks"
	endif

	// Display Open File dialog to get the file to be inserted
	Variable refNum		// Required for Open but not really used
	String fileFilter = "Graphics Files:.eps,.jpg,.png;All Files:.*;"
	Open /D /R /F=fileFilter refNum
	String filePath = S_fileName
	if (strlen(filePath) == 0)
		Print "You cancelled"
		return -1
	endif

	Notebook $nb, insertPicture={$"", $"", filePath, 0}
	if (V_flag)	
		Print "Picture inserted"
	else
		Print "No picture inserted"
	endif

	return 0
End

Save notebook pictures to files

The savePicture keyword is allowed for formatted text files only, not for plain text files.


savePicture={pictureName, pathName, filePath, options }
	Saves a picture from a formatted text notebook to a file specified by pathName and filePath.
	pictureName is the special character name (see Special Character Names) of the picture to be saved or $"" to save the selected picture in which case one picture and one picture only must be selected in the notebook.
	pathName is the name of an Igor symbolic path created via NewPath or $"" to use no path.
	filePath is a full path to the file to be written or a partial path or simple file name relative to the specified symbolic path.
	If pathName and filePath do not fully specify a file, a Save File dialog is displayed in which the user can specify the file to be written.
	options is a bitwise parameter defined as follows:
	Bit 0: ::If set, a Save File dialog is displayed even if the file
	Bit 1: ::If set, a file with the same name is overwritten if it
	Bit 2: ::If set then the leaf name specified by filePath is
	All other bits are reserved and must be set to zero.
	See Setting Bit Parameters for details about bit settings.
	The variable V_flag is set to 1 if the picture was written or to 0 otherwise, for example, if the user canceled from the Save File dialog.
	The string variable S_name is set to the special character name of the picture that was saved or to "" if no picture was saved.
	The string variable S_fileName is set to the full path of the file that was written or to "" if no picture was written.

Writing special character parameters

This section of Notebook relates to inserting special characters at the current selection in the notebook. To insert a notebook action, see NotebookAction.

The special characters are page break, short date, long date, abbreviated date and time. They act in some respects like a single character but have special properties. You can insert the special characters using the specialChar keyword.

The specialChar keyword is allowed for formatted text files only, not for plain text files.

Other special characters are allowed in headers and footers only and you cannot insert them in a document using the specialChar keyword. These are window title, page number and total pages.

The special characters other than page break character are dynamic. Igor updates them periodically.

specialChar={type, flags, optionsStr }

type is the special character type as follows:

1:	Page break.
2:	Short date.
3:	Long date.
4:	Abbreviated date.
5:	Time.

flags is reserved for future use. You should pass 0 for flags.

optionsStr is reserved for future use. You should pass "" for optionsStr.

specialUpdate=flags

Updates special characters in the notebook.

flags is interpreted bitwise:

bit 0:	0 to update all special characters.
	1 to update special characters in the selected text.
bit 1:	If 0 and updating for the document is disabled, it generates an error.
	If 1, updates regardless of whether updating is enabled or not.

To set bit 1 , use 2¹ = 2 for flags. See Setting Bit Parameters for details about bit settings. All other bits are reserved for future use and should be zero.

The specialUpdate keyword can update pictures of graphs, tables and page layouts that were created from windows in the current experiment.

Notebook

Notebook winName, keyword =value [, keyword =value ]...

Parameters

See Also

Selection Examples

See Also

Tabs Example

InsertPicture Example

See Also

Notebook winName, keyword =value [, keyword =value ]...​

Parameters​

See Also​

Selection Examples​

See Also​

Tabs Example​

InsertPicture Example​

See Also​

Notebook winName, keyword =value [, keyword =value ]...

Parameters

See Also

Selection Examples

See Also

Tabs Example

InsertPicture Example

See Also