Q(uick)BASIC Statement: CIRCLE

Quick View

CIRCLE

A graphics statement that draws an ellipse or circle with a specified center and radius

Worth knowing

Useful and cross-version information about the programming environments of QBasic and QuickBasic.

Syntax
  • CIRCLE [STEP] (x!,y!),radius![,[color%] [,[start!] [,[end!] [,aspect!]]]]
Description/Parameter(s)
STEP Specifies that coordinates are relative to the current graphics cursor position.
(x!,y!) The coordinates for the center of the circle or ellipse.
radius! The radius of the circle or ellipse in the units of the current coordinate system, determined by the most recent SCREEN, VIEW, and WINDOW statements.
color% A color attribute that sets the circle's color. The available color attributes depend on your graphics adapter and the screen mode set by the most recent SCREEN statement.
start! The starting angle for the arc, in radians.
end! The ending angle for the arc, in radians.
aspect! The ratio of the length of the y axis to the length of the x axis, used to draw ellipses.
  • To convert from degrees to radians, multiply degrees by (PI / 180).
Example

This example requires a color graphics adapter.

SCREEN 2 CIRCLE (320, 100), 200 CIRCLE STEP (0,0), 100
Syntax
  • CIRCLE [STEP] (x,y),radius[,[color][,[start][,[end][,aspect]]]]
Description/Parameter(s)
STEP The STEP option specifies that x and y are offsets relative to the current graphics cursor position.
x,y The x and y coordinates for the center of the circle or ellipse.
radius The radius of the circle or ellipse in the current coordinate system.
color The attribute of the desired color. The default color is the foreground color. See the COLOR statement details and the SCREEN statement details for more information on how to specify a color in different display screen modes.
start, end The start and end angles, in radians, for the arc to draw. The start and end arguments are used to draw partial circles or ellipses. The arguments may range in value from -2PI radians to 2PI radians, where PI= 3.141593. The default value for start is 0 radians. The default value for end is 2PI radians.
If start or end is negative, then CIRCLE draws a radius to that point on the arc and treats the angle as if it were positive.
The start angle can be less than the end angle. If you specify end but not start, the arc is drawn from 2PI to end; if you specify start, but not end, the statement draws an arc from start to zero.
aspect The aspect ratio, or the ratio of the y radius to the x radius. The default value for aspect is the value required to draw a round circle in the screen mode. This value is calculated as follows:
  • 4 * (ypixels/xpixels)/3
where xpixels by ypixels is the screen resolution. For example, in screen mode 1, where the resolution is 320 x 200, the default for aspect would be:
  • 4 * (200/320)/3, or 5/6.
If the aspect ratio is less than one, radius is the x radius. If aspect is greater than one, radius is equal to the y radius.

To draw a radius to angle 0 (a horizontal line segment to the right), do not give the angle as -0; use a very small nonzero value instead as shown:

  • ' Draws a pie-shaped one-quarter wedge of a circle:
  • SCREEN 2
  • CIRCLE (200,100),60,,-.0001,-1.57

You may omit an argument in the middle of the statement, but you must include the argument's commas. In the following statement, the color argument has been omitted:

  • CIRCLE STEP (150,200),94,,0.0,6.28

If you omit the last argument, you do not include the commas.

The last point that CIRCLE references, after drawing, is the center of the ellipse or circle. You may use coordinates that are outside the screen or viewport.

You may show coordinates as absolutes, or you may use the STEP option to show the position of the center point in relation to the previous point of reference. For example, if the previous point of reference is (10,10), then the following statement causes a circle to be drawn with radius 75 and center offset 10 from the current x coordinate and 5 from the current y coordinate. The circle's center is (20,15).

  • CIRCLE STEP (10,5), 75
Example

The following program first draws a circle with the upper left quarter missing. It then uses relative coordinates to position a second circle within the missing quarter circle. Finally, it uses a different aspect ratio to draw a small ellipse inside the small circle.

CONST PI=3.141593 SCREEN 2 ' Draw a circle with the upper-left quarter missing. ' Use negative numbers so radii are drawn. CIRCLE (320,100), 200,, -PI, -PI/2 ' Use relative coordinates to draw a circle within the missing ' quarter. CIRCLE STEP (-100,-42),100 ' Draw a small ellipse inside the circle. CIRCLE STEP(0,0), 100,,,, 5/25 ' Display the drawing until a key is pressed. LOCATE 25,1 : PRINT "Press any key to end."; DO LOOP WHILE INKEY$=""
Syntax
  • CIRCLE [STEP] (x!,y!),radius![,[color&] [,[start!] [,[end!] [,aspect!]]]]
Description/Parameter(s)
STEP Enables use of relative coordinates.
(x!,y!) The screen coordinates for the center of the circle or ellipse.
radius! A numeric expression; length of radius along x-axis, measured in pixels.
color& An integer expression; color code appropriate to the SCREEN mode and installed graphics adapter.
start!,end! Specify the start and end points of an arc as angles relative to the horizontal, in radians.
aspect! A numeric expression; used to draw ellipses or elliptical arcs (default is circle).
  • The argument radius! is measured in units of the current coordinate system, which is determined by the most recently executed SCREEN statement, along with any VIEW or WINDOW statements.
  • The argument color& is the attribute of the desired color. The default color is the foreground color. See the COLOR Statement Details and the SCREEN Statement Details for more information on how to specify a color in different display screen modes.
  • The arguments start! and end! are the start and end angles, in radians, for the arc to draw. They can range from -2PI radians to 2PI radians, where PI รท 3.141593. The default value for start! is 0 radians. The default value for end! is 2PI radians. To convert values from degrees to radians, multiply the angle (in degrees) by PI/180 (which is approximately equal to 0.0174532925199433).
  • The argument aspect! is the ratio of the y radius to the x radius. The default value for aspect! is the value required to draw a round circle in the screen mode.

Usage Notes

  • If start! or end! is negative, CIRCLE draws a radius to start! and treats the angle as positive. If end! is negative, CIRCLE draws a radius to end! and treats the angle as positive. If both start! and end! are negative, CIRCLE draws a radius to both start! and end! and treats the angle as positive.
  • The start angle can be less than the end angle. If you specify end! but not start!, the arc is drawn from 0 to end; if you specify start!, but not end!, the statement draws an arc from start! to 2 PI.
  • The aspect ratio is calculated as follows, where xpixels by ypixels is the screen resolution:

  • aspect = 4 * (ypixels / xpixels) / 3

  • If the aspect ratio is less than one, radius! is the x radius. If aspect! is greater than one, radius! is equal to the y radius.
  • To draw a radius to angle 0 (a horizontal line segment to the right), do not give the angle as -0; use a very small non-zero value instead as shown:

  • ' Draws a pie-shaped one-quarter wedge of a circle:
  • SCREEN 2
  • CIRCLE (200, 100), 60, , -.0001, -1.57

  • You can omit an argument in the middle of the statement, but you must include the argument's commas. If you omit a trailing argument, do not include its corresponding commas. In the following statement, color has been omitted:

  • CIRCLE STEP(150, 200), 94, , 0!, 6.28

  • The CIRCLE statement updates the graphics cursor position to the center of the ellipse or circle.
  • You can use coordinates that are outside the screen or viewport.
  • You can show coordinates as absolutes, or you can use the STEP option to show the position of the center point in relation to the previous point of reference. For example, if the previous point of reference were (10,10), then the following statement would draw a circle with radius 75 and center offset 10 from the current x coordinate and 5 from the current y coordinate. The circle's center would be (20,15).

  • CIRCLE STEP(10, 5), 75
Example

This example uses the CIRCLE statement to draw a circle with the upper-left quarter missing; to position, using relative coordinates, a second circle within the missing quarter; and using a different aspect ratio, to draw a small ellipse inside the small circle.

CONST PI = 3.141593 SCREEN 2 'Draw a circle with the upper-left quarter missing. 'Use negative numbers so radii are drawn. CIRCLE (320, 100), 200, , -PI, -PI / 2 'Use relative coordinates to draw a circle within the missing quarter. CIRCLE STEP(-100, -42), 100 'Draw a small ellipse inside the circle. CIRCLE STEP(0, 0), 100, , , , 5 / 25 'Display the drawing until a key is pressed. LOCATE 25, 1: PRINT "Press any key to end."; DO LOOP WHILE INKEY$ = ""