Draw method: State commands

Default

Syntax: Control.Draw 'Default'

Sets the Font, Pen, Brush and Scale to the default values for further draw commands, but does not delete the existing saved sequence of commands. The default Pen is a black solid line of 1 pixel width. The default Brush is the window background color. The default Font is Arial 10 point, plain style. The default text foreground color is black and the default text writing mode is transparent. The draw-method scale is set to the scale of the parent object at the time when the Draw method was first used.

Scale

Syntax 1: Control.Draw 'Scale' Value
Syntax 2: Control.Draw 'Scale' Height Width
Syntax 3: Control.Draw 'Scale' Top Left Height Width
Syntax 4: Control.Draw 'Scale' 0 Top Left Height Width

Sets the Draw-method scale for further drawing commands.

When the Draw method is first used on a control or window, the Draw-method scale is set to be the same as the scale property of the control or window. The top, left of the drawing area is at position 0 0, and the coordinates increase in the downwards and rightwards directions. Subsequent changes to the scale property of the control or window have no effect on the Draw method, but you can use the 'Scale' keyword in the Draw method to select a different scale for subsequent Draw method commands.

In the first syntax form shown above, the Value parameter selects one of the standard scales:

1. Use 'character' units. A character unit has the same height as a line of text in the default system font (16 points), and the width of a typical character (8 points). In this case the vertical and horizontal scales are different.
2. Use 'dialog' units, (1/8 system-font high, 1/4 system-font wide)
3. Use point units (nominally 72 points per inch)
4. Use 'twips' units (nominally 1440 twips per inch)
5. Use pixel units (also usually 72 per inch on the Macintosh), but this depends on the resolution and screen size.
6. Use nominal millimetres. Depending on the screen size, this may not be accurate for controls displayed on a screen, but it should be accurate when printing on paper (provided the printer driver is set up correctly).
7. (Applicable to Chart objects only) Use the same scale as the axes of the Chart. This is very useful for applying Draw method commands to a chart, for example to add lines showing confidence limits or annotate certain values with text. By using scale 7, you can ensure that the Draw commands always match the chart even if it is resized or re-scaled.

In the remaining syntax forms, the scale is proportional to the window or control size. The Height and Width parameters are used to indicate the number of units corresponding to the height and width of the window or control. For example, if Height is 200 and Width is 400, then the scale will be such that there are 200 vertical units between the top and bottom of the window, and 400 units across. This will remain true even if the window is resized, i.e. the scale is proportional to the window size, so that the graphic will be shrunk or stretched automatically when the window is re-drawn.

If the Top and Left parameters are supplied, the drawing origin is shifted such that these parameters correspond to the top left point of the drawing area.

Note that you can specify negative parameters for any of Height Width Top or Bottom. If you use a negative value for Height or Width, it changes the direction of the coordinate system. For example, the command

      Win.Draw 'Scale' 100 0 ¯100 200

sets the bottom left of the window to be row 0 column 0. The top left of the window is row 100 column 0. The bottom right of the window is row 0 column 200. The direction of the vertical axis has been reversed to be upwards.

Pen

Syntax: Control.Draw 'Pen' Style [[Color] Size]

Sets the Pen for further drawing commands.

The Style parameter is one of 0=Transparent, 1=Solid, 2=Insideframe, 3=Dash, 4=Dot, 5=DashDot, 6=DashDotDot. Default 1. Note: Under MacOS, dashed or dotted lines do not display consistently unless they are either horizontal or vertical.

The Color parameter can either be a single integer being the RGB values encoded 256⊥Blue Green Red where each color value is in the range 0 to 255, or separate Red Green Blue values in the range 0 to 255. Default 0 0 0 (Black)

The Size parameter is the pen width. (Default 1). If it is greater than 1, the Style must be 1.

Brush

Syntax 1: Control.Draw 'Brush' Style [Color]
Syntax 2: Control.Draw 'Brush' ¯2 FileName

Sets the Brush for further drawing commands.

In the first form, the Style parameter is one of 0=Transparent, 1=Solid, 2=Horizontal grid pattern, 3=Vertical grid pattern, 4=Forward diagonal, 5=Backward diagonal, 6=Cross pattern, 7=Diagonal cross patterns. Default 1.

The Color parameter can either be a single integer being the RGB values encoded 256⊥Blue Green Red where each color value is in the range 0 to 255, or separate Red Green Blue values in the range 0 to 255. Default 0 0 0 (Black)

You can also set the Style parameter to ¯2, as shown in the second form above. In this case it should be followed by the name of a bitmap file, which will be used as the background fill pattern. (Note: APLX automatically caches this bitmap for you and releases it when it is no longer needed. There is no need for the APL programmer to obtain a bitmap handle and free it explicitly).

Color

Syntax: Control.Draw 'Color' Color

Sets the foreground (and optionally background) color for further text drawing commands.

The Color parameter can either be a single integer being the RGB values encoded 256⊥Blue Green Red where each color value is in the range 0 to 255, or separate Red Green Blue values in the range 0 to 255. The default is 0 0 0 (Black).

If you want to specify the background color as well, you can provide two encoded integers, or a length 6 vector of two sets of RGB values. In this case the text foreground color is the first color you specify, and the background color is the second. Note that the background color will not be used if the current text mode is transparent - see the Mode command.

Font

Syntax: Control.Draw 'Font' Name [[[[Size] Style] Charset] Angle]

Sets the font for further text drawing commands. The parameters are the same as for the normal font property, with the addition of an optional drawing Angle. This is expressed in units of one tenth of a degree, anticlockwise from the horizontal. (This parameter is ignored under MacOS 8 and 9.) If any parameter is an empty vector, it is left unchanged.

Mode

Syntax: Control.Draw 'Mode' Opaque [[Mode] PolyType]

Sets the drawing mode for further drawing and text commands.

The Opaque parameter is 0 for transparent text and 1 for opaque text, or ¯1 to indicate 'leave unchanged'. The default is transparent. If you set Opaque to 1, text will be drawn with the background color selected using the Color command.

The Mode parameter is an integer in the range 1 to 16, or ¯1 to indicate 'leave unchanged'. It determines how pixels drawn using the Brush or Pen interact with the existing pixels in the window. The exact meaning of the values depends on the system on which APLX is running; they are mapped so that the most useful ones give rise to similar effects under MacOS, Windows and Linux. The possible values and the resulting pixels which appear on the window are:

In practice, the values you are likely to find useful are:

• 13 (default): Replace the destination pixel with the drawn pixel
• 7: Draw using the XOR operation, which is reversible. Draw again, and the figure will be removed. This is useful for 'rubber banding' or temporary outlines of shapes.

Under Windows, the PolyType parameter determines the algorithm used for filling of complex polygon shapes. If it is 0, the 'alternate' algorithm is used. If 1, the 'Winding' algorithm applies. It is ignored under MacOS and Linux.