## Class vsearch.Trial

- java.lang.Object
- - vsearch.Trial

- Enclosing class:
    vsearch

      public static class vsearch.Trial
      extends java.lang.Object

  This class resembles one trial of the study experiment. It keeps information of the symbols, coordinates and type what this trial really includes. It also gathers the information of user selections and the correctness of the answer. Also it generates and does the initialization and some drawing functions for the symbols and circles. The most important function here is the logging which logs the trial made. This class is used in the design ie. "design that contains 10 trials".
  See Also:
    `vsearch.DesignContainer`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `int` | `amountOfChars` The actual amount of characters used in calculations.
    `int` | `amountOfFoils` This trial's amount of foil characters.
    `int` | `amountOfTargets` The actual amount of targets used in calculations.
    `java.awt.Point[]` | `charCoords` Character or foil foil coordinates.
    `java.lang.String[]` | `generatedChars` This trial's generated characters.
    `java.lang.String` | `generatedCharStr` Generetated char string.
    `int` | `size` This trial's size / amount of letters
    `int` | `sizeReal` the real size of the trial ie.
    `boolean` | `suffled`
    `int` | `targ` This trial's target character's index number
    `int` | `targChar` This trial's target character
    `java.lang.String` | `targCharReal` The string representation of target character.
    `int` | `targColor` This trial's target character's color
    `java.lang.String` | `targColorReal` The string representation of target's color.
    `java.awt.Point[]` | `targetCoords` This trial's targets coordinates
    `int` | `targetsReal` The actual amount of targets.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `vsearch.Trial()`
    `vsearch.Trial(int v1, int v2, int v3, int v4)` The constructor for trial.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `checkCorrectness()` This function checks the correctness of user's answer.
    `void` | `drawChars(java.awt.Graphics g)` Draws characters(symbols) across the screen.
    `void` | `drawCircles(java.awt.Graphics g)` Draws circles across the screen.
    `void` | `generateCharCoords()` Generates charcoords.
    `void` | `printLog()` Log the results into debug or file according subject's number.
    `void` | `setTrialNumber(int num)` Set the trialNumber -variable of this trial which tells this trials index.
    `void` | `trialResponse1()` This function captures the time user had gone through when looking at the symbols.
    `void` | `trialResponse2()` When user clicks the second time this is called.
    `boolean` | `userClicks(int x, int y)` The hit test for user's click.
    `void` | `userClicksNone()` This is called when user clicks the none-button.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### targChar

          public int targChar

      This trial's target character

    - #### targColor

          public int targColor

      This trial's target character's color

    - #### size

          public int size

      This trial's size / amount of letters

    - #### targ

          public int targ

      This trial's target character's index number

    - #### targCharReal

          public java.lang.String targCharReal

      The string representation of target character.

    - #### targColorReal

          public java.lang.String targColorReal

      The string representation of target's color. ie. "white"

    - #### sizeReal

          public int sizeReal

      the real size of the trial ie. 10.

    - #### targetsReal

          public int targetsReal

      The actual amount of targets.

    - #### generatedChars

          public java.lang.String[] generatedChars

      This trial's generated characters.

    - #### charCoords

          public java.awt.Point[] charCoords

      Character or foil foil coordinates.

    - #### amountOfFoils

          public int amountOfFoils

      This trial's amount of foil characters.

    - #### targetCoords

          public java.awt.Point[] targetCoords

      This trial's targets coordinates

    - #### amountOfTargets

          public int amountOfTargets

      The actual amount of targets used in calculations.

    - #### amountOfChars

          public int amountOfChars

      The actual amount of characters used in calculations.

    - #### generatedCharStr

          public java.lang.String generatedCharStr

      Generetated char string. This helps to print the trial's info. The chars's will be generated into this string also.

    - #### suffled

          public boolean suffled

  - ### Constructor Detail

    - #### vsearch.Trial

          public vsearch.Trial()

    - #### vsearch.Trial

          public vsearch.Trial(int v1,
                       int v2,
                       int v3,
                       int v4)

      The constructor for trial. This takes care of calling the methods generating foils and the coordinates for characters. Also the trial's variables are set here. This is called when initializing the trial ie. from design. The easiest way to handle these are to change the values that define the de- design earlier. To understand this more you can drive this with debug=1 and you should see Added trial: -lines that describe what's happening.
      Parameters:
        `v1` - target's character index. ie. 0=X, 1=O according targChars[]
        `v2` - target's color index to use
        `v3` - tells how much symbols are in this trial (sizes[index])
        `v4` - tells how many symbols of this trial are targets. This is also index from table called targets[].

  - ### Method Detail

    - #### setTrialNumber

          public void setTrialNumber(int num)

      Set the trialNumber -variable of this trial which tells this trials index.
      Parameters:
        `num` - The trial number.

    - #### printLog

          public void printLog()

      Log the results into debug or file according subject's number. Filename is made from subjectnumber. This is called after trial is done to make sure all informatin is complete. Does io exception if something went horribly wrong.

    - #### trialResponse1

          public void trialResponse1()

      This function captures the time user had gone through when looking at the symbols. In other words this function is called when the user's visual searching is completed and he's ready to answer.
      See Also:
        `vsearch.getTestTimeMs()`, `vsearch.getScreenTimeMs()`, `trialResponse2()`

    - #### trialResponse2

          public void trialResponse2()

      When user clicks the second time this is called. The second time is the dis- play when user chooses what he saw in last screen. This is called response- Time2 and the time is get by getScreenTime() function. Also the test-time is captured here by getTestTimeMs() function.
      See Also:
        `vsearch.getTestTimeMs()`, `vsearch.getScreenTimeMs()`, `trialResponse1()`

    - #### userClicksNone

          public void userClicksNone()

      This is called when user clicks the none-button. After this checkCorrectness must be done to check if it was correct answer.

    - #### checkCorrectness

          public void checkCorrectness()

      This function checks the correctness of user's answer. This is called from userClicks -function. The result is put into correct -varible of this class for later usage.

    - #### userClicks

          public boolean userClicks(int x,
                           int y)

      The hit test for user's click. This tests through all the trial's symbols if some symbol was under the cursor when clicked. The size of the test circle is defined in variable circleSize. If the user clicked on right place the answer is captured to variable named answer and the function checkCorrectness() is used to see if it was correct.
      Parameters:
        `x` - mouse's x-coordinate.
        `y` - mouse's y-coordinate.
      Returns:
        if the cursor was over any symbol this returns true, otherwise false.

    - #### generateCharCoords

          public void generateCharCoords()

      Generates charcoords. These are the coordinates where each trials' symvbols are placed. The function tries to find always the most far points randomly. The points are generated again and again and it always accept the distance which is more far away from each other point. The repetitions used to do this loop is defined variable POINT_FINDER_LOOP_LOAD. The result generated table is charCoords and is used in draw functions and to check the user's answer's correctness/rightness. This function should be driven right in the start of trial to set the coordinates.
      See Also:
        `drawChars(Graphics g)`

    - #### drawChars

          public void drawChars(java.awt.Graphics g)

      Draws characters(symbols) across the screen. The positions are gathered from charCoods table.
      Parameters:
        `g` - Graphics to draw the stuff.

    - #### drawCircles

          public void drawCircles(java.awt.Graphics g)

      Draws circles across the screen. The positions are gathered from charCoods table. Circles are used in this test to show the previous place of the now hidden symbol.
      Parameters:
        `g` - Graphics to draw the stuff.