O1Library Docs
Fall 2023
Docs API

# Traced

o1.gui.immutable$.ViewFrame.Traced
final class Traced[TraceData](val extractTrace: Model => TraceData) extends ViewFrame[Model], TraceGeneratingView[Model, TraceData]

A view that wraps around another, collecting a log or trace of events while delegating its actual event-handling to the wrapped view. Provides additional methods for accessing such traces: trace, simulateAndGet, and startAndGet. A few examples of using these methods are given below.

`simulate` 500 clock ticks on the trace-collecing view and print the trace of clock ticks accompanied by descriptions of the view’äs `model`.

    for (traceItem, traceEvent) <- myTracedView.simulateAndGet(500) do
       println(traceEvent + ": " + traceItem)

Or, equivalently:

    myTracedView.simulate(500)
     for (traceItem, traceEvent) <- myTracedView.trace do
       println(traceEvent + ": " + traceItem)

Alternatively, start the trace-collecting view and run it interactively until it is done or a tick limit is reached. Then print the trace of ticks and GUI events accompanied with descriptions of the view’s `model`.

    val futureTrace = myTracedView.startAndGet(tickLimit=100) recover {
       case Aborted(message, partialTrace) => partialTrace
     }
     for trace <- futureTrace; (traceItem, traceEvent) <- trace do
       println(traceEvent + ": " + traceItem)

## Type parameters

TraceData

  the type of the model-state descriptions in the trace

## Parameters

extractTrace

  a function that determines how to describe a model state in the generated trace

## Attributes

Graph
Supertypes
  trait TraceGeneratingView[Model, TraceData]
  trait GeneratesTrace[Model, TraceData]
  class ViewFrame[Model]
  trait Controls[Model]
  trait Fast
  class ViewFrameImpl[Model]
  class Object
  trait Matchable
  class Any
  Show all

## Members list

### Type members

#### Inherited classlikes

final class Traced[TraceData](val extractTrace: Model => TraceData) extends ViewFrame[Model], TraceGeneratingView[Model, TraceData]

A view that wraps around another, collecting a log or trace of events while delegating its actual event-handling to the wrapped view. Provides additional methods for accessing such traces: trace, simulateAndGet, and startAndGet. A few examples of using these methods are given below.

A view that wraps around another, collecting a log or trace of events while delegating its actual event-handling to the wrapped view. Provides additional methods for accessing such traces: trace, simulateAndGet, and startAndGet. A few examples of using these methods are given below.

`simulate` 500 clock ticks on the trace-collecing view and print the trace of clock ticks accompanied by descriptions of the view’äs `model`.

    for (traceItem, traceEvent) <- myTracedView.simulateAndGet(500) do
       println(traceEvent + ": " + traceItem)

Or, equivalently:

    myTracedView.simulate(500)
     for (traceItem, traceEvent) <- myTracedView.trace do
       println(traceEvent + ": " + traceItem)

Alternatively, start the trace-collecting view and run it interactively until it is done or a tick limit is reached. Then print the trace of ticks and GUI events accompanied with descriptions of the view’s `model`.

    val futureTrace = myTracedView.startAndGet(tickLimit=100) recover {
       case Aborted(message, partialTrace) => partialTrace
     }
     for trace <- futureTrace; (traceItem, traceEvent) <- trace do
       println(traceEvent + ": " + traceItem)

## Type parameters

TraceData

  the type of the model-state descriptions in the trace

## Parameters

extractTrace

  a function that determines how to describe a model state in the generated trace

## Attributes

Inherited from:
  ViewFrame
Supertypes
  trait TraceGeneratingView[Model, TraceData]
  trait GeneratesTrace[Model, TraceData]
  class ViewFrame[Model]
  trait Controls[Model]
  trait Fast
  class ViewFrameImpl[Model]
  class Object
  trait Matchable
  class Any
  Show all

### Value members

#### Inherited methods

final def adjustSpeed(newTickRate: Double): Unit

Sets a new tick rate for the view, replacing any previously set by the constructor or this method.

Sets a new tick rate for the view, replacing any previously set by the constructor or this method.

## Attributes

Inherited from:
  ViewFrameImpl

final def close(): Unit

Closes the view: stops it (as per stop), does any onClose effects, hides the GUI window, and possibly terminates the entire application (as per the constructor parameter).

Closes the view: stops it (as per stop), does any onClose effects, hides the GUI window, and possibly terminates the entire application (as per the constructor parameter).

## Attributes

Inherited from:
  ViewFrameImpl

def icon: Option[Pic]

The icon to be displayed in the title bar of this view’s GUI frame.

The icon to be displayed in the title bar of this view’s GUI frame.

## Attributes

Inherited from:
  ViewFrameImpl

final def icon_=(icon: Pic): Unit

Sets the icon to be displayed in the title bar of this view’s GUI frame.

Sets the icon to be displayed in the title bar of this view’s GUI frame.

## Parameters

icon

  a picture to be used as the icon

## Attributes

Inherited from:
  ViewFrameImpl

final def icon_=(icon: Option[Pic]): Unit

Sets the icon to be displayed in the title bar of this view’s GUI frame.

Sets the icon to be displayed in the title bar of this view’s GUI frame.

## Parameters

icon

  a picture to be used as the icon; if `None`, en empty icon image will be displayed

## Attributes

Inherited from:
  ViewFrameImpl

override def isDone(state: Model): Boolean

Determines if the given state is a “done state” for the view. This implementation delegates to the underlying `View` that is being traced.

Determines if the given state is a “done state” for the view. This implementation delegates to the underlying `View` that is being traced.

## Parameters

state

  a state of the model (possibly a done state)

## Attributes

Definition Classes
  TraceGeneratingView -> Controls -> Controls
Inherited from:
  TraceGeneratingView

final override def isPaused: Boolean

Indicates whether the view is paused. This implementation delegates to the underlying `View` that is being traced.

Indicates whether the view is paused. This implementation delegates to the underlying `View` that is being traced.

## Attributes

Definition Classes
  GeneratesTrace -> Controls
Inherited from:
  GeneratesTrace

def makePic(state: Model): Pic

Returns a Pic that graphically represents the current state of the view’s `model` object. This implementation delegates to the underlying `View` that is being traced.

Returns a Pic that graphically represents the current state of the view’s `model` object. This implementation delegates to the underlying `View` that is being traced.

## Parameters

state

  a state of the model to be displayed

## Attributes

Inherited from:
  TraceGeneratingView

override def onClick(state: Model, event: MouseClicked): Model

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

## Attributes

Definition Classes
  TraceGeneratingView -> Controls -> Controls
Inherited from:
  TraceGeneratingView

override def onClick(state: Model, position: Pos): Model

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

## Attributes

Definition Classes
  TraceGeneratingView -> Controls -> Controls
Inherited from:
  TraceGeneratingView

def onClose(): Unit

Causes an effect when the view’s GUI window is closed for any reason. By default, this method does nothing.

Causes an effect when the view’s GUI window is closed for any reason. By default, this method does nothing.

## Attributes

Inherited from:
  ViewFrameImpl

override def onKeyDown(state: Model, event: KeyPressed): Model

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

## Attributes

Definition Classes
  TraceGeneratingView -> Controls -> Controls
Inherited from:
  TraceGeneratingView

override def onKeyDown(state: Model, key: Key): Model

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

## Attributes

Definition Classes
  TraceGeneratingView -> Controls -> Controls
Inherited from:
  TraceGeneratingView

override def onKeyUp(state: Model, event: KeyReleased): Model

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

## Attributes

Definition Classes
  TraceGeneratingView -> Controls -> Controls
Inherited from:
  TraceGeneratingView

override def onKeyUp(state: Model, key: Key): Model

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

## Attributes

Definition Classes
  TraceGeneratingView -> Controls -> Controls
Inherited from:
  TraceGeneratingView

override def onMouseDown(state: Model, event: MousePressed): Model

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

## Attributes

Definition Classes
  TraceGeneratingView -> Controls -> Controls
Inherited from:
  TraceGeneratingView

override def onMouseDown(state: Model, position: Pos): Model

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

## Attributes

Definition Classes
  TraceGeneratingView -> Controls -> Controls
Inherited from:
  TraceGeneratingView

override def onMouseDrag(state: Model, event: MouseDragged): Model

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

## Attributes

Definition Classes
  TraceGeneratingView -> Controls -> Controls
Inherited from:
  TraceGeneratingView

override def onMouseDrag(state: Model, position: Pos): Model

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

## Attributes

Definition Classes
  TraceGeneratingView -> Controls -> Controls
Inherited from:
  TraceGeneratingView

override def onMouseEnter(state: Model, event: MouseEntered): Model

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

## Attributes

Definition Classes
  TraceGeneratingView -> Controls -> Controls
Inherited from:
  TraceGeneratingView

override def onMouseExit(state: Model, event: MouseExited): Model

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

## Attributes

Definition Classes
  TraceGeneratingView -> Controls -> Controls
Inherited from:
  TraceGeneratingView

override def onMouseMove(state: Model, event: MouseMoved): Model

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

## Attributes

Definition Classes
  TraceGeneratingView -> Controls -> Controls
Inherited from:
  TraceGeneratingView

override def onMouseMove(state: Model, position: Pos): Model

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

## Attributes

Definition Classes
  TraceGeneratingView -> Controls -> Controls
Inherited from:
  TraceGeneratingView

override def onMouseUp(state: Model, event: MouseReleased): Model

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

## Attributes

Definition Classes
  TraceGeneratingView -> Controls -> Controls
Inherited from:
  TraceGeneratingView

override def onMouseUp(state: Model, position: Pos): Model

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

## Attributes

Definition Classes
  TraceGeneratingView -> Controls -> Controls
Inherited from:
  TraceGeneratingView

final override def onStop(): Unit

Causes an additional effect when the view is stopped (with `stop()`). This implementation delegates to the underlying `View` that is being traced. In addition, if the traced view had been started with `startAndGet` and reaches its tick limit before being done, this method causes the returned future to complete with a failure.

Causes an additional effect when the view is stopped (with `stop()`). This implementation delegates to the underlying `View` that is being traced. In addition, if the traced view had been started with `startAndGet` and reaches its tick limit before being done, this method causes the returned future to complete with a failure.

## Attributes

Definition Classes
  GeneratesTrace -> Controls
Inherited from:
  GeneratesTrace

override def onTick(previousState: Model, time: Long): Model

Handles a clock tick and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

Handles a clock tick and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

## Attributes

Definition Classes
  TraceGeneratingView -> Controls -> Controls
Inherited from:
  TraceGeneratingView

override def onTick(previousState: Model): Model

Handles a clock tick and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

Handles a clock tick and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

## Attributes

Definition Classes
  TraceGeneratingView -> Controls -> Controls
Inherited from:
  TraceGeneratingView

override def onType(state: Model, event: KeyTyped): Model

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

## Attributes

Definition Classes
  TraceGeneratingView -> Controls -> Controls
Inherited from:
  TraceGeneratingView

override def onType(state: Model, character: Char): Model

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

## Attributes

Definition Classes
  TraceGeneratingView -> Controls -> Controls
Inherited from:
  TraceGeneratingView

override def onWheel(state: Model, event: MouseWheelMoved): Model

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

## Attributes

Definition Classes
  TraceGeneratingView -> Controls -> Controls
Inherited from:
  TraceGeneratingView

override def onWheel(state: Model, rotation: Int): Model

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

Handles a GUI event and adds it to the view’s trace. Delegates the actual event-handling to the corresponding method on the underlying `View` that is being traced.

## Attributes

Definition Classes
  TraceGeneratingView -> Controls -> Controls
Inherited from:
  TraceGeneratingView

final def refresh(): Unit

Programmatically requests an update to the graphics of the view (even though no clock tick or triggering GUI event occurred).

Programmatically requests an update to the graphics of the view (even though no clock tick or triggering GUI event occurred).

## Attributes

Inherited from:
  ViewFrameImpl

final def simulate(tickLimit: Int): Unit

Runs the view as if by calling start except that it runs “headless”, with no actual GUI window visible and independently of a real-time clock. A number of simulated clock ticks are immediately sent to the view; this continues until either the view determines it is done or a predetermined maximum number of ticks has been reached.

Runs the view as if by calling start except that it runs “headless”, with no actual GUI window visible and independently of a real-time clock. A number of simulated clock ticks are immediately sent to the view; this continues until either the view determines it is done or a predetermined maximum number of ticks has been reached.

## Parameters

tickLimit

  the maximum number of ticks to simulate; `Int.MaxValue` (which is the default) means there is no such limit

## Attributes

Inherited from:
  ViewFrameImpl

final def simulateAndGet(tickLimit: Int): Seq[(TraceData, TraceEvent)]

Simulates this trace-generating view with simulate and returns the resulting trace. This is equivalent to calling first simulate, then trace. See also startAndGet.

Simulates this trace-generating view with simulate and returns the resulting trace. This is equivalent to calling first simulate, then trace. See also startAndGet.

## Parameters

tickLimit

  the maximum number of ticks to simulate; `Int.MaxValue` (which is the default) means there is no such limit

## Attributes

Inherited from:
  GeneratesTrace

override def sound(state: Model): Option[Sound]

Determines whether the view should play a sound, given a state of its model. This implementation delegates to the underlying underlying `View` that is being traced.

Determines whether the view should play a sound, given a state of its model. This implementation delegates to the underlying underlying `View` that is being traced.

## Parameters

state

  a state of the model

## Attributes

Definition Classes
  TraceGeneratingView -> Controls -> Controls
Inherited from:
  TraceGeneratingView

final def start(): Unit

Starts the view: loads the model in the GUI window, makes the window visible oncreen, and starts the clock. Cf. simulate.

Starts the view: loads the model in the GUI window, makes the window visible oncreen, and starts the clock. Cf. simulate.

## Attributes

Inherited from:
  ViewFrameImpl

final def startAndGet(tickLimit: Long): Future[Seq[(TraceData, TraceEvent)]]

Starts this trace-generating view with start and returns a Future that evaluates to the resulting trace. The `Future` succeeds when the view is done; if the view isn’t done after a given number of clock ticks, the `Future` fails with TraceAborted, producing a partial trace. See also simulateAndGet.

Starts this trace-generating view with start and returns a Future that evaluates to the resulting trace. The `Future` succeeds when the view is done; if the view isn’t done after a given number of clock ticks, the `Future` fails with TraceAborted, producing a partial trace. See also simulateAndGet.

## Parameters

tickLimit

  the maximum number of ticks to process before the future completes with a failure; defaults to `Long.MaxValue`

## Attributes

Inherited from:
  GeneratesTrace

final def stop(): Unit

Stops the view: stops the clock, stops listening to events, and disposes of the GUI window. A stopped view cannot be restarted.

Stops the view: stops the clock, stops listening to events, and disposes of the GUI window. A stopped view cannot be restarted.

## Attributes

Inherited from:
  ViewFrameImpl

final override def toString: String

Returns a brief textual description of the view.

Returns a brief textual description of the view.

## Attributes

Definition Classes
  GeneratesTrace -> Any
Inherited from:
  GeneratesTrace

final def tooltip: String

the tooltip text to be displayed while the mouse hovers on the view

the tooltip text to be displayed while the mouse hovers on the view

## Attributes

Inherited from:
  ViewFrameImpl

final def tooltip_=(newText: String): Unit

Sets the tooltip text to be displayed while the mouse hovers on the view.

Sets the tooltip text to be displayed while the mouse hovers on the view.

## Attributes

Inherited from:
  ViewFrameImpl

final def trace: Seq[(TraceData, TraceEvent)]

Returns a trace of the events processed by this view. The trace comes in a collection of pairs, each of which is composed of a `TraceData` value that describes at the time of the event and a TraceEvent value that describes the event itself.

Returns a trace of the events processed by this view. The trace comes in a collection of pairs, each of which is composed of a `TraceData` value that describes at the time of the event and a TraceEvent value that describes the event itself.

## Attributes

Inherited from:
  GeneratesTrace

final def traced: Traced[Model]

Returns a `View` that stores a trace of the ticks and GUI events that its event handlers process. This parameterless method stores, at each event, the (immutable) state of the `View`’s model. This is equivalent to calling tracedWith and passing in `identity`.

Returns a `View` that stores a trace of the ticks and GUI events that its event handlers process. This parameterless method stores, at each event, the (immutable) state of the `View`’s model. This is equivalent to calling tracedWith and passing in `identity`.

## Attributes

Inherited from:
  Controls

final def tracedPics: Traced[Pic]

Returns a `View` that stores a pictorial trace of the ticks and GUI events that the `View`’s event handlers process. This is equivalent to calling tracedWith and passing in the `View`’s `makePic` method.

Returns a `View` that stores a pictorial trace of the ticks and GUI events that the `View`’s event handlers process. This is equivalent to calling tracedWith and passing in the `View`’s `makePic` method.

## Attributes

Inherited from:
  Controls

final def tracedWith[TraceData](extractTrace: Model => TraceData): Traced[TraceData]

Returns a view that collects of the ticks and GUI events that the `View`’s event handlers process, using the given function to generate that trace. That trace-collecting view, which an instance of the Traced subclass, delegates the actual event handling to this original view but provides an additional interface for tracing.

Returns a view that collects of the ticks and GUI events that the `View`’s event handlers process, using the given function to generate that trace. That trace-collecting view, which an instance of the Traced subclass, delegates the actual event handling to this original view but provides an additional interface for tracing.

## Type parameters

TraceData

  the type of the model-state descriptions in the trace

## Parameters

extractTrace

  a function that determines how to describe a model state in the generated trace

## Attributes

See also

  traced, tracedPics

Inherited from:
  ViewFrame

final def visible: Boolean

whether this view’s GUI frame is visible onscreen

whether this view’s GUI frame is visible onscreen

## Attributes

Inherited from:
  ViewFrameImpl

final def visible_=(desiredVisibility: Boolean): Unit

Sets whether this view’s GUI frame is visible onscreen.

Sets whether this view’s GUI frame is visible onscreen.

## Attributes

Inherited from:
  ViewFrameImpl

#### Inherited fields

val closeWhenDone: Boolean

## Attributes

Inherited from:
  ViewFrameImpl

val refreshPolicy: RefreshPolicy

## Attributes

Inherited from:
  ViewFrameImpl

val terminateOnClose: Boolean

## Attributes

Inherited from:
  ViewFrameImpl

protected val title: String

## Attributes

Inherited from:
  ViewFrameImpl