Button

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

The Button operation creates or modifies the named button control in the target window.

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

Parameters

ctrlName is the name of the Button 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 =default: The appearance is determined by the DefaultGUIControls command. kind =native: Creates standard-looking controls for the current computer platform. kind =os9: Igor Pro 5 appearance (quasi-Macintosh OS 9 controls). platform =Mac: Changes the appearance of controls on Macintosh computers running Igor 9 or earlier. platform =Win: Changes the appearance of controls on Windows computers. platform =All: Changes the appearance of controls on Windows computers and on Macintosh computers running Igor 9 or earlier.
disable=d	Sets the state of the control. d is a bit field: bit 0 (the least significant bit) is set when the control is hidden. Bit 1 is set when the control is disabled:
	d =0: Normal (visible), enabled. d =1: Hidden. d =2: Visible and disabled. Drawn in grayed state, also disables action procedure. d =3: Hidden and disabled.
	See the ModifyControl example for setting the bits individually.
fColor=(r,g,b[,a])	Sets color of the button. r, g, b, and a specify the color and optional opacity as RGBA Values. While accepted as an input, a has no effect.
	Specify fColor=(0,0,0) to get the default button color. If you want a black button use fColor=(1,1,1). To get the default blue button appearance, use fColor(0,0,65535).
To set the color of the title text, see valueColor.
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).
font="fontName "	Sets font, e.g., font="Helvetica".
fsize=s	Sets font size.
fstyle=fs	Specifies the font style. fs is a bitwise parameter with each bit controlling one aspect of the font style as follows:
	Bit 0: Bold Bit 1: Italic Bit 2: Underline Bit 4: Strikethrough
	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. Of the three horizontal or vertical anchor points, at most two may be attached to layout guides. Attaching one of the three causes a control to move as the layout guide moves. Attaching two causes a control to both move and resize. Thus, the name kwNone will appear at least twice.
	Using kwNone for all anchor points results in completely detaching a control from the layout guides.
	Note that if you set a picture for the button's appearance, attachments to layout guides that cause the button to change size will distort the picture.
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 for the control when using a picture to define the appearance of the button (see the picture keyword).
	The labelBack keyword was added in Igor Pro 9.00.
	r, g, b, and a specify the the color and optional opacity as RGBA Values.
	For transparency to work, the picture must be inherently transparent. For example, each pixel in a PNG picture has its own internal alpha value so it can be inherently transparent or inherently opaque.
	If you want the button background to be actually transparent, use the labelBack color to set the background color of the picture. In most cases, use transparent white: labelBack=(65535, 65535, 65535, 0).
	If you omit labelBack or specify labelBack=0 then the button background color is the background color of the window in which the button is drawn.
noproc	Specifies that no procedure is to execute when clicking the button.
picture= pict	Draws the button using the named picture. The picture is taken to be three side-by-side frames that show the control appearance in the normal state, when the mouse is down, and in the disabled state. The picture may be either a global (imported) picture or a Proc Picture (see Proc Pictures).
	By default, the button's rectangle is filled with the background color of the window it is drawn in before the picture is drawn. You can use the labelBack keyword to control the button's background color and transparency.
	In Igor 6, the size keyword is ignored when a picture is used with a button control. To make it easier to size graphics for high-resolution screens, as of Igor 7, the size keyword is respected in this case.
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 button in control panel units.
proc=procName	Specifies the name of the procedure to execute when clicking the button.
rename=newName	Gives button a new name.
size={width,height }	Sets width and height of button in control panel units.
title=titleStr	Sets title of button to the specified string expression. The title is the text that appears in the button. If not given then title will be "New". If you use "" the button will contain no text.
	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.
valueColor=(r,g,b[,a])	Sets initial color of the button's text (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.
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.

Button Action Procedure

The action procedure for a Button control takes a predefined structure WMButtonAction as a parameter to the function:

Function ActionProcName(B_Struct) : ButtonControl
	STRUCT WMButtonAction &B_Struct
	...
	return 0
End

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

See WMButtonAction for details on the WMButtonAction structure.

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

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

Function procName (ctrlName) : ButtonControl
	String ctrlName
	...
	return 0
End

This old format should not be used in new code.

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.

Demos

Open All Controls Demo