Classes | GUI > Views

UserView : View : QObject : Object

A custom drawn view using Pen
Subclasses: QUserView


An empty view on which you can draw using the Pen class.

This view displays and does nothing by itself, but allows you to define how it will be drawn, and expects you to define its entire mode of interaction using mouse, key, and drag and drop actions.

To define how the view is drawn you set the -drawFunc variable to a Function within which you can use the Pen class to draw graphical primitives, such as lines, rectangles, ellipses, curves, and also text.

This class offers convenient mechanisms for creating animations, that is, to automatically redraw itself in regular time intervals. See the Animation section of this document.

For a guide to using this view, see Introduction to GUI: Custom views.

NOTE: Older tutorials might recommend subclassing UserView. Don't do that. Use composition, not inheritance. Make the UserView a property of your custom view class.

Class Methods

Inherited class methods

Undocumented class methods, bounds)



Instance Methods



.drawFunc = aFunction

Sets the Function to evaluate whenever the view is asked to redraw itself. This may be, for example, due to being hidden and shown again, being resized, another view moving on top of it, or after the View: -refresh method has been called.

Within that Function you are allowed to use the Pen class to draw within the bounds of the view. All the coordinates given to the methods of Pen are relative to the top-left corner of the view. Usage of Pen is not allowed outside of that Function.

The Function will be passed this view as the argument when evaluated.



A Function.


.background = color

From superclass: View

Sets the color used to fill the whole area occupied by the view below the drawing done in -drawFunc. You can set the background at any moment, even within the drawFunc, but any drawing done in that Function will always be displayed on top of the background.



A Color.


.drawingEnabled = boolean

Whether the -drawFunc will be called when the view is redrawing itself. Note that -background will be painted regardless of this variable.

The default value is true.



A Boolean.


.clearOnRefresh = boolean

Whether the view shall clear the last drawing done in -drawFunc before being redrawn.

If this is false, the view will continuously draw on top of all the previous drawing whenever it is redrawn, until -clearDrawing is called.

The default value is true.



A Boolean.


If -clearOnRefresh is false, you can call this method to manually clear any drawing done in -drawFunc so far.



.animate = bool

Whether the view shall redraw itself internally at a regular time interval (frame rate). See -frameRate for the way to adjust that interval.

The default value is false.



A Boolean.


.frameRate = fps

The interval at which the view regularly redraws itself, if -animate is true. You can change the desired frame rate by setting this variable.

The default frame rate is 60fps.

NOTE: Getting the value of this variable will return the average actual frame rate. If it is lower than the desired frame rate set as described above, that implies that the view tries but does not manage to redraw itself at that frame rate. The reason may typically be that the drawing defined in -drawFunc is computationally too demanding for the system.



A Float defining the interval between frames of animation, in frames per second.


The count of frames drawn while -animate is true; it will increase by 1 every time the view is redrawn.

If animation is stopped and started again (by setting animate to false and then true again), the frame count is restarted.


An Integer.


The UserView by itself does not respond to any interaction by the user. You can define the modes of interaction entirely on your own using mouse and keyboard actions. See Actions and Hooks for detailed explanation.

Note that there is no default mode of interaction with the UserView, so View: -action will never be triggered, if you don't implement that yourself.

Inherited instance methods

Undocumented instance methods


.action = func

From superclass: View



.drawHook = func

From extension in /SuperCollider/Contents/Resources/SCClassLibrary/Common/GUI/backwardsCompatibility/


'Introduction to GUI' contains an example with elaborate explanation on how to use UserView. Below are further examples.

Basic Usage

Resize the window or click on the UserView to refresh the drawing:

Coordinates are relative to the UserView. Try resizing the window:

Responding to mouse clicks and movement

Using mouse actions you can make UserView change the way it is drawn in response to mouse interaction. The sequence of examples below will guide you through the various possibilities.

Clicking and moving the mouse on each of the painted squares in the following example will redraw them differently. See interpreter output for posted information that you can use in the mouse actions.

The following example uses the -clearOnRefresh option to prevent the UserView from clearing its contents when redrawn. Clicking and moving the mouse within each square will draw ever more arcs on top of each other.

The following example uses the -clearOnRefresh option to keep the old contents when redrawn, allowing you to draw a line which follows the mouse cursor by clicking and dragging on the view.

It also uses the mouse position to compute the color of the line.


The following is an animation with mouse interaction. Click and drag in the view to move the center of the rotating object.

A simple ball animation:

An animation that makes a good use of the -clearOnRefresh option to keep the old contents when redrawing.

Usage of refreshInRect(aRect)

NOTE: This functionality is only available in Cocoa GUI

The refreshInRect method constrains the receiver's refresh area to the rectangle passed in aRect. You may use Quartz Debug's flash screen updates to see the refresh area of the view