Films v1.25 (3rd March 2011)
 Harriet Bazley

PURPOSE OF PROGRAM

This is a basic timetabling program to make it easier to decide which conflicting performances of which films to attend.   Once data on available performances has been entered, the program can display an interactive timetable on the screen, showing the knock-on effects of selecting a given performance in terms of the films with which it clashes.  Dates on which you have prior commitments can be eliminated from consideration altogether.    As you narrow down the possibilities, any films for which there is only one possible performance remaining will be highlighted in red, and a warning will be given for any which cannot be fitted into the timetable at all.


HARDWARE/SOFTWARE REQUIREMENTS

This program is written in BBC BASIC and should run on any RISC OS computer, although it does rely on screen modes 27 (16 colours at 640x480) and 31 (16 colours at 800x600) being available.  However, it requires the !ArmSort application by Martin Avison to have been seen by the Filer.   It can be run from a read-only archive.

The ArmSort module, written and  by Martin Avison, is used with his permission by this application to sort data in BASIC Arrays quickly and easily. ArmSort will sort any number of any type of BASIC array with just a '*Sort Array()' command in your program, and has many other sorting options. Further details and the latest version of the full !ArmSort package and documentation is available from http://www.avisoft.f9.co.uk/.


HOW TO USE THE PROGRAM:   QUICK GUIDE

(Note that Films is a single-tasking application which takes over the entire desktop;  you may want to print out these instructions for reference while using the program.)

Double-click on the application to run it.   Press the 'F' key to enter the name, date and time of a film.   Press 'N' to enter data for subsequent performances of the same film.   Press 'D' at any point to display the timetable so far, and 'F' or 'N' to resume data entry.   Press 'S' to save what you have typed in, and F3 to save without a prompt.

Press 'P' from the timetable display to pick a given performance to attend; press 'U' to change your mind and unselect it again. Press 'X' to exclude an entire day from consideration or 'R' to re-enable it.   Performances which are no longer available are displayed in magenta, matinee (i.e. cheap!) performances are highlighted in yellow and selected performances in green.   Red indicates a film for which there is only one possible performance remaining.   Dark blue indicates an 'excluded' day.   All other performances are listed in white.

Press 'O' to output your current decisions to file for future reference: selected and last-remaining performances will be highlighted in the margin. The directory containing these files will open when you return to the desktop.

Press 'E' to end the program and return to the desktop.   If you have unsaved data a warning will be given.


HOW TO USE THE PROGRAM:   DETAILED REFERENCE

A guide to relevant keypresses is given at the top of both the main data entry and the timetable screen for reference, but note that all keypresses work from both display screens, whether they are listed or not!   Press 'D' to display the timetable from the main screen (provided at least some data is present) and 'M' from the timetable screen to list the main data entry keypresses.

Each performance is assigned a unique code in the form 'a2', 'c1' etc, where the first letter represents the identity of the film and the digit represents the performance number.   For example, three performances of a given film might have the codes 'a1', 'a2' and 'a3' respectively.   These codes are used to identify individual performances, and are displayed on the left-hand end of the row when listing the films.   Certain functions of the program will prompt you to select a given performance by typing in its code.

*DATA ENTRY*

You may enter additional film data at any time by pressing 'F' to start data entry for a new film.   You will be prompted for the film's name, date and performance time (using the 24-hour clock).   Times will be listed in the format "18.10", but any separator is fine, e.g. "18:10" or even "18-10".   The program needs to store a full date, including the year, for certain purposes (e.g. to calculate the correct days of the week), but it will do its best to calculate this automatically - see notes on data entry below.

You may also use the 'F' key to add data on additional performances of a film already listed;  if the name typed is identical to an existing data item, the new performance will be added to the end of the existing set (i.e. will share its code letter) rather than being entered as a new film.  Where two different films in a given season share the same name, a distinction must be made, e.g. "Gaslight (1940)", "Gaslight (1944)".

However, the normal method of adding further performances for the film just entered is to press the 'N' key to enter data for the next performance;  to save typing, this will list the film's name in yellow, and prompt for date and time only.   Note that for ease of data entry, once you have entered the month name on one occasion the program will prompt you with the same month thereafter, and you need only type "9", "15", "22" etc - if you ignore the prompt and type a different month name, this will then become the new default.   Note also that you need only type the first three letters of the month's name for the program to identify it correctly.

Since in an overwhelming number of cases the appropriate year for each entry can be predicted by standard criteria, you will not be prompted for this at all (and if you do enter it, this portion of the date will be ignored).   The program simply looks at the current date and hence assumes that all months preceding this one must be references to next year, e.g. specifying a date of '17 Jan' in November 2006 will automatically enter it as '17 January 2007', whereas '17 Dec' would be treated as '17 December 2006'.   If required, the year supplied for a given performance can subsequently be altered manually via the correction dialogue - see below.


If you make a mistake during data entry, the 'C' key will automatically bring up the correction dialogue for the last performance entered.   It will prompt you to confirm the film's name, date and (separately) year, and time - pressing the Return key without entering any data will use the existing value, while entering a new value will update the data.  Note that, in an effort at sanity checking, neither dates prior to 2000 nor those more than ten years into the future will be accepted!   Note also that you can use the Copy and cursor arrow keys (labelled 'End' on a PC-style keyboard layout) to copy from the prompt line above:   use the arrow keys to move the cursor, and the Copy key to copy text to the input line while editing.

You may also use the 'I' key to correct the data for any performance rather than just the most recently entered item:   however, you will need to know the performance code, so this function is only really of use from the timetable display screen.   If you enter a valid performance code, you will be prompted to confirm or replace the data for that performance as above.

Press 'D' at any time to display or refresh the current timetable, giving a summary of what you have typed so far.   Press 'M' to restore the main data entry menu.   If you have typed in more data than can be displayed on the normal size screen (i.e. more than approx. 60 possible performances in total!) the program will automatically redraw the display in a larger screen mode.


*LOADING AND SAVING*

Typing in performance data is a tedious process, and the program allows you to save it and then make or update your decisions later, when time and failure to 'get round to it' have narrowed down the options a little!   Files are always stored in the !Films.data directory within the application, and the current contents of the directory will be listed to screen to show you what is already there:   there are no 'file management' (i.e. rename, delete, move) options as it is assumed to be more convenient to do this from the RISC OS Filer.

Press 'S' to save the current data in memory.   The default name for the file will be that of the month last used when entering dates - press Return to accept this, or type something else.   Any existing file of that name will be overwritten without warning.

Pressing 'F3' will activate the 'quicksave' function to save the current data to disc without prompting for a filename;  the default month name or the name under which it was loaded will be used.

Press 'L' to load data from file, restoring all previously-saved decisions.   You will be prompted to enter a file name;  again, you can use the Copy cursor to copy from the filenames listed onscreen if more convenient.   This will overwrite any data currently present in memory;  however, you can type in further performances subsequently and resave the file.   (Note that loading a data file will also set what is considered to be the 'current' month for entering dates, and the default save name for resaving it back to disc.)


*DATA MANIPULATION*

The donkey-work of typing in the performance data is only the start;  the point of this program is to make it easier to do something with it!   Once you have displayed a timetable for the current month's films, either after entering all the details or, more commonly, after reloading them from a previous session, the aim is to work out a manageable schedule of performances to attend.
When you make a definite decision to pick a given performance of a given film, the program will display the effects this decision has on the availability of other film performances, e.g. if you attend film A on a Wednesday, this may mean that you have to attend film B on the following Tuesday or not at all, which in turn may mean that you have to take the more expensive performance of film C if you are to attend that house-warming party pencilled in for next Saturday....

You have two basic tools at your disposal:   you may select individual performances (which will automatically eliminate from consideration all other potential performances of that film, plus all performances of other films that clash with the selected one), and you may exclude entire days from the timetable, thus eliminating all performances on that evening.   The program will highlight the cheaper matinee performances (currently hardwired in as all day Tuesday, Mondays to Thursdays before 7pm and Fridays before 5pm) in yellow, and will check each film to see how many, if any, of its potential performances remain open for selection.   If there is only one left then it highlights that performance in red:  use it or lose it!   If there are none left at all, either because you have selected other films which clash with all of them or because all possible dates are now in the past or otherwise disabled, it will beep and flash up the names of any such films above the timetable in red, allowing you either to try a fresh set of choices or abandon the intention of attending this film altogether - see below.

Pressing 'D' will redraw the display if it has been overwritten (e.g. by warning messages) and display the relevant keypresses for the timetable screen.


Press 'P' to pick a given performance to attend.   This will highlight it in green and dim all other performances of this film to magenta.   It will also dim out any simultaneous clashing performances of other films:   note that this is defined as all performances on that day starting up to ninety minutes earlier or later, so that selecting a film at 6.40 would disable films starting at 6.15, 5.55 or 7pm

If you wish to change your mind about which performance of a given film to attend, press 'U' and type in the performance code to unselect the highlighted film, making all the other performances available again - unless, of course, they clash with something else!  You may also press 'P' and select one of the alternative performances, which will attempt to highlight that one instead and dim out the first;  the program distinguishes internally between films that clash and those that are simply non-preferred performances, and will warn you if this is not possible.

Press 'X' to exclude an entire day from the timetable, dimming it to dark blue, if you know that for some reason it is out of the question to attend on that day, e.g. you are going to be out (or, conversely, are required to be in....) - you will be prompted to specify the year separately, in the extremely rare case that this should be necessary.

Note that the 'exclude' feature deliberately does NOT override any films that have already been selected for that day (although if you unselect them they will duly show up as disabled and the program will calculate for last remaining performances, etc) - this allows the 'catch up to today' function to work, and also makes it possible to select, say, the early performance but then manually exclude all the later performances of other films on that same day.   You should therefore either apply common sense or else when scheduling make sure that you mark all excluded days first!

Related to this is the 'T' ('catch up to today') function, which checks today's date and time and automatically excludes all performances which have already elapsed, triggering any associated warnings;  this is very useful for seeing what's left after you have reduced the possibilities by the simple technique of letting matters slide for some time....   Note that it is a good idea to select in green any optional (white) performances which you may have actually attended in the interim before using this function, both in order to eliminate any remaining alternative performances from clogging up the timetable, and to avoid spurious warnings about them.

Press 'Y' to restore any day previously excluded by either manual or automatic means (with the expected effects on last-remaining performances, etc.)

Press 'A' to abandon a given film, i.e. remove all of its performances from the timetable.    You may type either the exact NAME of the film or else its performance code - only the first letter, common to all performances of a given film, is significant here.  (Note that the program treats all responses of two or fewer letters as performance codes;  thus films such as Fritz Lang's "M" cannot be specified by title!)   This function is normally used to avoid repeated warnings that the film is not available, since otherwise the program will keep reminding you until you alter your timetable to accommodate it.

You may also press 'R' from this screen to remove a performance entered in error, or 'I' if you notice a mistake in previously-entered data, invoking the 'correct individual item' function described above under 'DATA ENTRY'.   Press 'M' to get back to the menu of data entry keypresses.


*SUMMARY OUTPUT*

Since the program takes over the entire desktop, it is not particularly convenient to have to re-run it and type in the name of a data file, let alone switch on and boot up your computer, every time you want to check your timetable for forthcoming events - nor is it very practical to snapshot the screen and print out the colour-on-a-black-background results.   I have therefore provided a function to save out a simple output list as a text file which can either be read from the desktop or else printed out, stuck in a pocket, and taken away with you.

Press 'O' to output the current list of potential performances to file.   All such files are saved into the directory !Films.Output, and if you save an output file this directory will be opened for easy access once you return to the desktop, with the current file listed at the top.   You will be prompted for a name to save it under - again, the default is that of the 'current' month of data entry.

The output will be saved in the form of a list of date headings followed by the details of all remaining (i.e. not dimmed-out) performances for that day, one performance per line, indented with a tab character:

Mon 18 July
	 2.30 Pursued
*	 8.45 Thunder Road
Tue 19 July
>	 6.20 The Princess Comes Across
Wed 20 July
	 6.20 Pursued
Fri 22 July
	 2.30 Mr and Mrs Smith
>	 6.30 My Man Godfrey

'Last remaining' (red) performances are marked by a '>' character at the start of the line, and 'definitely plan to attend' (green) performances are marked by a "*".   The rest of the colour codes are not represented: other films either appear as undecided possibilities or are omitted altogether.   Note that in order to eliminate clutter and confusion, if a day contains nothing but dimmed-out performances or if no performances are listed on that date at all - e.g. Thu 21 July above - no such heading will appear on the list.   


Saving output lists is quite separate from saving the actual performance and decision data itself;  you can fiddle around producing several different timetable combinations and save them under different names without affecting the stored data file at all (unless you subsequently save it back using the 'S' key).


*ENDING THE PROGRAM*

Finally, it is worth noting that pressing 'E' (rather than simply quitting via the Escape key...) will warn you of unsaved data before ending the program.   This covers decision data as well as edits to film names and times:   if you alter your performance selections, you will be prompted to save the file again to reflect these changes when you next reload it.   You may, of course, wish to discard the results of your experimentation, in which case simply press 'y' to confirm that you wish to exit.



FILE FORMAT

The data file format may be added to or edited by hand if you know what you are doing:   the data is sorted on loading and performance codes subsequently generated, so data may be added in any order.   An attempt is made to check that the format is as expected, and if the file appears to be corrupted the program will give an error message and refuse to load it.   Paranoid users should note that an error while attempting to SAVE a data file will cause the half-completed file to be wiped... thus deleting the previous version if saving back under the same name!   Output list files, on the other hand, may be edited freely as they are not machine-readable.

The file format is as follows:

<year>	<date>	<time>	<selection flags>	<title>

Each field must be separated by one, and only one, tab character.   The date is saved by default in the format "7 December", although dates in the format "07 Dec" can also be read back.   The year must be given as a four-digit value, e.g. "2007".

The time is saved by default in the format "18.10", but the hours/minutes separator can be any non-numeric character, e.g. "18:10" is equally valid.

The selection flags are stored as a single hexadecimal value, although some of the bits are recalculated on loading: a safe default value is &0.   The program expects the leading '&' and will refuse to load the file if it is absent.   The flag bits are as follows:

Bit 0: item is selected				displayed as green
Bit 1: (recalculated)matinee performance	yellow
Bit 2: non-preferred performance		magenta
Bit 3: excluded day				dark blue
Bit 4: performance clashes			magenta
Bit 5: (recalculated)last remaining performance	red

The title value is a simple string which may contain any literal character except a tab.   It should not be enclosed in quotation marks.