#! /usr/NeWS/bin/psh
%
% journalling - Install the journalling package (NeWS/journal.ps).
%
%		@(#)journalling 9.3 88/01/18
%
% Steven Isaac 8/25/87
% - based on original journaling code written by Jerry Farrell
%
% Overview
% --------
% The Journalling package allows you to start and stop record NeWS mouse 
% and keyboard events onto a file, and then play the file back. This results 
% in NeWS acting like a player piano, faithfully duplicating the original
% user actions in real time. 
% 
% This package permits continuous replaying of a given file. Playback can
% be interrupted at any time by clicking one of the mouse buttons.
% 
% Journalling also includes playback speed control, which allows you to slow
% down or speed up the playback rate.
% 
% Use
% ---
% Invoking this program will add a 'Journalling =>' menu item to the root menu. 
% Note that it will take a few seconds for journalling to load everything 
% into the NeWS server.
%
% There are five submenus under the main Journalling menu item:
% 
% Control Panel	   - Brings up the Journalling control panel
% Start Recording    - Start recording on the current Record file
% Stop Recording     - Signals the end of recording
% Playback           - Starts playback of the current Playback file
% Remove Journalling - Gets rid of all journalling menus and resources
% 
% Note that Playback can be interrupted at any time by hitting one of
% the mouse keys.
% 
% Selecting the Control Panel item brings up a control panel window. It
% contains the following items:
% 
% 	- RECORD, STOP, and PLAY buttons: These buttons perform the same 
%           function as the corresponding menu items. They also light up to 
%           indicate what action is currently taking place. They can be used 
%           interchangably with the menu items.
% 
%         - Record File: This text item allows you to specify the current file 
%           to record onto. It can be any valid filename on the server machine. 
%           Relative pathnames are taken to be relative to the directory
%           that NeWS was started from. The default for the Record file is 
% 	  "/tmp/NeWS.journal".
% 
% 	- Playback File: The current file to playback from. It has the same 
% 	  characteristics as the Record File.
% 
% 	- Play Forever toggle switch:  If this switch is on then Journalling 
% 	  will automatically repeat playing the Playback File.
% 
% 	- Playback Speed: Slider that scales the playback time. Positive 
% 	  values make playback speed up, negative values make playback slow 
% 	  down. This facility is dependent on the speed of the underlying 
% 	  hardware. It is not calibrated between different machines.
% 
% 	- Done: The Done button will hide the Control Panel. It can be brought 
% 	  back up by selecting the 'Control Panel' menu item. The Zap window 
% 	  command has the same effect.
% 
% Tips For Using Journalling
% --------------------------
% 1. When creating journals that will be replayed repeatedly, it is important
%    to get rid of whatever windows you have created at the end of the 
%    journal. The state of the screen should be just as it was when the
%    journal was begun. Otherwise, the NeWS server will eventually run out
%    of memory because you are continually creating new windows. Doing a
%    'Zap All' at the end of the journal will provide the desired effect.
% 
% 2. There is a noticible variation in performance on NeWS running on 
%    different kinds of machines; it runs much faster on a Sun 4 than on
%    a 3/50! This means that playing back a script recorded on a fast machine
%    might not always work correctly on a slower machine. A given machine
%    can handle NeWS events at some maximum rate. The Playback Speed Control 
%    will allow you to adapt playback speed of a given script to a fairly
%    wide range of machines; unfortunately, this requires a bit of trail and
%    error. 
% 
% 3. Care must be taken when recording sequences that contain a mouse click 
%    resulting in something being displayed at the place where the mouse
%    was clicked; ie. menu pop ups, shaping windows, etc. The mouse must
%    not be moved until the menu or bounding box is up on the screen. If
%    the mouse is moved, the wrong menu selection or window sizing will 
%    be made on playback. This is actually due to a bug in the litewindow
%    package. This restriction should go away when this is fixed.
%
(Journalling =>) /searchkey rootmenu send {
    pop % the index
} {
   /hourg /hourg_m framebuffer setstandardcursor
   pause
   systemdict /Item known not { (NeWS/liteitem.ps) run } if
   pause
   systemdict /Journal known not { (NeWS/journal.ps) run } if 

   JournalUI {def} forall	% Include all of JournalUI in our userdict
   startlistener		% Start the journalling process
   createcontrolpanel		% Create our window

   % Add a root menu entry for journalling
   /journalmenu [
	(Control Panel)    { {displaycontrolpanel} journaldoit }
	(Start Recording)  { {recordnotify} journaldoit }
	(Stop Recording)   { {stopnotify} journaldoit }
	(Playback)         { {playnotify} journaldoit }
	(Remove Journalling) { {killcontrolpanel} journaldoit }
	] /new DefaultMenu send def

   0 (Journalling =>) journalmenu /insertitem rootmenu send

   /ptr /ptr_m framebuffer setstandardcursor

} ifelse  % Journalling is not already installed...