5.1. InstructorInterface

(****
 *
 * Module InstructorInterface defines the basic objects and operations used by the instructor
 * interface. The instructor interface defines a workspace which will be used to open multiple documents.
 * Some of those documents include the Tests, QuestionBank(Shared and Local). Also the instructor uses the interface
 * to administer tests and upload them to the grader tool. These operations are defined in their respective modules in detail.
 * The interface simply provides the means for those documents to exist in the workspace.
 *)
module InstructorInterface;

from TestGeneration import Test,Wizard;
from InstructorFile import FilePermissions;
from StudentInterface import length;
from InstructorEdit import PreviousState;
from TestAdminister import TeacherView;
from TestGrading import TestGradingView;
from QuestionBankModule import QuestionBank,QuestionBankSettings,LocalQuestionBank,SharedQuestionBank;
export TestFile, InstructorWorkspace,FileSaveDialog, Text, HighlightedText,
    FileName, Location, FileOpenDialog, FileSaveDialog,InstructorUserName, InstructorPassword,InstructorLogOnScreen, IsValid;

object TestFile is
    components: fp:FilePermissions and t:Test and lqb:LocalQuestionBank and sqb:SharedQuestionBank;
    operations: Save,SaveTestAs,OpenTest;
    description: (*
        A TestFile is the file representation of a test. The InstructorWorkSpace
        uses TestFile objects to open or save tests modified in the student
        interface. A TestFile must be readable and writable and can be saved
        on a computer accessible to the instructor.
    *);
 end TestFile;

object Text is
    components: str:string and ps:PreviousState;
    operations: CopyText,PasteText;
    description:(* Text is simply a string on which edit operations can be performed
    *);
end Text;

 object HighlightedText is
    components: str:string and l:length;
    operations: CutText,CopyText;
    description: (*
        A HighlightedText object is a section or an entire body of text selected
        to be edited. The text can be cut, copied, erased, or replaced by another
        section or body of text. Any text that is highlighted should stand out from
        the rest of the text. The text should be bolded or be displayed in a different
        color than the rest of the text so the student can distinguish between
        highlighted and non-highlighted text.
    *);
 end HighlightedText;
object InstructorUserName is
    components: str:string and valid:IsValid;
    operations: InstructorLogOnScreen, ExportToGrader;
    description: (*
        An InstructorUserName is a unique string that instructors use to authenticate
        themseleves as and when needed in the Instructor Interface
     *);
 end InstructorUserName;

 object InstructorPassword is
    components: str:string and valid:IsValid;
    operations: InstructorLogOnScreen,ExportToGrader;
    description: (*
        A Password is a unique single encrypted string. Instructors use their individual passwords
        along with their user names to authenticate themselves as and when needed in the 
        instructor interface.
    *);
 end InstructorPassword;
object IsValid is boolean
    operations: ServerLocation,ExportToGrader;
    description:(*
                 * This is the variable that is set after the instructor's username and password are vaidated by the system
                  *);
end IsValid;
object InstructorLogOnScreen is
    components: un:InstructorUserName and ps:InstructorPassword;
    description: (*
        An instructor types in their Calpoly User ID and password into the Log on screen
        to gain access to components of the Instructor interface.
    *);
 end LogOnScreen;

object InstructorWorkspace is
    components: t:Test and lqb:LocalQuestionBank and sqb:SharedQuestionBank and los:InstructorLogOnScreen and wiz:Wizard and tv:TeacherView
            and qbs:QuestionBankSettings and tgv:TestGradingView and qb:QuestionBank;
    operations: NewTest,OpenTest,ExitInstructorInterface,AdministerTest,GradeTest,PassBackTest,closeGradedTests,ExportToGrader,OpenQuestionBankSetting,
            OpenLocalQuestionBank,OpenSharedQuestionBank;
    description: (*
              * The InstructorWorkSpace is the work space the instructor uses to generate tests,
              *    connect to questions banks, edit tests, and grade tests within the instructor interface.
              * It displays the operations of the InstructorFile, InstructorEdit, InstructorTests ,
                      * and InstructorQuestions modules as menu items titled
              *    "File", "Edit", "Tests", and "Questions". The previous_state component is used to support
              * one level of command undo. The Clipboard is used with the cut, copy, and paste operations.
              *);
end InstructorWorkspace;

object FileName is string
    description:(*The name of a file that can be opened in the workspace*);
end;

object Location is string
    description:(*Location specifies where the file is located*);
end;

object FileOpenDialog is
    components: FileName and Location;
    description: (*
              * The FileOpenDialog is the dialog interface where a student may select only
              * a test file to open into the student interface from a specific directory.
                      *);
end FileOpenDialog;

object FileSaveDialog is
    components: FileName and Location;
    description: (*
              * The FileSaveDialog is the dialog interface where an instructor may save the test
              * or a question bank displayed in the instructor interface to a specific directory.
                  *);
end FileSaveDialog;

end InstructorInterface;



(****
 *
 * Module Instructor File defines the operations related to generating a new test,
 * opening an existing test, saving , printing , and exiting from the instructor
 * interface. The following objects are taken from the Calender Tool program: FilePermissions,
 * IsReadable, IsWritable, FileType, TestType, FileData, RequiresSaving.
 *)
module InstructorFile;

from InstructorInterface import TestFile, Test, FileSaveDialog, InstructorWorkspace;
from TestGeneration import Wizard;
from QuestionBankModule import QuestionBank, SharedQuestionBank,LocalQuestionBank;
export FilePermissions, IsReadable, IsWritable, FileType, TestType, FileData, RequiresSaving;

object FilePermissions is
    components: ir:IsReadable and iw:IsWritable;
    operations: OpenTest;
    description: (*
              * FilePermissions are permissions indicating if a file is readable and/or
              * writable.
                  *);
end FilePermissions;

object IsReadable is boolean
    operations: OpenTest;
    description: (*
              * A flag indicating if a file is readable, which must be true to carry out the
              * OpenTest operation.
                  *);
end IsReadable;

object IsWritable is boolean
    operations:OpenTest,Save,SaveTestAs;
    description: (*
              * A flag indicating if a file is writable, which must be true to carry out the
              * SaveTest and SaveTestAs operations.
                  *);
end IsWritable;

object FileType is TestType
    operations: OpenTest;
    description: (*
              * The type of file used by the student interface where data is of TestType
                  * and can be stored in a file.
                  *);
end FileType;

object TestType is
    operations: OpenTest;
    description: (*
              * File data tag that indicates if a file contains Test data made by the Test
              * Tool program.
                  *);
end TestType;

object FileData is Test
    operations: OpenTest;
    description: (*
              * FileData is a representation of a Test object. When implementing FileData,
              * any file data object may be used that accurately holds a Test object.
                  *);
end FileData;

object RequiresSaving is boolean
    description: (*
                  * NeedsSaving is true if a test has been edited, which is true if one or more
                  * successful edit operations has been performed on the displayed test since the
                  * most recent save. The test edit operations are Undo, Redo, Cut, Copy, and Paste.
    *);
end RequiresSaving;

operation NewTest is
        inputs: iws:InstructorWorkspace;
        outputs: iws':InstructorWorkspace;

        description: (*
                  * Activates the test generation wizard
                      *);

        precondition: true;
       
        postcondition:
        (*
         * The workspace has a new wizard. It will require saving.
         *)
        (iws = iws');
end NewTest;

operation OpenTest is
    inputs: iw:InstructorWorkspace and tf:TestFile and permissions:FilePermissions and fd:FileData
        and ft:FileType and ir:IsReadable and tt:TestType;
    outputs: t:Test, iw':InstructorWorkspace;
    description: (*
              * OpenTest will open a test file from a specific directory and display it in
              * the instructor interface. The student may only open test files in the
              * operation and not any other type of file.
                  *);
     precondition:
           (*
         * A test file must exist and be located in a directory that is accessible by the
         * student. The file must also be readable and the type of the file must be of type
         * test. This precondition is taken from the precondition of the FileOpen operation
         * of the Calander RSL specification.
         *)
        (exists (tf:TestFile) (tf.fp.ir));

     postcondition:
           (*
         * The test file is opened into the instructor interface filling in the entire
         * instructor interface area.
         *)
        (iw'.t = tf.t);
end OpenTest;

operation Save is
    inputs: t:Test and fsd: FileSaveDialog and iw:IsWritable; 
    outputs: tf':TestFile;
    description: (*
              * SaveTest will save any changes made to the currently displayed Test in the
              * instructor interface to the test file that contains the test. This option only
              * updates the test file with the new changes that are not contained in the
              * old test file and the file must be writable.
                  *);   
precondition:
    (*
     * A test file must exist and be present within the instructor interface. IsWritable must
         * be true.
     *)
    (exists (tf:TestFile) (tf'.t = t) and (tf'.fp.iw = iw));

postcondition:
    (*
     * Changes must have been made to the test in the instructor interface that are not
     * contained in the old test file, or the test was newly created.
     *)
    (tf'.t = t) and (tf'.fp.iw) and (tf'.fp.ir);
       
end Save;

operation SaveTestAs is
    inputs: t:Test and qb:QuestionBank and fsd:FileSaveDialog and iw:IsWritable;
    outputs: tf':TestFile;
    description: (*
        SaveTestAs will save the test file currently displayed in the instructor's interface
        as a new file in a specific directory. This operation can either create a new
        file with a new name or overwrite an old file that is writable with the same name.
        If overwriting a file with the same name, the instructor must be prompted that saving
        the test file will overwrite the old file and if he wishes to continue.
    *);

 precondition:
    (*
     * A test object must exist as an object that can be saved as a file and be displayed
     * in the instructors interface.
     *)
    (t != nil) and (qb != nil);

 postcondition:
    (*
     * A test file is made from the test object currently displayed in the instructors interface
     * under a file name of the his choosing. The test file is saved in a directory
     * accessible by the instructor.
     *)
    (tf'.t = t) and (tf'.fp.ir) and (tf'.fp.iw);

 end SaveTestAs;

object UserWantsToSave is boolean
    description: (*
        UserWantsToSave is a state that tells the instructor interface if the instructor
        wants to save the changes made to a test.
    *);
 end UserWantsToSave;
operation ExitinstructorInterface is
    inputs: iw:InstructorWorkspace and tf:TestFile and uwts:UserWantsToSave;
    outputs: tf':TestFile;
    description: (*
        ExitinstructorInterface will close the Instructor interface and exit the program. If
        there is a test or a question bank in the Instructor interface that has been changed but not saved,
        a prompt will appear asking the Instructor if he would like to save the changes
        to the test before exiting the Instructor interface.
    *);

 precondition:
    (*
     * The Instructor can exit the application anytime during a session.
     *)
     true;

 postcondition:
    (*
     * If a test or a question bank is displayed in the Instructor interface that has been changed but not saved,
     * the Instructor is asked if he would like to save the changes to it before exiting.
     *)
    if(iw.t != nil) or (iw.lqb != nil) or (iw.sqb != nil) then
        (if (uwts) then
            (tf'.fp.iw and tf'.fp.ir and tf'.t = iw.t)
            and
            (tf'.fp.iw and tf'.fp.ir and tf'.lqb = iw.lqb)
            and
            (tf'.fp.iw and tf'.fp.ir and tf'.sqb = iw.sqb)
           
        else
            (tf' = tf))
    else
        (tf' = nil);

 end ExitInstructorInterface;

end InstructorFile;



(****
 *
 * Module Instructor Edit defines the operations related to undo and redo.
 * The following object definitions are taken from the Calander RSL specifictations:
 * Clipboard, TextSelection, StartPosition, EndPosition, Context, and State.
 *)

module InstructorEdit;

from InstructorInterface import Text, HighlightedText, InstructorWorkspace,length;
export Clipboard,State, PreviousState;

object Clipboard is
    components: str:string and l:length;
    operations: CutText,CopyText,PasteText;
    description: (*
        Clipboard is a buffer that stores the TextSelection temporarily
    *);
 end Clipboard;

object State is boolean
    description: (*
              * State is a flag indicating if a change has been made to a test displayed in the
              * instructor interface.
                  *);
end State;

object PreviousState is State
    operations:UndoChange;
    description: (*
        PreviousState is a state of a test before the most recent change.
    *);
 end PreviousState;   

object PreviousText is Text
    operations:UndoChange;
    description: (*
        PreviousText is the original text before any recent change.
    *);
 end PreviousText;   
operation UndoChange is
    inputs: txt:PreviousText and ps:PreviousState;
    outputs: txt':Text;
    description: (*
        UndoChange reverts the most recent change made to the currently displayed Test
        in the student interface. The UndoChange operation can only undo changes made to
        the text answer of a question made by a student. The UndoChage operation can be
        used only one time.
    *);
   
 precondition:
    (*
     * Some text must exist in the test and the text must have been changed at least once
     * before the UndoChange operation can be used.
     *)
    (txt'.ps);

 postcondition:
    (*
     * The most recent change to the text on the test is reverted back to its original
     * form before the most recent change was made.
     *)
    (txt' = txt);

 end UndoChange;

operation CutText is
    inputs: htxt:HighlightedText and cp:Clipboard;
    outputs: ;
    description: (*
        CutText will remove a piece of highlighted text from the test currently displayed
        in student interface. The text will not be deleted, but will be temporarily saved
        on the Clipboard until he decides to put it back onto the test.
    *);
 precondition:
    (*
     * Some text must exist in the test and the student must manually highlight the text to
     * be cut from the test.
     *)
    true;
 
 postcondition:
    (*
     * The highighted text is cut out from the test and saved as a temporary file on the
     * Clipboard.
     *)
    (htxt.l = 0) and (cp.str = htxt.str);
 end CutText;

 operation CopyText is
    inputs: htxt:HighlightedText and cp:Clipboard;
    outputs: cptxt:Text;
    description: (*
        CopyText will copy a piece of highlighted text from the test currently displayed
        in the student interface. The copied text is saved on the Clipboard until the
        student decides to put the copied text back onto the test.
    *);
 
 precondition:
    (*
     * Some text must exist in the test and the student must manually highlight the text to
     * be copied from the test.
     *)
    true;

 postcondition:
    (*
     * The highlighted text is copied from the test and saved as a temporary file on the
     * Clipboard.
     *)
     (cp.str = htxt.str);

 end CopyText;

 operation PasteText is
    inputs: ctxt:Text and cptxt:Text and cb:Clipboard;
    outputs: Text;
    description: (*
        PasteText will place the string currently in the buffer to the current location of the
        cursor in the active document*);
   
 precondition:
    (*
     * The clipboard is not empty.
     *)
    (cb.str != nil);

 postcondition:
    (*
     * The text retrieved from the clipboard is placed to the current location of the cursor
     *)
    true;

 end PasteText;


end InstructorEdit;



(****
 *
 * Module InstructorTests defines the objects and operations related to administering a test,  
 * grading tests, passing back tests, and exporting to the grader within the instructor
 * interface.
 *)

module InstructorTests;

from InstructorInterface import Test, TestFile, InstructorWorkspace,InstructorUserName,InstructorPassword,IsValid;
from QuestionModule import CorrectAnswer,QuestionText,Answer;
from TestAdminister import Status, QuestionView, CurrentQuestion, TeacherView, TestView,ClassTests;
from TestGrading import TestGradingView;
from InstructorFile import FilePermissions;
export Accessible;

object Accessible is boolean
    operations: GradeTest;
    description: (*
        Accessible is a flag indicating if a LocationAddress is accessible to the instructor from
        the instructor interface.
    *);
 end Accessible;

object IsAvailable is boolean
    operations:PassBackTest;
    description:(* This is a flag to notify the system that the graded test is now available for the
        students to view*);
end;

operation AdministerTest is
    inputs: iw:InstructorWorkspace;
    outputs: iw':InstructorWorkspace,tv:TeacherView;
        description: (*
                      * The teacher view of administering a test is displayed in the instructor workspace.
                      *);
        precondition:
        (* The instructor can run this operation anytime he is ready to administer a test*)
        true;
    postcondition:
        (*
         * The proctoring window is displayed in the intructor's interface
         *)
        (iw'.tv = iw.tv);
end AdministerTest;

operation GradeTest is
    inputs: iw:InstructorWorkspace, a:Accessible, t:Test, ct:ClassTests;
    outputs: iw':InstructorWorkspace, tgv:TestGradingView;
    description: (*
              * The instructor opens up the test that needs to be graded. This will open up the
            Test Grading View.
              *);
    precondition:
        (*
         * A graded test file exsts and must be part of classtests.
         *)
        exists (t:Test) t.aq != nil;
    postcondition:       
        (* After the test file has been verified that it exists and is answered then, the workspace will have the test grading view
           displayed.*)   
        iw'.tgv = iw.tgv;
end GradeTest;

operation PassBackTest is
    inputs: iw:InstructorWorkspace,t:Test,ct:ClassTests, ia:IsAvailable;
    outputs: iw':InstructorWorkspace;
    description: (*
              * The instructor makes the graded exam available for students who can then check their grades
              *);
    precondition:
        (*
         * The graded test exists
         *)
        exists (t:Test) t.gq != nil;
    postcondition:
        (*
         * The graded test is now made available to students
         *)
        t.ia;
end PassBackTest;

operation closeGradedTests is
    inputs: iw:InstructorWorkspace, t:Test;
    outputs: iw':InstructorWorkspace;
    description:(*After the gradedtest has been made available by the instructor, he may wish to close it
            so that no new student can access his test.This operation will make the graded tests unavailable*);
    precondition:
        (*The graded tests should be available*)
        t.ia;
    postcondition:
        (*The graded tests have now been made unavailable*)
        not(t.ia);
end closeGradedTests;

object ServerLocation is
    components: str:string, valid:IsValid;
    operations: ExportToGrader;
    description:(*This is a pre determined location for the grader server.*);
end ServerLocation;

operation ExportToGrader is
    inputs: iw:InstructorWorkspace,t:Test,ct:ClassTests,un:InstructorUserName,ps:InstructorPassword, valid:IsValid, sl:ServerLocation;
    outputs: iw':InstructorWorkspace;
    description: (*
              * The instructor takes all taken tests and export them to the grader tool
              * for grading.
              *);
    precondition:
        (*
         * The test to be exported to the grader tool must be graded by the instructor. The loacation for the
         * grader server is a valid location. Also the instructor needs a valid user name and password to export a test
         * file to the grader tool
         *)
        exists (at:AnsweredTest) t.gq != nil;
    postcondition:
        (*
         * If the userName, Password and location is valid, then the chosen test will be exported to the
         * grader tool
         *)
        if(un.valid and ps.valid) then
        Export(sl)
        else
            iw' = iw;

end ExportToGrader;
function Export(sl:ServerLocation) -> (boolean) = sl.valid;
end InstructorTests;



(****
 *
 * Module InstructorQuestions defines the objects and operations related to setting up
 * local and shared question banks, connecting to local question banks, and connection to
 * shared question banks within the instructor interface.
 *)

module InstructorQuestions;

from InstructorInterface import InstructorWorkspace,InstructorLogOnScreen,InstructorUserName,InstructorPassword,IsValid;
from InstructorTests import Accessible;
from QuestionBankModule import QuestionBank, LocalQuestionBank,SharedQuestionBank,QuestionBankSettings,
                LocalQuestionBankSettings,SharedQuestionBankSettings,LocalBankProfile,BankName,BankLocation,
                BankUserList,BankAdministrator,BankUR,Username,Password,SharedBankProfile;

operation OpenQuestionBankSetting is
    inputs: iw:InstructorWorkspace, qbs:QuestionBankSettings;
    outputs: iw':InstructorWorkspace;
    description: (*
              * The instructor uses this option to setup his question bank setting. This will include
              * local and shared question bank settings.
              *);
    precondition:
        (*
         *No other questionBank or QuestionBankSettings window should be open.
         *)
        iw.qbs = nil and iw.lqb = nil and iw.sqb = nil;
    postcondition:
        (*
         * The instructors workspace now contains the dialog to change question bank settings
         *)
        iw'.qbs = qbs;
end OpenQuestionBankSetting;

operation OpenLocalQuestionBank is
    inputs: iw:InstructorWorkspace, qbs:QuestionBankSettings;
    outputs: iw':InstructorWorkspace;
    description: (*
              * The instructors can use this option to open up the local question bank, where he can edit questions.
              *);
    precondition:
        (*
         * The question bank exists within the instructor's local hard drive.
         *)
        iw.lqb = nil and #(qbs.Lqbs.Lbp) > 0;
    postcondition:
        (*
         * The question bank is opened up in the Instructor Interface.
         *)
        iw'.lqb = qbs.Lqbs.Lbp[1].lqb;
end OpenLocalQuestionBank;

operation OpenSharedQuestionBank is
    inputs: iw: InstructorWorkspace, qbs:QuestionBankSettings;
    outputs: iw':InstructorWorkspace;
    description: (*
              * The instructor enters his username and password in or to connect to the shared
              * question bank. Once connected, the shared question bank opens within the
              * instructor's interface.
              *);
    precondition:
        (*
         * The log on screen appears and the username and password are authenticated by the system. If they are valid, then the shared
         * question bank will appear in the instructors interface.
         *)
         iw.sqb = nil and #(qbs.Sqbs.sbp) > 0 and exists(bur' in qbs.Sqbs.sbp[1].bul.bur) (qbs.Sqbs.sbp[1].un = bur'.un)
        and (qbs.Sqbs.sbp[1].pw = bur'.pw);

    postcondition:
        (*
         * The shared question bank is displayed within the instructor's interface.
         *)
        iw'.sqb = qbs.Sqbs.sbp[1].sqb;
end OpenSharedQuestionBank;

end InstructorQuestions;