QB64-PE/internal/help/CIRCLE.txt

The {{KW|CIRCLE}} statement is used in graphics {{KW|SCREEN (statement)|SCREEN}} modes to create circles, arcs or ellipses.



{{PageSyntax}}
: '''CIRCLE''' [{{KW|STEP}}]'''({{Parameter|Column}}, {{Parameter|Row}}), {{Parameter|radius%}}[, {{Parameter|colour%}}][,''' {{Parameter|startRadian!}}, {{Parameter|stopRadian!}}] [, {{Parameter|aspect!}}]


{{Parameters}}
* Can use [[STEP]] for relative coordinate moves from the previous graphic coordinates.
* Coordinates designate the center position of the circle. Can be partially drawn offscreen.
* {{Parameter|radius%}} is an [[INTEGER]] value for half of the total circle diameter.
* {{Parameter|colour%}} is any available color attribute in the {{KW|SCREEN (statement)|SCREEN}} mode used. 
* {{Parameter|startRadian!}} and {{Parameter|stopRadian!}} can be any {{KW|SINGLE}} value from 0 to 2 * pi to create partial circles or ellipses.
* ''aspect!'' [[SINGLE]] values of 0 to 1 affect the vertical height and values over 1 affect the horizontal width of an ellipse. Aspect = 1 is a normal circle.


''Usage:'' 
* When using {{Parameter|aspect!}} the {{Parameter|startRadian!}} and {{Parameter|stopRadian!}} commas MUST be included even if not used.
* Radians move in a counter clockwise direction from 0 to 2 * Pi. Zero and 2 * Pi are the same circle radian at 3 o'clock.
* Negative radian values can be used to draw lines from the end of an arc or partial ellipse to the circle center.
* Commas after the {{Parameter|colour%}} parameter are not required when creating a normal circle. Color can also be omitted.
* '''CIRCLE can be used in any graphic screen mode, but cannot be used in the default screen mode 0 as it is text only!''' 


''Example:'' Program illustrates how the CIRCLE command using a negative radian value can be used to create the hands of a clock.
{{CodeStart}} '' ''
{{Cl|CONST}} PI = 3.141593 'The mathematical value of PI to six places
{{Cl|DIM}} clock(60)             'A dimensioned array to hold 60 radian points
clockcount% = 15          'A counter to keep track of the radians

'* Start at radian 2*PI and continue clockwise to radian 0
'* Since radian 2*PI points directly right, we need to start clockcount%
'* at 15 (for 15 seconds).  The {{Cl|FOR...NEXT|FOR}}/{{Cl|NEXT}} loop counts backwards in increments
'* of 60 giving us the 60 second clock points.  These points are then stored
'* in the dimensioned array clock() to be used later.
'*
{{Cl|FOR...NEXT|FOR}} radian = 2 * PI {{Cl|TO}} 0 {{Cl|STEP}} -(2 * PI) / 60
    clock(clockcount%) = radian
    clockcount% = clockcount% + 1
    {{Cl|IF...THEN|IF}} clockcount% = 61 {{Cl|THEN}} clockcount% = 1
{{Cl|NEXT}} radian
'* Change to a graphics screen and draw the clock face
{{Cl|SCREEN}} 7
{{Cl|CLS}}
{{Cl|LOCATE}} 1, 1
{{Cl|COLOR}} 14, 0
{{Cl|PRINT}} "Ritchie's Clock"
{{Cl|COLOR}} 9, 0
{{Cl|PRINT}} "Uses {{Cl|CIRCLE}} to"
{{Cl|PRINT}} "draw hands!"
{{Cl|COLOR}} 8, 0
{{Cl|CIRCLE}} (160, 100), 110, 8 'circle with radius of 110 and dark gray
{{Cl|CIRCLE}} (160, 100), 102, 8 'circle with radius of 102 and dark gray
{{Cl|PAINT}} (265, 100), 8, 8 'fill between the two dark gray circles with gray
{{Cl|CIRCLE}} (160, 100), 110, 7 'circle with radius of 110 and light gray
'*
'* Get the current time from the QuickBASIC built in variable {{Cl|TIME$}}
'* Since {{Cl|TIME$}} is a string, we need to extract the hours, minutes and
'* seconds from it using {{Cl|LEFT$}}, {{Cl|RIGHT$}} and {{Cl|MID$}}. Then, each of these
'* extractions need to be converted to a numeric value using VAL and
'* stored in their respective variables.
'*
seconds% = {{Cl|INT}}({{Cl|VAL}}({{Cl|RIGHT$}}({{Cl|TIME$}}, 2))) 'extract seconds from {{Cl|TIME$}}
{{Cl|IF...THEN|IF}} seconds% = 0 {{Cl|THEN}} seconds% = 60 'array counts 1 to 60 not 0 to 59
previoussecond% = seconds% 'hold current second for later use
minutes% = {{Cl|INT}}({{Cl|VAL}}({{Cl|MID$}}({{Cl|TIME$}}, 4, 2))) 'extract minutes from {{Cl|TIME$}}
{{Cl|IF...THEN|IF}} minutes% = 0 {{Cl|THEN}} minutes% = 60 'array counts 1 to 60 not 0 to 59
previousminute% = minutes% 'hold current minute for later use
hours% = {{Cl|INT}}({{Cl|VAL}}({{Cl|LEFT$}}({{Cl|TIME$}}, 2))) 'extract hour from {{Cl|TIME$}}
{{Cl|IF...THEN|IF}} hours% >= 12 {{Cl|THEN}} hours% = hours% - 12 'convert from military time
{{Cl|IF...THEN|IF}} hours% = 0 {{Cl|THEN}} hours% = 12 'count from 1 to 12 not 0 to 11
previoushour% = hours% 'hold current hour for later use
'*
'* Start of main program loop
'*
{{Cl|DO}}
    {{Cl|IF...THEN|IF}} seconds% <> previoussecond% {{Cl|THEN}} 'has a second elapsed?
        {{Cl|LOCATE}} 22, 17 'print the time on the screen at
        {{Cl|PRINT}} {{Cl|TIME$}}; 'position 22, 17
        '* Since a second has elapsed we need to erase the old second hand
        '* position and draw the new position
     
        {{Cl|CIRCLE}} (160, 100), 100, 0, -clock(previoussecond%), clock(previoussecond%)
        {{Cl|CIRCLE}} (160, 100), 100, 15, -clock(seconds%), clock(seconds%)
        previoussecond% = seconds% 'hold current second for later use
        {{Cl|IF...THEN|IF}} minutes% <> previousminute% {{Cl|THEN}} 'has a minute elapsed?
            '* Since a minute has elapsed we need to erase the old hour hand position
            {{Cl|CIRCLE}} (160, 100), 90, 0, -clock(previousminute%), clock(previousminute%)
            previousminute% = minutes% 'hold current minute for later use
        {{Cl|END IF}}
        '*
        '* Draw the current minute hand position
        '*
        {{Cl|CIRCLE}} (160, 100), 90, 14, -clock(minutes%), clock(minutes%)
        {{Cl|IF...THEN|IF}} hours% <> previoushour% {{Cl|THEN}} 'has an hour elapsed?
            '* Since an hour has elapsed we need to erase the old hour hand position        
            {{Cl|CIRCLE}} (160, 100), 75, 0, -clock(previoushour% * 5), clock(previoushour% * 5)
            previoushour% = hours% 'hold current hour for later use
        {{Cl|END IF}}
        '*
        '* Draw the current hour hand position
        '*
        {{Cl|CIRCLE}} (160, 100), 75, 12, -clock(hours% * 5), clock(hours% * 5)
    {{Cl|END IF}}
    seconds% = {{Cl|VAL}}({{Cl|RIGHT$}}({{Cl|TIME$}}, 2)) 'extract time again and do all over
    {{Cl|IF...THEN|IF}} seconds% = 0 {{Cl|THEN}} seconds% = 60
    minutes% = {{Cl|VAL}}({{Cl|MID$}}({{Cl|TIME$}}, 4, 2))
    {{Cl|IF...THEN|IF}} minutes% = 0 {{Cl|THEN}} minutes% = 60
    hours% = {{Cl|VAL}}({{Cl|LEFT$}}({{Cl|TIME$}}, 2))
    {{Cl|IF...THEN|IF}} hours% >= 12 {{Cl|THEN}} hours% = hours% - 12
    {{Cl|IF...THEN|IF}} hours% = 0 {{Cl|THEN}} hours% = 12
{{Cl|LOOP}} {{Cl|UNTIL}} {{Cl|INKEY$}} <> "" 'stop program if user presses a key '' ''

{{CodeEnd}}
{{small|Circle clock - by Terry Ritchie  11/04/06}}


{{PageSeeAlso}}
* {{KW|STEP}}
* {{KW|LINE}}
* {{KW|SCREEN (statement)}}


{{PageNavigation}}