HELP INSTRUMENT_FLAVOURS                       Mark Rubinstein  July 1986
                                         Revised by Ian Rogers July 1987

    lib instrument_flavours;

This library provides a set of flavours for building and manipulating
visual instruments, such as gauges and dials.  The instrument flavours use
other flavours representing workstation windows and parts thereof.  The
window flavours are provided by LIB * WINDOW_FLAVOURS and are documented
in HELP * WINDOW_FLAVOURS.  Please note that they will only work when you
are working with a POPLOG WINDOW MANGER - see HELP * VEDPWM.

For details of the flavours package see TEACH * FLAVOURS
For details of the windows interface see HELP * WINDOW_FLAVOURS

In general all instruments have a 'hostwindow' on which they sit. If none
is provided at initialise time (e.g. when using make_instance) then by
default an instance of -instrument_window_flavour- will be created .  This
is a part_graphics_window which will by default sit upon the real graphics
window -instrument_window-.  If the *VALOF of the word "instrument_window"
is not an instance of graphics_window then one will be created and
assigned.  This means that by default (if you don't specify a hostwindow)
then all instruments will appear on the same window.

When the value of an instrument is changed then the needle of a dial or
bar of a gauge automatically moves.  If you change the minvalue or range
of an instrument it will redraw itself appropriately.

If the instrument's flavour inherits from receiving_bar_gauge (receiving
dials have not been implemented) then pressing the left mouse button while
the mouse cursor is in the instrument's hostwindow will cause the
instrument to adjust it's value appropriately and so move the gauge's bar.

Scaled instrument will draw a scale around the instrument.  It draws
-graduation_frequency- + 1 short lines along the gauge and
-label_frequency- + 1 longer lines with labels indicating the value at
that point.

-- INDEX - (Use <ENTER> g to access sections) -------------------------

 -- Protocol for instrument_window_flavour
 -- Protocol for instrument_flavour
 -- Protocol for scaled_instrument_flavour
 -- Protocol for bar_gauge_flavour
 -- Protocol for receiving_bar_gauge_flavour
 -- Protocol for horizontal_bar_gauge_flavour
 -- Protocol for scaled_horizontal_bar_gauge_flavour
 -- Protocol for receiving_horizontal_bar_gauge_flavour
 -- Protocol for scaled_receiving_horizontal_bar_gauge_flavour
 -- Protocol for vertical_bar_gauge_flavour
 -- Protocol for scaled_vertical_bar_gauge_flavour
 -- Protocol for receiving_vertical_bar_gauge_flavour
 -- Protocol for scaled_receiving_vertical_bar_gauge_flavour
 -- Protocol for dial_flavour
 -- Protocol for scaled_dial_flavour
 -- Protocol for receiving_dial_flavour
 -- Protocol for receiving_scaled_dial_flavour

-- Protocol for instrument_window_flavour ------------------------------

    By default instrument will make an instance of instrument_window to be
    their 'hostwindow'.

Inherits from part_graphics_window and vanilla
Instance variables are char_base, char_height, char_width, hostwindow,
    instrument, name, operation, paint, position and size.

instrument
    The instrument which sits on this window.
left_button_pushed(x, y)
    Passes the message on to the instrument.
refreshself
    Passes the message on to the instrument.

-- Protocol for instrument_flavour -------------------------------------

    Some basic features of instruments.

A mixin
Inherits from ivalofinit, named_object and vanilla
Instance variables are hostwindow, instrument_size, minvalue, name, range,
    value, x_offset and y_offset.

subclasses should implement methods for adjust_host_size,
    draw_instrument_border and paintvalue.

left_button_pushed(x, y)
    Default method -- does nothing.
makeself
    Sends self the messages draw_instrument_border, paintvalue and writename
minvalue
    The minimum value the instrument will show (or allow).  Value cannot be
    set less than this.
position -> {x y}
{x y} -> position;
    This method and its updater passes on the message and the arguments to the
    hostwindow so that the hostwindow (usually a part_window) and the gauge is
    moved.  This message has an updater.
range
    The maximum value the instrument will show (or allow) - the minvalue.
        minvalue + range = maxvalue
refreshself
    Sends self the message makeself.
writename
    If name is a string then it will write the characters of name
    below the instrument.
x_offset and y_offset
    Define the position of the gauge within its hostwindow.

There are before daemons on: value, paintvalue, range and minvalue
There are after daemons on: initialise, range, minvalue and instrument_size

-- Protocol for scaled_instrument_flavour ------------------------------

    Mixin for instruments with a scale around them.  Will send self the
    message "writescale" whenever the message draw_instrument_border is sent.

A mixin
Inherits from instrument and vanilla
Instance variables are graduation_frequency, hostwindow, instrument_size
    label_frequency, minvalue, name, range, value, x_offset and y_offset.

Subclasses should provide methods for: writescale.

There are after daemons on: draw_instrument_border

-- Protocol for bar_gauge_flavour --------------------------------------

    Features common to all bar gauges -- vertical and horizontal.

A mixin
Inherits from instrument and vanilla
Instance variables are gauge_length, gauge_width, hostwindow,
    instrument_size, minvalue, name, range, value, x_offset and y_offset.

draw_instrument_border
    Draws a rectangle of length gauge_length and width gauge_width at the
    position {x_offset, y_offset} in the hostwindow.
offset_for_value(v) -> n
    For a given value v will return the number of pixels from the origin
    of the instrument to the appropriate place for the value.

There are before daemons on: gauge_width and gauge_length
There are after daemons on: gauge_width

-- Protocol for receiving_bar_gauge_flavour ----------------------------

    Features of gauges that will respond to the message
    "left_button_pushed" by moving the gauges value to that location.

Inherits from bar_gauge and vanilla
Instance variables are gauge_length, gauge_width, hostwindow,
    instrument_size minvalue, name, range, value, x_offset and y_offset.

value_for_offset(o) ->
    for a given offset from the gauge's origin returns the value that the
    position represents.

-- Protocol for horizontal_bar_gauge_flavour ---------------------------

    Flavour of the no-frills horizontal bar gauge.

Inherits from bar_gauge and vanilla
Instance variables are gauge_length, gauge_width, hostwindow,
    instrument_size, minvalue, name, range, value, x_offset and y_offset.

adjust_host_size
    Adjusts the size of the hostwindow so that it is sufficient only to
    contain the gauge.
paintvalue
    Paints the bar of the appropriate size for the current value.

There are before daemons on: value
There are after daemons on: gauge_length and instrument_size

-- Protocol for scaled_horizontal_bar_gauge_flavour --------------------

    Flavour of the bar_gauge with a scale.

Inherits from horizontal_bar_gauge, scaled_instrument and vanilla
Instance variables are gauge_length, gauge_width, graduation_frequency,
    hostwindow, instrument_size, label_frequency, minvalue, name, range,
    value, x_offset and y_offset.

writescale
    Draws the scale for the gauge.

-- Protocol for receiving_horizontal_bar_gauge_flavour -----------------

    Instances of this flavour respond when the left mouse button is pushed
    in their hostwindow.

Inherits from horizontal_bar_gauge, receiving_bar_gauge and vanilla
Instance variables are gauge_length, gauge_width, hostwindow,
    instrument_size, minvalue, name, range, value, x_offset and y_offset.

left_button_pushed(x, y)
    Updates value such that the bar extends to x.

-- Protocol for scaled_receiving_horizontal_bar_gauge_flavour ----------

    Mixes features of the scaled horizontal bar gauge with the receiving
    one.

Inherits from scaled_horizontal_bar_gauge, receiving_horizontal_bar_gauge
    and vanilla.
Instance variables are gauge_length, gauge_width, graduation_frequency,
    hostwindow, instrument_size, label_frequency, minvalue, name, range,
    value, x_offset and y_offset.

-- Protocol for vertical_bar_gauge_flavour -----------------------------

Inherits from bar_gauge and vanilla.
Instance variables are gauge_length, gauge_width, hostwindow,
    instrument_size, minvalue, name, range, value, x_offset and y_offset.

adjust_host_size
    Adjusts the size of the hostwindow so that it is sufficient only to
    contain the gauge.
paintvalue
    Paints the bar of the appropriate size for the current value.

There are before daemons on: value
There are after daemons on: gauge_width and instrument_size

-- Protocol for scaled_vertical_bar_gauge_flavour ----------------------

Inherits from vertical_bar_gauge, scaled_instrument and vanilla.
Instance variables are gauge_length, gauge_width, graduation_frequency,
    hostwindow, instrument_size, label_frequency, minvalue, name, range,
    value, x_offset and y_offset.

writescale
    Draws the scale for the gauge.

-- Protocol for receiving_vertical_bar_gauge_flavour -------------------

Inherits from vertical_bar_gauge, receiving_bar_gauge and vanilla.
Instance variables are gauge_length, gauge_width, hostwindow,
    instrument_size, minvalue, name, range, value, x_offset and y_offset.

left_button_pushed(x, y)
    Updates value such that the bar extends to y.

-- Protocol for scaled_receiving_vertical_bar_gauge_flavour ------------

    Mixes features of scaled gauge with that of the receiving one.

Inherits from scaled_vertical_bar_gauge, receiving_vertical_bar_gauge and
    vanilla
Instance variables are gauge_length, gauge_width, graduation_frequency,
    hostwindow, label_frequency, minvalue, name, range, instrument_size,
    value, x_offset and y_offset.

-- Protocol for dial_flavour -------------------------------------------

    Dials are hemispherical (upper-hemisphere) and have a filled
    hemisphere at the centre.  The radius of the main hemisphere is
    instrument_size and the radius of the small black hemisphere is
    centre_radius.

Inherits from instrument and vanilla.
Instance variables are centre_radius, hostwindow, instrument_size,
    minvalue, name, range, value, x_offset and y_offset.

adjust_host_size
    Adjusts the size of the hostwindow so that it is sufficient only to
    contain the dial.
draw_instrument_border
    Draws the hemispheres.
circ_for_value_at(v, r) -> {x y}
    Returns the position on the circumference of a circle of a radius r
    for the value v.
paintvalue
    Draws the needle for the current value.

There are before daemons on: instrument_size and value
There are after daemons on: value

-- Protocol for scaled_dial_flavour ------------------------------------

Inherits from dial, scaled_instrument and vanilla.
Instance variables are centre_radius, graduation_frequency, hostwindow,
    instrument_size, label_frequency, minvalue, name, range, value,
    x_offset and y_offset.

adjust_host_size
    Adjusts the size of the hostwindow so that it is sufficient only to
    contain the dial.  (Needs to be bigger for the scaled dial).
writescale
    Writes the scale around the edge of the dial.

-- Protocol for receiving_dial_flavour --------------------------------

    Features of dials that will respond to the message
    "left_button_pushed" by moving the dials value to that location.

Inherits from dial and vanilla
Instance variables are: hostwindow, instrument_size, minvalue, name,
range, value, x_offset and y_offset.

-- Protocol for receiving_scaled_dial_flavour -------------------------

    Features of dials that will respond to the message
    "left_button_pushed" by moving the dials value to that location.

Inherits from receiving_dial, scaled_dial and vanilla
Instance variables are: hostwindow, instrument_size, minvalue, name,
range, value, x_offset and y_offset.

--- C.all/help/instrument_flavours -------------------------------------
--- Copyright University of Sussex 1987. All rights reserved. ----------
