CheckBox

CheckBox [/Z] ctrlName [ keyword = value [, keyword = value ...] ]

The CheckBox operation creates or modifies a checkbox, radio button or disclosure triangle in the target or named window which must be a graph or control panel.

ctrlName is the name of the checkbox.

For information about the state or status of the control, use the ControlInfo operation.

Parameters

The following keyword=value parameters are supported:

ctrlName is the name of the CheckBox control to be created or changed.

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.
disable=d	Sets user editability of the control.
	d=0: Normal. d=1: Hide. d=2: Disable user input.
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:
	fr=0: Focus rectangle will not be drawn. fr=1: Focus rectangle will be drawn (default).
fsize=s	Sets font size for checkbox.
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. Both the width and height of a checkbox control are set by the font and font size and the length of the title. Consequently, only one anchor may be attached to layout guides in each direction, as attaching two anchor points would most likely result in an attempt to resize the checkbox control.
	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
	Sets the background color of the CheckBox.
	The labelBack keyword was added in Igor Pro 9.00.
	r, g, b, and a specify the color and optional opacity as RGBA Values.
	If you omit labelBack or specify labelBack=0, then the background color is that of the window in which the CheckBox is drawn.
mode=m	Specifies checkbox appearance.
	m =1: Display as a radio button control. m =0: Default checkbox appearance.
m =2:	Display as a treeview expansion node.
noproc	Specifies that no procedure is to execute when the checkbox is clicked.
picture= pict	Draws the checkbox using the named picture. The picture is taken to be six side-by-side frames which show the control appearance in the normal state, when the mouse is down, and in the disabled state. The first three frames are used when the checked state is false and the next three show the true state. The picture may be either a global (imported) picture or a Proc Picture (see Proc Pictures).
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 checkbox in control panel units.
proc=procName	Specifies the procedure to execute when the checkbox is clicked.
rename=newName	Gives checkbox a new name.
side=s	s =0: Checkbox is on the left, title is on the right (default). s =1: Checkbox is on the right, title is on the left.
size={width,height }	Sets width and height of control in control panel units.
title=titleStr	Sets title of checkbox to the specified string expression. The title is the text that appears in the checkbox. If not given or if "" then title will be "New".
	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=v	Specifies whether the checkbox is selected (v =1) or not (v =0).
variable=varName	Specifies a global numeric variable to be set to the current state of a checkbox whenever it is clicked or when it is set by the value keyword. The variable is two-way: setting the variable also changes the state of the checkbox.
wave=waveName	Specifies a point from a wave to be set to the current state of a checkbox when it is clicked or when it is set by the value keyword. 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. This feature was added in Igor Pro 9.00.
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.

Checkbox Action Procedure

The action procedure for a CheckBox control takes a predefined structure WMCheckboxAction as a parameter to the function:

Function ActionProcName(CB_Struct) : CheckBoxControl
	STRUCT WMCheckboxAction &CB_Struct
	...
	return 0
End

The ": CheckBoxControl" designation tells Igor to include this procedure in the Procedure pop-up menu in the CheckBox Control dialog.

See WMCheckboxAction for details on the WMCheckboxAction structure.

Although the return value is not currently used, action procedures should always return zero.

You may see an old format checkbox action procedure in old code:

Function procName (ctrlName,checked) : CheckBoxControl
	String ctrlName
	Variable checked	// 1 if selected, 0 if not
	...
	return 0
End

This old format should not be used in new code.

When using radio button controls, it is the responsibility of the Igor programmer to turn off other radio buttons when one of a group of radio buttons is pressed.

Examples

// Create a radio button group

Window Panel0() : Panel
	PauseUpdate; Silent 1		// building window...
	NewPanel /W=(150,50,353,212)
	Variable/G gSelectedRadioButton = 1
	CheckBox radioButton1,pos={52,25},size={78,15},title="Radio 1",value= 1,mode=1,proc=MyRadioButtonProc
	CheckBox radioButton2,pos={52,45},size={78,15},title="Radio 2",value= 0,mode=1,proc=MyRadioButtonProc
	CheckBox radioButton3,pos={52,65},size={78,15},title="Radio 3",value= 0,mode=1,proc=MyRadioButtonProc
EndMacro

static Function HandleRadioButtonClick(controlName)
	String controlName
	
	NVAR gSelectedRadioButton = root:gSelectedRadioButton

	strswitch(controlName)
		case "radioButton1":
			gSelectedRadioButton = 1
			break
		case "radioButton2":
			gSelectedRadioButton = 2
			break
		case "radioButton3":
			gSelectedRadioButton = 3
			break
	endswitch
	CheckBox radioButton1, value = gSelectedRadioButton==1
	CheckBox radioButton2, value = gSelectedRadioButton==2
	CheckBox radioButton3, value = gSelectedRadioButton==3
End

Function MyRadioButtonProc(cb) : CheckBoxControl
	STRUCT WMCheckboxAction& cb
	
	switch(cb.eventCode)
		case 2:		// Mouse up
			HandleRadioButtonClick(cb.ctrlName)
			break
	endswitch

	return 0
End

See Also

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.