## 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 `Dr`aw 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:

Value | Effect under Windows/Linux | Effect under MacOS
1 | Pixels are replaced with Black | Pixels are replaced with Black
2 | Inverse of the logical OR of the drawn pixel color and existing pixel color | Not implemented
3 | Logical AND of the existing pixel color and inverse of the drawn pixel color | Not implemented
4 | Inverse of drawn pixel color | Where the pen or brush pattern is 1, the existing pixel is unchanged. Where it is 0, the pen or brish color is used
5 | Logical AND of the drawn pixel color and inverse of the existing pixel color | Not implemented
6 | Inverts the current pixel color | Not implemented
7 | Logical XOR of the drawn pixel color and existing pixel color | Where the pen or brush pattern is l, the existing pixel is inverted. Where it is 0, it is unchanged
8 | Inverse of the logical AND of the drawn pixel color and existing pixel color | Not implemented
9 | Logical AND of the drawn pixel color and existing pixel color | Not implemented
10 | Inverse of the XOR of the drawn pixel color and existing pixel color | Where the pen or brush pattern is 1, existing pixel is unchanged. Where it is 0, it is inverted
11 | Existing pixels are unchanged | Existing pixels are unchanged
12 | Logical OR of existing pixel color and inverse of drawn pixel color | Not implemented
13 (default) | Pixels are replaced with drawn pixel color | Pixels are replaced with drawn pixel color
14 | Logical OR of drawn pixel color and inverse of existing pixel color | Not implemented
15 | Logical OR of drawn pixel color and existing pixel color | Not implemented
16 | Pixels are replaced with White | Pixels are replaced with White

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.

Topic: APLX Help : System Classes : Using the Draw method : Draw method State commands

[ Previous |Next | Contents | Index ]