Skip to main content

Other Programming Keywords

These keywords are used for various purposes when writing Igor procedures.

#define​

#define symbol

A #define statement is a conditional compilation directive that defines a symbol for use only with #ifdef or ifndef expressions. #undef removes the definition.

Details​

The defined symbol exists only in the file where it is defined; the only exception is in the main procedure window where the scope covers all other procedures except independent modules. See Conditional Compilation for information on defining a global symbol.

#define cannot be combined inline with other conditional compilation directives.

See Also​

The #undef, #ifdef-#endif, and #ifndef-#endif statements

Conditional Compilation

#if-#elif-#endif​

#if expression1
	<TRUE part 1>		// Compile if condition 1 is TRUE
#elif expression2
	<TRUE part 2>		// Compile if condition 2 is TRUE and condition 1 is FALSE
[...]
[#else
	<FALSE part>]		// Optionally compile if all conditions are FALSE
#endif

In a #if-#elif-#endif conditional compilation statement, when an expression evaluates as TRUE (absolute value > 0.5), then only code corresponding to the TRUE part of that expression is compiled, and then the conditional statement is exited. If all expressions evaluate as FALSE (zero) then FALSE part is compiled when present.

Details​

Conditional compiler directives must be either entirely outside or inside function definitions; they cannot straddle a function fragment. Conditionals cannot be used within Macros.

The expressions should involve only built-in functions and literal strings and numbers such as:

#if exists("PanelResolution") != 3      // if built-in function from Igor 7+ is missing
	Function PanelResolution(panelName)   // implement an Igor 6 or earlier equivalent
		String panelName
		return 72
	End
#endif

Constants and StrConstants may not be used in the expression.

The expressions should not reference user-defined macros or functions in a different independent module ("IM"), such as in the following scenario:

// This code must be in its own procedure file and not in the built-in procedure file:
#pragma IndependentModule = myIM

#if exists("ProcGlobal#test") == 6      // NO: when compiling myIM, code in other IMs may not be compiled yet.
Function myFunction()                   // Won't compile because #if expression will be false
    Execute/Q/Z "ProcGlobal#test()"     // Only ProcGlobal can call into another IM; another IM can't directly call ProcGlobal
End
#endif
// Code in the built-in Procedure window:
Function test()
	Print "testing"
End

Running myIM#myFunction() on the command line will fail with a "unknown/inappropriate name or symbol" error.

That is because ProcGlobal procedures (those not in procedure windows with a #pragma IndependentModule statement) are compiled after all procedure windows with a #pragma IndependentModule statement.

See Also​

Conditional Compilation, Independent Modules, Constants, IgorVersion, exists

#if-#endif​

#if expression
	<TRUE part>     // Compile if condition is TRUE
[#else
	<FALSE part>]   // Optionally compile if condition is FALSE
#endif

A #if-#endif conditional compilation statement evaluates expression. If expression is TRUE (absolute value > 0.5) then the code in TRUE part is compiled, or if FALSE (zero) then the optional FALSE part is compiled.

Details​

Conditional compiler directives must be either entirely outside or inside function definitions; they cannot straddle a function fragment. Conditionals cannot be used within Macros.

See Also​

Conditional Compilation

#ifdef-#endif​

#ifdef symbol
	<TRUE part>         // Compile if symbol is defined
[#else
	<FALSE part>]       // Optionally compile if no symbol
#endif

A #ifdef-#endif conditional compilation statement evaluates symbol. When symbol is defined the code in TRUE part is compiled, or if undefined then the optional FALSE part is compiled.

Details​

Conditional compiler directives must be either entirely outside or inside function definitions; they cannot straddle a function fragment. Conditionals cannot be used within Macros.

symbol must be defined before the conditional with #define.

See Also​

#define, Conditional Compilation

#ifndef-#endif​

#ifndef symbol
	<TRUE part>         // Compile if symbol is undefined
[#else
	<FALSE part>]       // Optionally compile if symbol defined
#endif

A #ifndef-#endif conditional compilation statement evaluates symbol. When symbol is undefined the code in TRUE part is compiled, or if defined then the optional FALSE part is compiled.

Details​

Conditional compiler directives must be either entirely outside or inside function definitions; they cannot straddle a function fragment. Conditionals cannot be used within Macros.

symbol must be defined before the conditional with #define.

See Also​

#define, Conditional Compilation

#include​

#include "file spec" or <file spec>

A #include statement in a procedure file automatically opens another procedure file. You should use #include in any procedure file that you write if it requires that another procedure file be open. A #include statement must always appear flush against the left margin in a procedure window.

Parameters​

The ".ipf" extension must be omitted from both "file spec" and <file spec>.

The <file spec> syntax is used to include a WaveMetrics procedure file in "Igor Pro Folder/WaveMetrics Procedures". file spec is the name of the procedure file without the extension.

The "file spec" syntax is used to include a user procedure file typically in "Igor Pro User Files/User Procedures". If file spec is the name of or a partial path to the file, Igor interprets it as relative to the "User Procedures" folder. If file spec is a full path then it specifies the exact path to the file without the extension.

See Also​

The Include Statement, Igor Pro User Files, Turning the Included File's Menus Off

#pragma​

#pragma introduces a compiler directive, which is a message to the Igor procedure compiler. A #pragma statement must always appear flush against the left margin in a procedure window.

Igor ignores unknown pragmas such as pragmas introduced in later versions of the program.

Currently, Igor supports the following pragmas:

#pragma rtGlobals = value
#pragma version = versionNumber
#pragma IgorVersion = versionNumber
#pragma hide = value
#pragma ModuleName = name
#pragma IndependentModule = name
#pragma rtFunctionErrors = value
#pragma TextEncoding = "textEncodingName"                           // Added in Igor Pro 7.00
#pragma DefaultTab = {<mode>,<width in points>,<width in spaces>}   // Added in Igor Pro 9.00

See Also​

Pragmas, The rtGlobals Pragma, The version Pragma, The IgorVersion Pragma, The hide Pragma, The ModuleName Pragma, The IndependentModule Pragma, The rtFunctionErrors Pragma, The TextEncoding Pragma, The DefaultTab Pragma For Procedure Files

#undef​

#undef symbol

A #undef statement removes a nonglobal symbol created previously by #define. See Conditional Compilation for information on undefining a global symbol.

See Also​

#define, Conditional Compilation

Constant​

Constant kName = literalNumber
Constant/C kName = (literalNumberReal, literalNumberImag )

The Constant declaration defines the number literalNumber under the name kName for use by other code, such as in a switch construct.

The complex form, using the /C flag to create a complex constant, requires Igor Pro 7.00 or later.

See Also​

See the Strconstant keyword for string types, as well as the Constant Type and Switch Statements sections.

DefaultTab​

#pragma DefaultTab={mode,widthInPoints,widthInSpaces}

The DefaultTab pragma allows you to specify default tab settings by entering a pragma statement in a procedure file. Specifying tab widths in spaces rather than points provides better results if the procedure window font or font size is changed.

The DefaultTab pragma was added in Igor Pro 9.00. It is ignored by earlier Igor versions.

See Procedure Window Default Tabs for details.

DoPrompt [/HELP=helpStr ] dialogTitleStr, variable [, variable ]...​

The DoPrompt command in a function invokes the simple input dialog. A DoPrompt specifies the title for the simple input dialog and which input variables are to be included in the dialog.

Flags​

/HELP=helpStrSets the help topic or help text that appears when the dialog's Help button is pressed.
helpStr can be a help topic and subtopic such as is used by DisplayHelpTopic/K=1 helpStr, or it can be text (255 chars max) that is displayed in a subdialog just as if DoAlert 0, helpStr had been called, or helpStr can be "" to remove the Help button.

Parameters​

variable is the name of a dialog input variable, which can be real or complex numeric local variable or local string variable, defined by a Prompt statement. You can specify as many as 10 variables.

dialogTitleStr is a string or string expression containing the text for the title of the simple input dialog.

Details​

Prompt statements are required to define what variables are to be used and the text for any string expression to accompany or describe the input variable in the dialog. When a DoPrompt variable is missing a Prompt statement, you will get a compilation error. Pop-up menu string data cannot be continued across multiple lines as can be done using Prompt in macros. See Prompt for further usage details.

Prompt statements for the input variables used by DoPrompt must come before the DoPrompt statement itself, otherwise, they may be used anywhere within the body of a function. The variables are not required to be input parameters for the function (as is the case for Prompt in macros) and they may be declared within the funtion body. DoPrompts can accept as many as 10 variables.

Functions can use multiple DoPrompt statements, and Prompt statements can be reused or redefined.

When the user clicks the Cancel button, any new input parameter values are not stored in the variables.

DoPrompt sets the variable V_flag as follows:
V_flag=
0:Continue clicked.
1:Cancel clicked.

See Also​

The Simple Input Dialog, Prompt, DisplayHelpTopic

GalleryGlobal​

GalleryGlobal#pictureName

The GalleryGlobal keyword is used in an independent module to reference a picture in the global picture gallery which you can view by choosing Misc→Pictures.

See Also​

Independent Modules and Pictures

hide​

#pragma hide=value

The hide pragma allows you to make a procedure file invisible.

See Also​

#pragma, The hide Pragma

IgorVersion​

#pragma IgorVersion=versNum

When a procedure file contains the directive, #pragma IgorVersion=versNum, an error will be generated if versNum is greater than the current Igor Pro version number. It prevents procedures that use new features added in later versions from running under older versions of Igor in which these features are missing. However, this version check is limited because it does not work with versions of Igor older than 4.0.

See Also​

#pragma, The IgorVersion Pragma

IndependentModule​

#pragma IndependentModule=imName

The IndependentModule pragma designates groups of one or more procedure files that are compiled and linked separately. Once compiled and linked, the code remains in place and is usable even though other procedures may fail to compile. This allows functioning control panels and menus to continue to work regardless of user programming errors.

See Also​

#pragma, Independent Modules, The IndependentModule Pragma

Menu menuNameStr [, hideable, dynamic, contextualmenu]

The Menu keyword introduces a menu definition. You can use this to create your own menu, or to add items to a built-in Igor menu.

Use the optional hideable keyword to make the menu hideable using HideIgorMenus.

Use the optional dynamic keyword to cause Igor to re-evaluate the menu definition when the menu is used. This is helpful when the menu item text is provided by a user-defined function. See Dynamic Menu Items.

Use the optional contextualmenu keyword for menus invoked by PopupContextualMenu/N.

See User-defined Menus for further information.

ModuleName​

#pragma ModuleName=modName

The ModuleName pragma assigns a name, which must be unique among all procedure files, to a procedure file so that you can use static functions and Proc Pictures in a global context, such as in the action procedure of a control or on the Command Line.

Using the ModuleName pragma involves at least two steps. First, within the procedure file assign it a name using #pragma ModuleName=modName, and then access objects in the named file by preceding the object name with the name of the module and the # character, such as or example: ModName#StatFuncName().

See Also​

#pragma, Regular Modules

MultiThread​

MultiThread [/NT=numThreads] wave = expression

In user-defined functions, the MultiThread keyword can be inserted in front of wave assignment statements to speed up execution on multiprocessor computer systems.

caution

Misuse of this keyword can result in a performance penalty or even a crash. Be sure to read Automatic Parallel Processing with MultiThread before using MultiThread.

The expression must be thread-safe. This means that if it calls a function, the function must be thread-safe. This goes for both built-in and user-defined functions.

Not all built-in functions are thread-safe. Use the Command Help tab in the Igor Help Browser to see which functions are thread-safe.

User-defined functions are thread-safe if they are defined using the ThreadSafe keyword. See ThreadSafe Functions for details.

You can specify the number of threads using the /NT flag. The default value, which takes effect if you omit /NT or specify /NT=0, uses the number returned by ThreadProcessorCount. /NT=1 specifies a single thread and is equivalent to omitting the MultiThread keyword; you might want to turn off threading to avoid its overhead when the wave has few points. numThreads values greater than one specify the desired number of threads to be used. Igor may use fewer threads depending on how it is able to partition the task. The /NT flag was added in Igor Pro 8.00.

For more complex multithreading applications, see ThreadSafe Functions and Multitasking.

See Also​

Automatic Parallel Processing with MultiThread

Waveform Arithmetic and Assignment

Demo​

Open MultiThread Mandelbrot Demo Experiment

Override​

Override Constant objectName = newNumber
Override StrConstant objectName = "newStringValue"
Override Function funcName()

The Override keyword redefines a constant, strconstant, or user function. The objectName or funcName must be the same as the name of the original object or function that is being redefined. The override must be defined before the target object appears in the compile sequence.

See Also​

Function Overrides, Constant Type

The Popup keyword is used with Prompt statements in Functions and Macros. It indicates that you want a pop-up menu instead of the normal text entry item in a DoPrompt simple input dialog (or a Macro's missing parameter dialog (archaic)). menuList is a string expression containing a list of items, separated by semicolons, that are to appear in the pop-up menu. menuList is limited to 255 bytes.

Pop-up menus accept both numeric and string parameters. For numeric parameters, the number of the item selected is placed in a variable. Numbering starts from one. For string parameters, the selected item's text is placed in a string variable.

See Also​

Prompt, DoPrompt, Pop-Up Menus in Simple Dialogs

See WaveList, TraceNameList, ContourNameList, ImageNameList, FontList, MacroList, FunctionList, StringList, and VariableList for ways to generate lists of Igor objects.

ProcGlobal​

ProcGlobal#procPictureName

The ProcGlobal keyword is used with Proc Pictures to avoid possible naming conflicts with any other global pictures in the experiment. When you add a picture to an experiment using the Pictures dialog, such a picture is global in scope and may potentially have the same name as a Proc Picture. When a Proc Picture is global (and only then), you should use the ProcGlobal keyword to make sure that the Proc Picture is used with your code and to avoid confusion with pictures in the Pictures dialog.

See Also​

Proc Pictures

Prompt variableName, titleStr [, popup, menuListStr ]​

The Prompt statement is used in functions for the simple input dialog and in macros for the missing parameter dialog. Prompt supplies text to describe variableName to the user, and optionally provides a pop-up menu of choices for the value of variableName.

Parameters​

variableName is the name of a macro input parameter or function variable.

titleStr is a string or string expression containing the text to present in the dialog to describe what variableName is.

The optional keyword "popup" is used to provide a pop-up list of choices for the values of variableName. If popup is used, then menuListStr is required.

menuListStr is a string or string expression that contains a semicolon-separated list of choices for the value of variableName. If variableName is a string, choosing from this list will set the string to the selection. If it is a numeric variable, then it is set to the item number of the selection (if the first item is selected, the numeric variable is set to 1, etc.).

Details​

In macros, there must be a blank line after the set of input parameter declarations and prompt statements and there must not be any blank lines within the set.

In user-defined functions, Prompt may be used anywhere within the body of the function, but must precede any DoPrompt that uses the Prompt variable.

menuListStr may be continued on succeeding lines only in macros, as long as no comment is appended to the Prompt line. The additional lines should start with a semicolon, and are appended to the menuListStrs on preceding lines.

See Also​

For use in user-defined functions, see The Simple Input Dialog.

For use in macros, see The Missing Parameter Dialog.

For use in functions and macros, see the DoPrompt and popup keywords.

root​

root[:dataFolderName [:dataFolderName [:...]]][:objectName ]

Igor's data folder hierarchy starts with the root folder as its basis. The root data folder always exists and it contains all other objects (waves, variables, strings, and data folders). By default, the root data folder is the current data folder when Igor starts a new experiment. In commands, root is used as part of a path specifying the location of a data object in the folder hierarchy.

See also​

Data Folders

rtGlobals​

#pragma rtglobals = 0, 1, 2 or 3

#pragma rtglobals=<n> is a compiler directive that controls compiler and runtime behaviors for the procedure file in which it appears.

This statement must be flush against the left edge of the procedure file with no indentation. It is usually placed at the top of the file.

#pragma rtglobals=0 turns off runtime creation of globals. This is obsolete.

#pragma rtglobals=1 is a directive that turns on runtime lookup of globals. This is the default behavior if #pragma rtGlobals is omitted from a given procedure file.

#pragma rtglobals=2 turns off compatibility mode. This is mostly obsolete. See Legacy Code Issues for details.

#pragma rtglobals=3 turns on runtime lookup of globals, strict wave reference mode and wave index bounds checking.

rtGlobals=3 is recommended.

See The rtGlobals Pragma for a detailed explanation of rtGlobals.

Static​

Static Constant objectName = newNumber
Static StrConstant objectName = "newStringValue"
Static Function funcName()
Static Structure structureName
Static Picture pictName

The Static keyword declaration specifies that a constant, user-defined function, structure, or Proc Picture is local to the procedure file in which it appears. Static objects can only be used by other functions; they cannot be accessed from macros; they cannot be accessed from other procedure files or from the command line.

See Also​

Static Functions, Proc Pictures, Constants

Strconstant​

Strconstant ksName ="literal string "

The Strconstant declaration defines the string literal string under the name ksName for use by other code, such as in a switch construct.

See Also​

See the Constant keyword for numeric types, as well as the Constant Type and Switch Statements sections.

The Submenu keyword introduces a submenu definition. It is used inside a Menu definition. See User-defined Menus for further information.

TextEncoding​

#pragma TextEncoding = "<text encoding name>"

#pragma TextEncoding is a compiler directive that tells Igor the text encoding used by a procedure file. Igor needs to know this in order to correctly interpret non-ASCII characters in the file. We recommend that you add a TextEncoding pragma to your procedure files.

All new procedure files should use the UTF-8 text encoding:

#pragma TextEncoding = "UTF-8"

See Text Encoding Names and Codes for a list of accepted text encoding names.

This statement must be flush against the left edge of the procedure file with no indentation. It is usually placed at or near the top of the file.

The TextEncoding pragma was added in Igor Pro 7.00 and is ignored by earlier versions.

See The TextEncoding Pragma for further explanation.

ThreadSafe​

ThreadSafe Function funcName()

The ThreadSafe keyword declaration specifies that a user function can be used for preemptive multitasking background tasks on multiprocessor computer systems.

A ThreadSafe function is one that can operate correctly during simultaneous execution by multiple threads. Such functions are generally limited to numeric or utility functions. Functions that access windows are not ThreadSafe. To determine if an operation is ThreadSafe, use the Command Help tab of the Help Browser and choose ThreadSafe from the pop-up menu.

ThreadSafe functions can call other ThreadSafe functions but may not call non-ThreadSafe functions. Non-ThreadSafe functions can call ThreadSafe functions.

See Also​

ThreadSafe Functions, ThreadSafe Functions and Multitasking

version​

#pragma version=versNum

When the user invokes the File Information dialog, the version pragma provides file version information, which is displayed next to the file name in the dialog. This line must not be indented and must appear in the first 50 lines of the file. See Procedure File Version Information.

See Also​

#pragma, The version Pragma, IgorInfo

// {#}​

The // characters end the executable part of a command line and start a comment. The comment continues only to the end of the line.

$ {#}​

The $ character is used to convert a string containing a name into a reference to the named object. See Converting a String into a Reference Using $ and Using $ in Macros for details.