CustomControl
CustomControl [/Z] ctrlName [ keyword = value [, keyword = value ...] ]
The CustomControl operation creates or modifies a custom control in the target window. A CustomControl starts out as a generic button, but you can customize both its appearance and its action.
Parameters
ctrlName is the name of the Custom Control to be created or changed. See Button for standard default parameters.
The following keyword=value parameters are supported:
| 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. | |||||||||
| fColor=(r,g,b[,a]) | Sets color of the button only when picture is not used and frame=1. | ||||||||
| r, g, b, and a specify the the color and optional opacity as RGBA Values. | |||||||||
| focusRing=fr | Enables or disables the drawing of a rectangle indicating keyboard focus: | ||||||||
| |||||||||
| frame= f | Sets frame style used only when picture is not used: | ||||||||
| |||||||||
| Set fColor to something other than black to colorize the button. | |||||||||
| |||||||||
| 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 a custom control's user-defined action procedure can attempt to resize the control or take other actions that could be in conflict with layout guide attachments. If the control uses a picture for the control, the picture may be distorted if the layout guides change the control's size. | |||||||||
| 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 background color for the control only when a picture is not used and frame is not 1. | |||||||||
| r, g, b, and a specify the the color and optional opacity as RGBA Values. If not set (or labelBack=0), then background is transparent (not erased). | |||||||||
| mode=m | Notifies the control that something has happened. Can be used for any purpose. See Details discussion of the kCCE_mode event. | ||||||||
| noproc | Specifies that no procedure is to execute when clicking the custom control. | ||||||||
| picture= pict | Uses the named Proc Picture to draw the control. Using this form of the picture keyword, the picture is taken to be three side-by-side frames, which show the control appearance in the normal state, when the mouse is down, and in the disabled state. | ||||||||
| The control action function can change the number of frames using the picture={pict,n } syntax. | |||||||||
| If the size keyword is not used when the control is created, the picture size sets the initial size of the control; the width is the picture width/3. Resizing the control will distort the picture. | |||||||||
| picture={pict,n } | Uses the specified Proc Picture to draw the control. The picture is n side-by-side frames instead of the default three frames. | ||||||||
| If the size keyword is not used when the control is created, the picture size sets the initial size of the control; the width is the picture width/n. Resizing the control will distort the picture. | |||||||||
| 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 name of the action function for the control. The function must not kill the control or the window. | ||||||||
| rename=newName | Gives the control a new name. | ||||||||
| size={width,height } | Sets size of the control in control panel units. If a picture is used, this may distort the picture. See the picture keyword. | ||||||||
| title=titleStr | Specifies text that appears in the control. | ||||||||
| 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=varName | Sets the numeric variable, string variable, or wave that is associated with the control. With a wave, specify a point using the standard bracket notation with either a point number (value=awave[4]) or a row label (value=awave[%alabel]). | ||||||||
| valueColor=(r,g,b[,a]) | Sets initial color of the title for the button drawn only when picture is not used and frame=1. | ||||||||
| 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. | |||||||||
Flags
| /Z | No error reporting. | |
Details
When you create a custom control, your action procedure gets information about the state of the control using the WMCustomControlAction structure. See WMCustomControlAction for details on the WMCustomControlAction structure.
Although the return value is not currently used, action procedures should always return zero.
When Igor calls your action procedure for the kCCE_draw event, the basic button picture (custom or default) will already have been drawn. You can use standard drawing commands such as DrawLine to draw on top of the basic picture. Unlike the normal situation when drawing commands merely add to a drawing operation list which only later is drawn, kCCE_draw event drawing commands are executed directly. The coordinate system, which you cannot change, is control panel units with (0,0) being the top left corner of the control. Most drawing commands are legal but because of the immediate nature of drawing, the /A (append) flag of DrawPoly is not allowed.
The kCCE_mode event, which Igor sends when you execute CustomControl with the mode keyword, can be used for any purpose, but it mainly serves as a notification to the control that something has happened. For example, to send information to a control, you can set a named (or the unnamed) userdata and then set the mode to indicate that the control should examine the userdata. For this signaling purpose, you should use a mode value of 0 because this value will not become part of the recreation macro.
The kCCE_frame event is sent just before drawing one of the pict frames, as set by the picture parameter. On input, the curFrame field is set to 0 (normal or mouse down outside button), to 1 (mouse down in button), or to 2 (disable). You may modify curFrame as desired but your value will be clipped to a valid value.
When you specify a pict with the picture parameter, you will get a kCCE_drawOSBM event when that pict is drawn into an offscreen bitmap. Once it is created, all updates use the offscreen bitmap until you specify a new picture parameter. Thus the custom drawing done at this event is static, unlike drawing done during the kCCE_draw event, which can be different each time the control is drawn. Because the pict can be contain multiple side-by-side frames, the width of the offscreen bitmap is the width derived from the ctrlRect field multiplied by the number of frames.
Because the action function is called in the middle of various control events, it must not kill the control or the window. Doing so will almost certainly cause a crash.
CustomControl Action Procedure
The action procedure for a CustomControl control takes a predefined structure WMCustomControlAction as a parameter to the function:
Function ActionProcName(s)
STRUCT WMCustomControlAction& s
...
return 0
End
See WMCustomControlAction for details on the WMCustomControlAction structure.
Although the return value is not currently used, action procedures should always return zero.
The action procedure may have drawing commands such as SetDrawEnv, DrawRect, etc. These commands include a /W flag that directs their action to a particular window or subwindow. However, in a CustomControl action procedure, the /W flag is ignored and all drawing commands are directed to the window or subwindow containing the control.
Because the action procedure runs during a drawing operation that cannot be interrupted without crashing Igor, the debugger cannot be invoked while it is running. Consequently breakpoints set in the function are ignored. Use Debugging with Print Statements instead.
Examples
See Creating Custom Controls for some examples of custom controls.
For a demonstration of custom controls, see the Custom Control Demo.pxp example experiment, which is located in your Igor Pro Folder in the Examples:Feature Demos 2: folder.
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.
TextBox, DrawPoly, DefaultGUIControls