Commodore‎ > ‎BASIC‎ > ‎Keywords‎ > ‎

BOX

Keyword
Abbreviation Token (hex) Version(s) Classification
BOX B{Shift+O} E1 3.5 Command and Statement
BOX none  E1  7.0  Command and Statement 
ELSE E{Shift+L} E1 4.7 Preposition

Syntax  
BOX [  colorSource ] , { [ + | - ] xValA [ , [ + | - ] yValA ] distanceA ; angleA } [ , { [ + | - ] xValB [ , [ + | - ] yValB ] distanceB ; angleB } [ , [ rotation ] [ , fill ] ] ] 
 
Parameters Type Legal Value(s) Default Value Note(s)
colorSource Integer
0 or 1 (high-res)
0 to 3 (multi-color)
1
The actual color on-screen depends
on the colorSource assignment by COLOR
xValA Integer*  -32768 to +32767    rectangular X ordinate or offset for corner A
yValA Integer*  -32768 to +32767    rectangular Y ordinate or offset for corner A
distanceA Integer*  -32768 to +32767    polar distance for corner A 
angleA Unsigned Integer  0 to 65535     polar angle for corner A in clockwise degrees 
xValB Integer*  -32768 to +32767  pixel cursor X  rectangular X ordinate or offset for corner B
yValB  Integer*  -32768 to +32767  pixel cursor Y rectangular Y ordinate or offset for corner B 
distanceB Integer*  -32768 to +32767  polar distance for corner B 
angleB  Unsigned Integer  0 to 65535  undefined polar angle for corner B in clockwise degrees
rotation  Unsigned Integer  0 to 65535  rectangle rotation in clockwise degrees 
fill Integer 0 or 1    draw a solid/filled box if 1; only outline if 0
*Due to a bug in the original C128 ROMs (start-up message says (c)1985), only positive/unsigned values of 0 to 65535 may be used.
 
 
Purpose  
Draw a parallelogram (typically a rectangle) on the bitmap screen.

 
 
Remarks  
The first coordinate (following immediately after the optional colorSource) is required.  It defines one corner of the un-rotated box.  The second coordinate is optional; it defines the opposite corner of the un-rotated box.  If not specified, the second coordinate defaults to the pixel cursor (the last point calculated in the previous bitmap command).  Any specified coordinate(s) will be effected by SCALE if it is active.  The resulting value(s) may be off-screen, as long as they are legal values as shown above.
 
Without the optional rotation (or if it is specified as a multiple of 180), a rectangle will typically be drawn.  A true square will result only if a proper scaling of the X ordinate relative to the Y is used (this varies based on GRAPHIC mode and PAL/NTSC video).  Otherwise a rotated box (a "diamond") will be drawn.  Because of symmetry, only the rotation mod 180 is significant.  For example a rotation of 45 is effectively the same as a rotation of 225 or 405 (45 + 180*1 or 45 + 180*2).  In order to specify this value, the normally optional second coordinate must be specified (you can use +0,+0 to effectively use the default value).
 
The fill acts like a boolean flag: a value of 1 causes the box to be drawn solid ("filled"), and a value of 0 (the default) causes only an outline to be drawn ("hollow").  Unfortunately, BASIC won't accept its own boolean values!!  For example, BASIC returns -1 for true from relational operators, but if such a value is specified for fill an ILLEGAL QUANTITY ERROR is generated.  Use the ABS() function to fix this behavior.
 
If the BOX is not filled, then the width plotted on screen of all four line-segments is controlled by a secret BASIC variable.  That secret variable can be set with WIDTH.  If it is 1, each "dot" (of the line-segments) will be 1 pixel wide; if it is 2, each "dot" will be 2 pixels wide.
  
Strangely in all versions, negative angles are not allowed!  Try adding 360 (or 720) to fix this problem (this works for positive angles too).
 
Any floating-point numbers will first be converted to integers (see INT).  If any value is out-of-range (see above) an ILLEGAL QUANTITY ERROR is generated.  If no bitmap has been setup (see GRAPHIC), a NO GRAPHICS AREA is generated.
 
Example of optional colorSource and optional "Coordinate B":
DRAW 1,60,60: BOX ,100,100 : REM BOX 1, 100,100, 60,60
 
Example of relative rectangular and polar coordinate:
DRAW 1,60,60: BOX ,+10, -10 : REM BOX 1, 70,50, 60,60

READY.
DRAW 1,60,60: BOX , 20; 30 : REM ~BOX 1, 70,43, 60,60
 
Example of rotation and fill (these require the normally optional "Coordinate B"):
DRAW 1,60,60: BOX ,100,100, ,, 45 :REM try omit Coordinate B

?ILLEGAL QUANTITY ERROR
READY.
DRAW 1,60,60: BOX ,100,100, +0,+0, 45 :REM BOX 1,100,100, 60,60, 45, 0

READY.
BOX 1, 100,100, 60,60, ,1 :REM rotation omitted (no rotation), fill box
 
Compare With  
 
See Also  

© H2Obsession, 2014
Comments