Draw method: Rendering commands

Clear

Syntax: Control.Draw 'Clear'

Erases the entire drawing area and fills it with the current Brush. (For a Printer object, it ejects the page instead). Note that this command does not delete saved commands associated with the control, so for efficiency and to avoid wasting memory you should not call this method repeatedly if the autoredraw property is 1. Alternatively you should use the Reset keyword to delete saved commands before calling Clear.

Bitmap (from file)

Syntax: Control.Draw 'Bitmap' Filename [[[Row Col] Height Width] Stretch]

Alternative keywords: 'Picture' or 'Icon'

Draws an image from a file on the control. The Filename parameter is the path to the file containing the image. Under Windows, this can be a Bitmap (.bmp), Windows metafile (.wmf), Icon (.ico) or JPEG (.jpg or .jpeg) image. Under MacOS, the supported formats include bitmaps and JPEGs, as well as MacOS PICT files and usually other formats such as TIFF and GIF. Under Linux, the supported types depend on the operating system version but will typically include .png .xpm .jpg .jpeg .ico and .bmp files. (To display all formats, your Windows or MacOS system may need an appropriate graphics converter or QuickTime module installed). APLX automatically caches the picture in memory, and releases it when it is no longer needed. If you display multiple copies of the same picture, only one copy will be loaded in memory.

The optional Row and Col parameters determine the top left corner on the control where the picture will be displayed.

Usually the picture is displayed at its natural size. The optional Height and Width parameters allow you to specify the size of the rectangle in which it is displayed. If the Stretch parameter is 0 or omitted, the picture is clipped to this size. If it is 1, the picture is stretched or shrunk to fit the specified height and width. (However, for Icons this parameter must be 0).

You can also draw multiple bitmaps with a single command by passing a nested vector of multiple Filename...Stretch parameters.

Bitmap (from APL variable)

Syntax: Control.Draw 'Bitmap' Array [[[Row Col] Height Width] Stretch]

Alternative keywords: 'Picture' or 'Icon'

This second form of the Bitmap command allows you to pass an APL array which contains the picture as a set of RGB color values. The Array parameter is a two-dimensional integer array. Each element contains a color value for the corresponding pixel. The color value is encoded as 256⊥Blue Green Red where each color value is in the range 0 to 255.

The other parameters are as described above.

You can also draw multiple bitmaps with a single command by passing a nested vector of multiple Array...Stretch parameters.

Circle

Syntax: Control.Draw 'Circle' Row Col Radius [[[[Aspect] StartAngle EndAngle] Border] TiltAngle]

Draws a circle, ellipse, arc, or pie slice. The figure is drawn with the current Pen and filled with the current Brush.

The Row and Col parameters determine the center of the circle or ellipse. The Radius parameter determines the radius of the circle or ellipse. If the Aspect parameter is 1 (default), the figure drawn will be a circle provided the current scale has the same units along both axes. If the Aspect parameter is greater than 0, the Radius parameter determines the radius along the horizontal axis, and the radius along the vertical axis is obtained by multiplying Radius by Aspect. If Aspect is less than 0, the Radius parameter determines the radius along the vertical axis and the radius along the horizontal axis is obtained by multiplying Radius by the absolute value of Aspect.

The optional StartAngle and EndAngle parameters are used for pie slices and arcs. They are measured in degrees, anti-clockwise from the right horizontal axis. The default is 0 360, i.e. a full circle or ellipse.

The Border parameter determines which lines are drawn with the Pen. It is the sum of:

1  Draw the circumference 
2  Draw the radius at the starting angle
4  Draw the radius at the end angle

The default is 1. If you don't want any line to be drawn, you can set Border to 0 or use a transparent Pen. If you don't want the figure to be filled, use a transparent Brush.

The final optional parameter, TiltAngle, allows you to specify that you want the figure rotated from the horizontal. It is expressed in degrees counter-clockwise from the right horizontal axis. The rotation is applied after all of the other parameters have been evaluated, so the radius along what would have been the horizontal axis becomes the radius along the line at TiltAngle degrees from the horizontal. (If you specify this parameter, drawing may be slower and the figure less precise than it would be if you omit it).

You can also draw multiple figures either by passing multiple enclosed vectors of 3 to 8 parameters, or by passing a matrix of 3 to 8 columns.

Chord

Syntax: Control.Draw 'Chord' Row Col Radius [[[[Aspect] StartAngle EndAngle] Border] TiltAngle]

Draws a chord (ie the intersection of a circle and a line). The figure is drawn with the current Pen and filled with the current Brush.

The parameters are the same as for Circle, except for the Border parameter, which is the sum of:

1  Draw the circumference 
2  Draw the intersecting line

You can also draw multiple chords either by passing multiple enclosed vectors of 3 to 8 parameters, or by passing a matrix of 3 to 8 columns.

Ellipse

Syntax: Control.Draw 'Ellipse' Row Col Height Width

Draws a circle or ellipse. The figure is drawn with the current Pen and filled with the current Brush.

This is similar to the Circle command, but only complete circles/ellipses can be drawn and the size of the figure is expressed in a different way. The Row and Col parameters determine the top, left of the rectangle which just contains the figure. The Height and Width parameters determine the size of the containing rectangle.

You can draw multiple figures by passing a nested vector of 4-element parameters, or by passing an N by 4 matrix.

Line

Syntax: Control.Draw 'Line' Points

Draws one or more connected lines using the current Pen.

The Points parameter is an N by 2 numeric matrix describing the points to be connected, where N is at least 2. The first column represents the Rows, and the second column the Columns.

You can also draw multiple series of lines in one command by passing multiple sets of Points arrays.

Seg

Syntax: Control.Draw 'Seg' Array [Array, Array...]

Draws one or more sets of connected lines (without polygon fill) in one operation, using the current Pen.

The argument comprises one or more M by N matrices of: Y1 X1 Y2 X2... Each row of the matrix corresponds to one set of connected lines. Points are taken in pairs from each row, so N must be even, and the sets of lines in each array must have the same number of segments.

This method is provided mainly for compatibility with APL+Win. You can achieve the same effect in a more flexible manner by supplying a nested argument to the Line keyword.

Poly

Syntax: Control.Draw 'Poly' Points

Draws a polygon using the current Pen, and fills the polygons using the current Brush.

The Points parameter is an N by 2 numeric matrix describing the points to be connected, where N is at least 3. The first column represents the Rows, and the second column the Columns. APLX automatically draws the last line to connect the last point to the first. For complex shapes, the Mode command specifies the algorithm used to determine which regions of the polygon are filled.

If you don't want the polygon to be filled, use a transparent brush.

You can also draw multiple polygons in one command by passing multiple sets of Points arrays.

Rect

Syntax: Control.Draw 'Rect' Row Col Height Width [RoundingV RoundingH]

Draws a rectangle or round-cornered rectangle. The rectangle is drawn with the current Pen and filled with the current Brush.

The Row and Col parameters determine the top, left of the rectangle, and the Height and Width parameters determine its size. For a round-cornered rectangle, the RoundingV and RoundingH parameters determine the diameter of the corners in the vertical and horizontal directions respectively.

You can also draw multiple rectangles in one command by passing a nested vector of 4- or 6-element parameters, or by passing an N by 4 or 6 matrix.

Text

Syntax: Control.Draw 'Text' String Row Col

Draws a text string in the current Font.

The String parameter is a character vector or matrix containing the text to be written. It can contain embedded carriage return (⎕R) characters. If it is a matrix, carriage returns are automatically inserted at the end of each line. The Row and Col parameters determine the starting position. Text can be written at an angle by setting the angle using the Font command.

TextSize

Syntax: R ← Control.Draw 'TextSize' String [String, String..]

Alternative keyword: '?Text'

Determines the size required to render one or more text strings in the current Font.

The argument comprises one or more character scalars, vectors or matrices. If only one string is supplied, the result is a 2-element numeric vector containing the height and width required to draw the string with the currently-selected font, in the current Draw scale. If more than one string is supplied, the result is a nested vector with one element per string. Each element is a two-element vector giving the height and width required for the corresponding string.