SetVariable_Operation
SetVariable [/Z] ctrlName [ keyword = value [, keyword = value ...] ]
The SetVariable operation creates or modifies a SetVariable control in the target window.
A SetVariable control sets the value of a global numeric or string variable or a point in a wave when you type or click in the control. A SetVariable can also hold its own value without the need for a global or wave.
For information about the state or status of the control, use the ControlInfo operation.
Parameters
ctrlName is the name of the SetVariable control to be created or changed.
The following keyword=value parameters are supported:
| activate | Activates the control and selects the text that sets the value. Use ControlUpdate to deactivate the control and deselect the text. | ||||||||
| align=alignment | Sets the alignment mode of the control. The alignment mode controls the interpretation of the leftOrRight parameter to the pos keyword. The align keyword was added in Igor Pro 8.00. | ||||||||
| If alignment=0 (default), leftOrRight specifies the position of the left end of the control and the left end position remains fixed if the control size is changed. | |||||||||
| If alignment=1, leftOrRight specifies the position of the right end of the control and the right end position remains fixed if the control size is changed. | |||||||||
| appearance={kind [, platform ]} | |||||||||
| Sets the appearance of the control. platform is optional. Both parameters are names, not strings. | |||||||||
kind can be one of default, native, or os9. | |||||||||
platform can be one of Mac, Win, or All. | |||||||||
| See Button and DefaultGUIControls for more appearance details. | |||||||||
| bodyWidth=width | Specifies an explicit size for the body (nontitle) portion of a SetVariable control. By default (bodyWidth=0), the body portion is the amount left over from the specified control width after providing space for the current text of the title portion. If the font, font size or text of the title changes, then the body portion may grow or shrink. If you supply a bodyWidth>0, then the body is fixed at the size you specify regardless of the body text. This makes it easier to keep a set of controls right aligned when the default font is changed. | ||||||||
| disable=d | Sets user editability of the control. | ||||||||
| |||||||||
| fColor=(r,g,b[,a]) | Sets the initial color of the title. r, g, b, and a specify the the color and optional opacity as RGBA Values. The default is opaque black. | ||||||||
| To further change the color of the title text, use escape sequences as described for title=titleStr. | |||||||||
| focusRing=fr | Enables or disables the drawing of a rectangle indicating keyboard focus: | ||||||||
| |||||||||
| font="fontName" | Sets the font used to display the value of the variable, | ||||||||
| e.g., font="Helvetica". | |||||||||
| format=formatStr | Sets the numeric format of the displayed value, e.g., format="%g". Not used with string variables. Never use leading text or the "%W" format for numbers, because Igor reads the value back without interpreting the extra text. For a description of formatStr, see the printf operation. | ||||||||
| frame=f |
| ||||||||
| fsize=s | Sets the size of the type used to display the value of the variable. | ||||||||
| fstyle=fs | fs is a bitwise parameter with each bit controlling one aspect of the font style as follows: | ||||||||
| |||||||||
| See Setting Bit Parameters for details about bit settings. | |||||||||
| guides={left, hcenter, right, top, vcenter, bottom} | |||||||||
| Controls attachments of anchor points to layout guides. See Laying Out Controls in Guides Mode for detailed information and examples. | |||||||||
| Each of left, hcenter, right, top, vcenter, bottom is replaced with the name of a layout guide of appropriate orientation. That is, left, hcenter, right indicate attachments to vertical guides, and top, vcenter, bottom indicate attachments to horizontal guides. Use the special name kwNone to represent an unattached anchor point. | |||||||||
| An error results if you overconstrain a control's layout. A SetVariable control's height is determined by font and font sizes used for the title and value, so only one of top, vcenter, bottom can be attached to a layout guide. | |||||||||
| If you use the bodyWidth keyword, the width of the control is set by the body width plus the width of the title, so you can use only one of left, hcenter, right. | |||||||||
| If you do not use bodyWidth, then the value portion of the control is whatever is left over after the title width is subtracted from the overall control width, so if you use two guide attachments, they could reduce the width of the value portion to zero. | |||||||||
| Using kwNone for all anchor points results in completely detaching a control from the layout guides. | |||||||||
| help={helpStr } | Sets the help for the control. | ||||||||
| helpStr is limited to 1970 bytes (255 in Igor Pro 8 and before). | |||||||||
| You can insert a line break by putting "\r" in a quoted string. | |||||||||
| labelBack=(r,g,b[,a]) or 0 | |||||||||
| Specifies the background fill color for labels. r, g, b, and a specify the the color and optional opacity as RGBA Values. The default is 0, which uses the window's background color. | |||||||||
| limits={low,high,inc } | low and high set the limits of the allowable values for the variable. inc sets the amount by which the variable is incremented if you click the control's up/down arrows. This applies to numeric variables, not to string variables. If inc is zero then the up/down arrows will not be drawn. | ||||||||
| live=l |
| ||||||||
| noedit=val |
| ||||||||
| noproc | Specifies that no procedure is to execute when the control's value is changed. | ||||||||
| pos={leftOrRight,top } | Sets the position in control panel units of the top/left corner of the control if its alignment mode is 0 or the top/right corner of the control if its alignment mode is 1. See the align keyword above for details. | ||||||||
| pos+={dx,dy } | Offsets the position of the control in control panel units. | ||||||||
| proc=procName | Specifies the procedure to execute when the control's value is changed. | ||||||||
| rename=newName | Gives control a new name. | ||||||||
| size={width,height } | Sets width of control in control panel units. height is ignored. | ||||||||
| styledText=val | styledText=1 allows the use of use of formatting escape codes described under Annotation Escape Codes. This works for string SetVariable controls only, not for numeric controls. | ||||||||
| For example: | |||||||||
SetVariable sv0 value=_STR:"\JC\K(65535,0,0)Centered Red Text" | |||||||||
| styledText=0 treats escape codes as plain text. | |||||||||
| The styledText keyword was added in Igor Pro 6.34. For compatibility with earlier versions of Igor, the combination of noedit=1 and styledText=1 is recorded as noedit=2 in recreation macros. | |||||||||
| textAlign=t | Sets the alignment of the text displayed in the body of the control. | ||||||||
| |||||||||
| The textAlign keyword was added in Igor Pro 9.00. | |||||||||
| title=titleStr | Sets the title of the control to the specified string expression. The title is displayed to the left of the control. If titleStr is empty (""), the name of the variable being controlled is displayed as a title. Use title=" " to create a "blank" title. | ||||||||
| Using escape codes you can change the font, size, style and color of the title. See Annotation Escape Codes for details. | |||||||||
| userdata(UDName )=UDStr | |||||||||
| Sets the unnamed user data to UDStr. Use the optional (UDName ) to specify a named user data to create. | |||||||||
| userdata(UDName )+=UDStr | |||||||||
| Appends UDStr to the current unnamed user data. Use the optional (UDName ) to append to the named user data. | |||||||||
| value=varOrWaveName | Sets the numeric or string variable or wave element to be controlled. | ||||||||
| If varOrWaveName references a wave, the point is specified using standard bracket notation with either a numeric point number or a row label, e.g., value=awave[4] or value=awave[%alabel]. You may also use a 2D, 3D, or 4D wave and specify a column, layer, and chunk index or dimension label in addition to the row index. | |||||||||
| You can have the control store the value internally rather than in a global variable. In place of varName, use _STR:str or _NUM:num. For example: | |||||||||
NewPanel;SetVariable sv1,value=_NUM:123 | |||||||||
| valueColor=(r,g,b[,a]) | Sets the color of the value text. r, g, b, and a specify the the color and optional opacity as RGBA Values. The default is opaque black. | ||||||||
| valueBackColor=(r,g,b[,a]) | |||||||||
| Sets the background color under the value text. r, g, b, and a specify the the color and optional opacity as RGBA Values. | |||||||||
| valueBackColor=0 | Sets the background color under the value text to the default color, the standard document background color used on the current operating system, which is usually white. | ||||||||
| win=winName | Specifies which window or subwindow contains the named control. If not given, then the top-most graph or panel window or subwindow is assumed. | ||||||||
| When identifying a subwindow with winName, see Subwindow Syntax for details on forming the window hierarchy. | |||||||||
Flags
| /Z | No error reporting. | |
Details
The target window must be a graph or panel.
SetVariable Action Procedure
The action procedure for a SetVariable control takes a predefined WMSetVariableAction structure as a parameter to the function:
Function ActionProcName(SV_Struct) : SetVariableControl
STRUCT WMSetVariableAction &SV_Struct
...
return 0
End
The ": SetVariableControl" designation tells Igor to include this procedure in the Procedure pop-up menu in the SetVariable Control dialog.
See WMSetVariableAction for details on the WMSetVariableAction structure.
Although the return value is not currently used, action procedures should always return zero.
You may see an old format SetVariable action procedure in old code:
Function procName (ctrlName,varNum,varStr,varName) : SetVariableControl
String ctrlName
Variable varNum // value of variable as number
String varStr // value of variable as string
String varName // name of variable
...
return 0
End
This old format should not be used in new code.
Examples
Executing the commands:
Variable/G globalVar=99
SetVariable setvar0 size={120,20}
SetVariable setvar0 font="Helvetica", value=globalVar
creates a SetVariable control that displays the value of globalVar.
See Also
printf for an explanation of formatStr.
Controls and Control Panels for details about control panels and controls.
Control Panel Units for a discussion of the units used for controls.
The ControlInfo operation for information about the control.
The GetUserData function for retrieving named user data.