This legacy web site is no longer updated but will remain online for the foreseeable future. UUhistle is not being actively supported or developed. Successor systems include Jsvee and Kelmu.

Using Course Config Files

UUhistle can load example programs and settings from a course config file. UUhistle can load a course config file locally from the user's computer or from a teacher-defined URL on the net. A teacher can create a course config file and use it as a vehicle for distributing example programs and exercises.

A Config File Example

Course config files are written in XML. This sample file defines a single viewable example program and a single visual program simulation exercise where the user is required to manually simulate execution. It's verbose, but not too hard to understand.

<UUhistle version="0.6">
  <Course name="Sample configuration file">
    <Round name="Exercise Round 1">

      <Exercise name="A viewable program example">
        <Settings>
          <Setting name="allowSimulation" value="false" enabled="true"/>
        </Settings>
        <Description>
           Click Next Step repeatedly to view the program's execution.
           You cannot manually simulate this one. 
        </Description>
        <Code>
          <Line text="a = 10 + 5 * 4"/>
          <Line text="b = a * 3 - 7" />
        </Code>
      </Exercise>

      <Exercise name="A visual program simulation exercise">
        <Settings>
          <Setting name="defaultVPS" value="true" enabled="false"/>
        </Settings>
        <Description>
          <p>A visual program simulation exercise.</p>
          <p>The user has to manually simulate the entire program run except 
          for line changes that don't involve explicit conditionals.
          (After evaluating the conditional, the user has to click on the next line,
          but moving from line 1 to line 2, for instance, happens automatically.)</p>
        </Description>
        <Code>
          <Line text="a = 10 + 5 * 4"/>
          <Line text="b = a * 3 - 7" />
          <Line text="if a &lt; b:" />
          <Line text="    a = b" />
          <Line text="else:" />
          <Line text="    b = a" />
        </Code>
      </Exercise>

    </Round>
  </Course>
</UUhistle>

Where to Place It

When UUhistle is used as an applet, the default location of the course config file is the same directory with the JAR package that the applet is loaded from. This location can be changed via an applet parameter. If a course identifier is set in the applet parameters, then the file should be called exercises_COURSEID.xml, replacing COURSEID with the course identifier. If no course identifier is set, then the file should be called simply exercises.xml.

When UUhistle is used as a standalone application, the default location of the course config file is the current working directory. Through the Settings menu, the user can specify another location, which can be a local file or directory, or a remote URL. You can point UUhistle either to a directory where exercises.xml is located or directly to a file whose name has the .xml suffix.

Config File Overview

The sample file below contains an example of each different element type. Click the elements for more details. You may also want to look at the DTD.

There are three levels of granularity: Course elements contain Round elements, which in turn contain Exercise elements that define specific example programs. Inside each Exercise element, you define the program code, and possibly a grading scheme and popup questions for that example code.

Settings can be set at any of the three levels. For instance, a Settings element directly inside a Round element applies to all exercises in that round. Round-level settings override the course-level settings and exercise-level settings override round and course-level settings.

<UUhistle version="0.6">
  <Course name="Sample configuration file">
    <Description>This is a sample file</Description>
    <Settings>
      <Setting name="allAutomation" value="true" enabled="true"/>
    </Settings>
    <Round name="First round">
      <Description>
        This is the first round of exercises.
      </Description>
      <Settings>
        <Setting name="evaluateOperatorsAutomatically" value="false" enabled="false"/>
      </Settings>
      <Exercise name="First exercise">
        <Description>
          In this exercise, drag and click the visual elements to execute the program.
        </Description>
        <Settings>
          <Setting name="addOperatorsAutomatically" value="false" enabled="false"/>
        </Settings>
        <Points maxPoints="15" totalJumps="2"/>
        <Code>
          <Line text="a = 10 + 5 * 4"/>
          <Line text="b = a * 3 - 7">
            <Question text="The assigned value is ..." type="radio" points="5">
              <Option text="1" />
              <Option text="56" />
              <Option text="83" correct="true"/>
            </Question>
          </Line>
        </Code>
      </Exercise>
    </Round>
  </Course>
</UUhistle>

The XML Format in Detail

All elements and their explanations are listed below in alphabetical order. The following notation is used for child elements:

Code

Contains the code of the specific exercise. Each line is described in its own child element.

Possible parent elements: Exercise
Child elements: Line+

Attributes:

Attribute Type Explanation
showClasses optional A comma-separated list of built-in Python classes to be included in UUhistle's Classes panel when the program is viewed. If not set, all available built-in classes are shown that have method names matching those used in the code.

Course

A high-level element that contains rounds of exercises.

Possible parent elements: UUhistle
Child elements: Description, Settings?, Round+

Attributes:

Attribute Type Explanation
name required A name that UUhistle displays in the example program selection dialog.

Description

The description of a course, round or exercise. UUhistle shows the description in the GUI.

Possible parent elements: Course, Exercise, Round
Child elements: none

Attributes: none

Content: The element contains a textual (XHTML) description.

Exercise

Describes an exercise, i.e., a viewable example program or a visual program simulation assignment.

Possible parent elements: Round
Child elements: Description, Settings?, Points?, Code, HiddenCode?

Attributes:

Attribute Type Explanation
name required The name of this exercise. Shown in the UUhistle GUI.
id optional/required The identifier for this exercise. When a submission type is set (in the top-level UUhistle element or in the applet parameters), an identifier must be defined for each exercise in the course config file.
maxPoints optional Defines a maximum points value for the exercise, accompanied by a simple grading scheme: the user will receive this number of points upon reaching the end of the program, assuming they have correctly answered any popup questions (see Question) embedded into the execution sequence. If there are no popup questions, then simply reaching the end of the program gives the full points. Note that when this attribute is set, the user does not get partial points for intermediate execution steps (excepting popup questions).

This attribute must not be used in combination with the optional Points element, which defines a more detailed grading scheme.

HiddenCode

Contains code that is a 'hidden', built-in part of the exercise. This code is not shown to the user. Hidden code can be used from the visible code as a black box, just like Python's built-in functions and classes. For instance, the hidden code can define a class whose methods are used from the visible code without visualizing each step of those methods' execution.

Just like the Code element, which defines the visible code for the exercise, this element also consists of Line elements that contain each line of code separately. Apart from the text attribute, all other attributes of Line elements are ignored within HiddenCode.

Possible parent elements: Exercise
Child elements: Line+

Attributes: none

Line

Represents a single line of code.

Possible parent elements: Code, HiddenCode
Child elements: Question?

Attributes:

Attribute Type Explanation
text required The line of Python code. Remember to use &amp; and &lt; as necessary!
fullAutomationAfter optional Describes how many times the user must manually simulate the execution steps defined on this line. E.g. If set to zero, the user does not need to manually simulate the line at all. If set to 1, the user must manually simulate the line the first time it is executed, but the second time (and later) they may just press Next Step to proceed. This attribute is ignored if the line is a part of a HiddenCode element.
fastForwardAfter optional Like fullAutomationAfter but for enabling the fast forward button. This line-specific setting overrides the overall fast-forwarding setting (allowFastForward).
occurrences optional Describes how many times this line will be executed during the entire program run. This information is needed when the Points element is used. The default value is 0 if the line is empty, 1 otherwise. This attribute is ignored if the line is a part of a HiddenCode element.
pointWeight optional When the Points element is used, all lines of code are considered equally valuable in grading unless otherwise specified with this attribute. Each line has an impact on grading proportional to its pointWeight. (The default for each line is 1.) This attribute is ignored if the line is a part of a HiddenCode element.
info optional If given, this text will be shown in a popup dialog when this line is reached for the first time.
\n can be used for newlines. This attribute is ignored if the line is a part of a HiddenCode element.
description optional An XHTML description of this line of code. If set, a UUhistle user can access this description while the line is being executed by clicking on an Explain this line link. This attribute is ignored if the line is a part of a HiddenCode element.
linkCaption optional Overrides the default Explain this line link text. (See the description attribute above.). This attribute is ignored if the line is a part of a HiddenCode element.

Option

Represents one available choice in a multiple choice question.

Possible parent elements: Question
Child elements: none

Attributes:

Attribute Type Explanation
text required The option as text. Shown to the UUhistle user as part of the question.
correct optional A correct answer should have this attribute to set true.

Points

Defines a grading scheme for this exercise. Note that if you want to give grades to students, you should either simply define a maxPoints attribute for the Exercise element or use a Points element for a more fine-grained grading scheme. Also note that if you do use a Points element, you'll need to adjust the occurrences attributes of the various Line elements.

Possible parent elements: Exercise
Child elements: none

Attributes:

Attribute Type Explanation
maxPoints required The maximum points for this exercise.
totalJumps required The total number of times that any line is executed during the program run. Any line that is executed only once counts once. Any line in a function that is called N times counts N times. Any line in a loop with M iterations counts M times.
initialJumps optional A number of lines that are executed at the beginning of the program but which don't impact scoring at all. The default is 0.
yellowDecrement optional A number points that is deducted for any the submitted simulation trace contains a 'yellow mistake' or a 'red mistake'. That is, a points penalty for incorrect simulation steps. The default value is 0.
tutorialMaxPoints optional The maximum number of points for this exercise if the tutorial mode has been used while solving it. The default value is 0.
hintsAvailable optional The number of hints available in this exercise. (Hints are tutorial-mode-like tips that the user can access using the question mark button in the UUhistle GUI.) -1 means an infinite number of hints. The default value is 0.
freeHints optional The number of hints that the user can get without them costing points. The default is 0.
hintDecrement optional The number of points lost if the user asks for a hint and all free hints have been used. The default value is 0.

Question

Defines a question to be shown when execution reaches a specific line of code for the first time.

Possible parent elements: Line
Child elements: Option

Attributes:

Attribute Type Explanation
text required The question text shown to the user.
Use \n for line breaks.
type required A question type.
Must be one of: input, checkbox or radio.
points optional The number of points given after correct answer. The default value is 0.
title optional Overrides the default dialog caption (which is simply: Question).
noResult optional By default, UUhistle will tell the user if they answered correctly or incorrectly. Setting this attribute overrides the default response — the noResult text is shown instead. (E.g. "Let's continue executing and see if you were right...").
Use \n for a line break.
width optional The width of the input text field in pixels. (Only relevant when type is set to input.)
answer (required) If type is input, this attribute specifies the correct answer. If not, this attribute is irrelevant.
atEnd optional If set to true, the question will be asked only after the line has been dealt with and control is about to move to another line of code (instead of when execution reaches the line).

Round

A round contains exercises.

Possible parent elements: Course
Child elements: Description, Settings?, Exercise+

Attributes:

Attribute Type Explanation
name required A name that UUhistle displays in the example program selection dialog.
noSubmit optional If set to true, the exercises of this round can not be submitted regardless of the submitType set in the top-level UUhistle element.

Setting

A single setting for a course, round or exercise.

Possible parent elements: Settings
Child elements: none

Attributes:

Attribute Type Explanation
enabled required true or false, defines if the user is allowed to change this setting through the UUhistle GUI.
name required The name of this setting. A list of possible settings is at the end of this document.
value required true or false

Settings

Contains settings for a course, round or exercise.

Possible parent elements: Course, Exercise, Round
Child elements: Setting+

Attributes: none

UUhistle

The root element of the course config file.

Possible parent elements: none (root element)
Child elements: Course

Attributes:

Attribute Type Explanation
version required The version number of UUhistle to be used with this course config file.
submitType optional If set to POST, the results are sent to a server using a HTTP POST request. This attribute has no effect if UUhistle is used as an applet. In that case, use an applet parameter instead.
submitURL optional The URL where submissions will be POSTed. This attribute is required if the submit type is set to POST. This must be an absolute URL, e.g. http://www.example.com/uuhistle_post.php. This attribute has no effect if UUhistle is used as an applet. In that case, use an applet parameter instead.


List of Settings

Here is a list of all the settings that can be defined at the course, round or exercise level.

Main settings

Name Default Explanation
defaultVPS N/A This convenience setting can be set to true to conveniently create a basic visual program simulation exercise: the user has to manually simulate the entire program run with the exception of line changes that don't involve explicit conditional branches (i.e., only line changes based on conditional in if and while statements are manual).

Setting defaultVPS to true is equivalent to setting (in order) allowSimulation to true, allAutomation to false, allJumps to true, and jumpBranches to false. Setting defaultVPS to false has no effect.
allowSimulation false Allow the user to manually simulate this exercise. This setting must be enabled in a visual program simulation exercise. Disable it if you want to have students only view a program (and perhaps answer popup questions).
allAutomation true Sets all automation settings (see below) at once. In effect, what this means is that this setting defines if the user has to manually perform program execution steps or if it is possible to make UUhistle do them automatically. Setting this to true allows using the Next Step button to step through all kinds of program execution steps. If you set this to false, UUhistle will require users to manually simulate the entire program run, including all line changes.
allJumps true Sets all jumps settings (see below) at once. The jumps settings are a subset of the automation settings.
allowFastForward true Allow the user to fast forward by holding down the appropriate button, assuming manual simulation is not require.
jumpInSteppingMode true If set to true, once the user has successfully manually simulated a line's execution, control jumps to the next line immediately. If false, moving to the next line is a separate execution step.
showAllAsClassInstances false Also show values of simple immutable built-in types (ints and string and the like) in terms of objects and references.
useShortcuts false Use 'shortcuts' when displaying program execution: trivial uses of the evaluation area are bypassed. For instance, assignment from a variable to another does not use the evaluation area.
useStepping true Advance only a step at a time. If set to false, UUhistle will start the next execution step as soon as the previous one finishes (unless it needs to be done manually, of course).
tutorialMode false Enable the tutorial mode, which gives constant detailed advice to the user on how to manually simulate the program.
createLiteralsAtStart false If set to true, create all literal values in the heap at execution start, rather than as needed.
showPythonClasses true If a method name used in the code matches a built-in method, display the built-in class.
onlyMainRef false Only show a single arrow when the user mouses over a reference. UUhistle visualizes references as arrows when the user mouses over them. If onlyMainRef is set to true, only a single arrow from the reference value to the target object is shown. If this is set to false, other references to the same object (from elsewhere in memory) are simultaneously highlighted as dimmer arrows.

Automation settings

The following settings belong to one or both of two settings groups: automation and jumps. The latter is a subset of the former. Use allAutomation and allJumps (above) to set all automation or jumps settings at once.

If you define conflicting settings, the later setting will override the earlier, as appropriate. This is quite useful. For instance, to require students to manually simulate all execution steps except changes of line that are not governed by a branching statement, you can set allAutomation to false, then allJumps to true, and finally jumpBranches to false. (This particular example is a pretty good combination of settings for a visual program simulation exercise, which is why there is a convenience setting defaultVPS that sets up an exercise exactly so. See above.)

Name Group Default Explanation
addFunctionsAutomatically automation true Do not require the user to manually fetch functions to the evaluation area.
addMethodsAutomatically automation true Do not require the user to manually fetch methods to the evaluation area.
addOperatorsAutomatically automation true Do not require the user to manually fetch operators to the evaluation area.
addValuesFromFieldsAutomatically automation true Do not require the user to manually fetch values from instance variables to the evaluation area.
addValuesFromHeapAutomatically automation true Do not require the user to manually fetch values from the heap to the evaluation area.
addValuesFromVariablesAutomatically automation true Do not require the user to manually fetch values from local variables to the evaluation area.
assignFieldsAutomatically automation true Do not require the user to manually assign values to instance variables.
assignParametersAutomatically automation true Do not require the user to manually assign values to parameter variables.
assignVariablesAutomatically automation true Do not require the user to manually assign values to local variables.
createClassInstancesAutomatically automation true Do not require the user to manually create class instances in the heap.
createFramesAutomatically automation true Do not require the user to manually create new frames in the call stack.
defClassesAutomatically automation true Do not require the user to manually define classes.
defFunctionsAutomatically automation true Do not require the user to manually define functions.
evaluateFunctionsAutomatically automation true Do not require the user to manually start function/method calls.
evaluateOperatorsAutomatically automation true Do not require the user to manually apply operators.
initializeCollectionsAutomatically automation true Do not require the user to manually fetch collection initializers and use them.
returnValueAutomatically automation true Do not require the user to manually return values.
goToFunctionDefAutomatically automation, jumps true Do not require the user to manually jump to a function/method when its called.
jumpAutomatically automation, jumps true Do not require the user to manually move on to the following line.
jumpBranches automation, jumps true Do not require the user to manually jump in branching statements.
jumpDefsAutomatically automation, jumps true Do not require the user to manually jump to the next class/method/function definition.
jumpInsideFunctionAutomatically automation, jumps true Do not require the user to manually jump to the function body after the frame has been set up.
goBackAfterReturnAutomatically automation, jumps true Do not require the user to manually go back to the calling line.
selectFieldNamesAutomatically automation true Do not require the user to manually select the names of instance variables.
selectParameterNamesAutomatically automation true Do not require the user to manually select the names of parameter variables.
selectVariableNamesAutomatically automation true Do not require the user to manually select the names of local variables.