Documentation for DiskLister 1.0 

                                17.3.93.

                  Written by Gary Smith and Charles Hawes.

                              P.O. Box 550,
                              Hamilton,
                              Queensland,
                              Australia, 4007.


   Ed: Included is an unbound deck in CanDo 1.6. Unfortunately, lack of space
  prevents us from including DeckBrowser - however, anyone interested in this
  program will be likely to have either CanDo or DeckBrowser. Alternatively,
  you can find DeckBrowser on Megadisc #30 in the C directory of the B disk,
  so just copy it to the C directory of the disk which you drag the
  DiskLister drawer to, and then just double-click on DiskLister.


   <> 34 <%> 34 <%> 34 <%> 34 <%> 34 <%> 34 <%> 34 <%> 34 <%> 34 <%> 34 <>


   DiskLister is public domain and can be distributed freely.  DiskLister is
  a program to catalogue floppy disks. It was born out of the frustration of
  looking through hundreds of floppy disks, looking for a file that we knew
  was on one of them. We tried several other disk catalogue programs, but
  there was always at least one thing wrong with each of them. So we decided
  to write our own.

   DiskLister has been written in CanDo 1.6. It is provided as an unbound
  deck, as an example of CanDo programming. Some of the features that
  DiskLister uses are Cycle gadgets, AppWindows, and using requesters. By
  loading DiskLister into CanDo, you can see how we have produced these
  features. We do not suggest that these are the 'proper' way to do these
  things, but it is the way we have done them.  It is assumed that you have
  at least a working knowledge of CanDo. If you do not have the CanDo
  program "DeckBrowser" or CanDo itself, then you will not be able to run
  DiskLister.  Note that the provided deck has been produced for a PAL
  screen, and will open on an interlaced screen if you have a NTSC system.
  Because DiskLister has been provided as an unbound deck, you can load
  DiskLister into CanDo and change the screen arrang ement to suit yourself.
  DiskLister offers scope for you to add your own features, and customize the
  program to your own likes. This is one of the major benefits of programs
  like CanDo.


Operating Instructions:

   DiskLister requires six files to operate - the DiskLister deck, the
  PrefsReq deck, two image files called IconImage1 and IconImage2, and two
  other CanDo decks called SimpleReq and PaletteReq. SimpleReq provides the
  requesters used in the program, and PaletteReq supplies the palette
  requester. All of these files must be in the same directory.

   There are several ways to run DiskLister. The unbound deck can be run
  with DeckBrowser. To do this, change the DiskLister icon default tool to
  "c:DeckBrowser" (or where ever the DeckBrowser program is located).
  Alternatively, you could bind the deck (using TheBinder or TheMultiBinder)
  and run the program as a bound deck using the CanDo library.  When first
  run, DiskLister will create a sub-directory called "Data" in the directory
  that the program is located. You can not run DiskLister from a locked
  floppy disk (because DiskLister can not create this directory). The
  catalogue files you create wi ll be stored in the "Data" directory.

   The basic operation of DiskLister is as follows. A floppy disk is
  inserted into a disk drive. DiskLister scans the disk, making a list of
  all the files and directories on the disk. This list can then be saved.
  Do this for all of the floppy disks you want to catalogue. Once your disks
  are catalogued, a Search function can then be used to search for files that
  are located on a disk somewhere in your collection. For example, you could
  do a search for the program "PicMaker", and DiskLister would then give you
  a list of any disks that have "PicMaker" on them - much easier and quicker
  than searching manually through dozens or hundreds of disks.

   After inserting the disk you wish to catalogue, you need to tell
  DiskLister which drive to scan. Use the 'Drive' cycle drive to cycle
  through the available drives.

   After setting the drive number, click the 'Scan Disk' gadget. A requester
  will appear, telling you that DiskLister is searching through the disk in
  the drive. After the scanning is complete, a list of all the files and
  directories on the disk will a ppear in the 'Disk Contents' field. To save
  this information, click the 'Save' gadget. A requester will appear, asking
  you to name this disk. Either enter a new name or accept the default
  entry, and click the 'OK' gadget. This information will be saved in the
  "Data" directory, and the disk name entered in the 'Disk Name' field.

   To view the contents of a disk you have previously saved, click on the
  name of the disk in the 'Disk Name' field.

   To delete a catalogue file, select it in the 'Disk Name' field and then
  click the 'Delete' gadget. A requester will appear asking you to confirm
  that you want to delete this file.

   The 'Print' gadget allows you to print the currently selected disk.

   The 'List All' gadget lists all of your currently saved catalogue files.

   The 'Auto Scan' gadget is a toggle select gadget - it is either on or off.
  If this option is turned on, then any disk that is inserted into a disk
  drive will be immediately scanned. Note that DiskLister will always scan
  the drive selected in the 'Drive' gadget when any disk is inserted in any
  drive. (This is not intentional, we just couldn't find any way of finding
  how to tell which drive a disk was inserted into). After the disk has been
  scanned, the Save requester will appear, allowing you to immediately save
  the disk information. The Auto Scan feature is useful when you scanning a
  lot of disks, one after the other.

   The 'Iconify' gadget reduces DiskLister to a small window on the Workbench
  screen. If you are using Workbench 2, then this window will be an
  AppWindow. If you drag an icon of a disk onto this window, DiskLister will
  Auto Scan the disk. To 'Uniconify' the window, double-click the icon in
  the window.  The 'Search' field allows you to enter a string to search for
  in your saved catalogue files. Type in the name you want to search for and
  press the 'Return' key. After searching through all your saved catalogue
  files, DiskLister will then give you a list of the disks which have a file
  or directory name containing the name that you entered. To view the
  contents of one of these disks, click on its name in the 'Disk Name' field.
  The contents of the disk will be displayed, with the first occurrence of
  the search name highlighted. To search for the another occurrence in the
  same disk, click on the highlighted name in the 'Disk Contents' field. If
  there are no more occurrences the last line will be highlighted. The
  search that is carried out is not case-sensitive and finds any occurrence
  of the search string. (This could be changed if you prefer it differently,
  or you could add some new gadgets to allow for different search
  attributes).

   The 'Prefs' gadget brings up a requester where you can change various
  aspects of DiskLister. These options are:

   Iconify X Position: - The X position of the Iconified window. Default is
  0.

   Iconify Y Position: - The Y position of the Iconified window. Default is
  200.

   Contents List Indent: - this sets the number of spaces that Disklister
  indents each directory level of the disk contents list. The default is 3.

   Maximum Drive Number: - the highest drive cycle number. Default = 1.

   Default Drive Number: - the starting drive number. Default = 0.

   The 'Set Palette' gadget allows you to alter the colours of the screen.

   The 'Save' gadget saves the current preferences as a file called
  DiskLister.prefs in the same directory as DiskLister. When DiskLister
  starts up, it checks for this file and changes the preferences to match it.

   The 'Use' gadget uses the current preferences, but does not save them.

   The 'Cancel' gadget cancels any changes you have made.



   Programming Notes:

   Routines:

   Here is a list of the routines and a brief outline of their purpose.

  'app message' - handles app messages from the Iconify window
  'ask to delete' - shows a requester asking to confirm deletion of file
  'ask to quit' - shows a requester asking to confirm 'Quit'
  'ask to replace' - shows a requester about overwriting existing file
  'delete' - delete selected catalogue file
  'draw drive name' - draws the drive name in the 'Drive' cycle gadget
  'get disk name' - gets the name of a disk in the selected drive
  'iconify' - iconify the window
  'kill info' - removes a 'status' or 'message' requester
  'list all' - list all the saved catalogue files
  'load images' - load the image for iconified window
  'load images 2' - load the alternate image for the iconified window
  'load palette' - loads the prefs palette
  'load prefs' - loads the preferences file
  'loadreqs' - load the 'SimpleReq' deck to allow for use of requesters
  'message' - display a 'Message' requester with a 'Continue' gadget
  'new size' - routine activated when main window is resized
  'next drive' - sets the number in the 'Drive' gadget to next drive
  'ok' - saves a catalogue file
  'print' - print contents of current disk
  'process messages' - routine to handle messages from the SimpleReq deck
  'refreshwindow' - draws the window graphics and text
  'save' - shows a requester asking for name of the disk before saving
  'save prefs' - save the prefe
  'scan disk' - scans disk for contents
  'search' - searches for a text string in saved catalogue files
  'set defaults' - sets the default preferences
  'set file names' - set default file names
  'set prefs' - displays the preferences requester
  'show disk' - displays the contents of a disk
  'show next search' - search for next occurrence of the search text string
  'start iconify' - sets up iconify window
  'startup' - sets default variable values
  'status' - shows requester with status information
  'uniconify' - reopens the main window after iconify

   Global Variables:

   drive        - is the number of the disk drive to scan
   diskinfoname - the name of the disk being scanned
   autoscan     - TRUE if Auto Scan is on, FALSE if not
   filelist     - document for displaying disk contents
   disklist     - document for displaying disk names
   origdir      - directory where DiskLister is located
   savedir      - directory where catalogue files are saved
   prefs        - variable containing the preferences settings


   Loading DiskLister into CanDo:

   First, copy the DiskLister, DiskListerOptions, IconImage1, IconImage2,
  SimpleReq and PaletteReq files into a working directory. Unless you place
  these files in a directory called CanDo:Decks, you will have trouble
  loading DiskLister into CanDo for the first time. The CanDo file requester
  will appear, asking you to find the SimpleReq file. Locate it and then
  click the OK gadget. DiskLister loads this SimpleReq file when it starts
  up.

*************
* Global routine "set file names"
    If Supervised = TRUE                    ; if DiskLister is being edited
        Let origdir = "cando:decks"         ; set the working directory
    Else
        Let origdir = TheOriginDirectory    ; else use starting directory
    EndIf
    Let savedir = "Data"                    ; set where to save data files
    Let savedir = PathAndFile( origdir , savedir )
    If exists( savedir ) = FALSE            ; create it if necessary
        Dos "makedir" ||| savedir
    EndIf
    Let prefsreqname = PathAndFile( origdir , "PrefsReq" )
    Let prefsname = PathAndFile( origdir , "DiskLister.prefs" )
* End of routine "set file names"
*************

   The 'set file names' routine sets up where DiskLister looks for its
  required files. It sets the global variable 'origdir' to
  'TheOrignDirectory' system variable. This would normally be the directory
  where DiskLister is located, however when editing the deck, CanDo sets the
  'TheOriginDirectory' to directory that CanDo is in. To get around this,
  use the 'Supervised' system variable. When this variable is TRUE, then
  DiskLister is being edited in CanDo. If it is FALSE, then DiskLister is
  being run. Edit the 'set file names' routine and change the "CanDo:Decks"
  name to the full path name of the directory where DiskLister is located.
  When DiskLister is run from the Workbench, 'Supervised' will be FALSE, so
  therefore 'origdir' will be set to the directory DiskLister is in. This
  avoids having to set up an assign to allow DiskLister to find its files.


*************
* Global routine "process messages"
    Local name
    If ARG1 = "Quit"        ; from 'ask to quit' routine
        If ARG2 = TRUE
            Quit
        EndIf
    EndIf
    If ARG1 = "Replace"     ; from 'ask to replace' routine - replace         If ARG2 = TRUE      ; existing catalogue file
            Do "ok",replacediskname,FALSE
        EndIf
    EndIf
    If ARG1 = "SaveName"    ; enter disk name to save
        If ARG2 = TRUE
            If ARG3 = ""    ; ARG3 contains name entered in requester
                Do "message","No disk name entered!","File not saved"
                StopScript
            EndIf
            If exists( PathAndFile( savedir , ARG3 ) ) = TRUE
                Let replacediskname = ARG3
                Do "ask to replace",ARG3
            Else
                Do "ok",ARG3,TRUE
            EndIf
        EndIf
    EndIf
    If ARG1 = "Delete"          ; delete catalogue file
        If ARG2 = TRUE
            Do "delete"
        EndIf
    EndIf
    If ARG1 = "Prefs"         ; from prefs requester
        If ARG2 = TRUE
            Let prefs = ARG3"
        EndIf
        Do "load palette"
    EndIf
* End of routine "process messages"
*************

   The 'process messages' routine handles messages from the requesters. The
  'MessageFromSubDeck' activation of the two cards in the deck should contain
  the following script -

   Do "process messages",ARG1,ARG2,ARG3,ARG4,ARG5,ARG6,ARG7,ARG8

   As an example of how the requesters work, I will use the 'Quit' requester.
  The 'ask to quit' script (activated when the 'Quit' gadget is clicked)
  contains this script -

    Do "loadreqs"
    OpenRequester "simplereq","YesNo","Quit","","Do you really want to quit?"

The 'loadreqs' routine loads the 'SimpleReq' sub-deck.
The 'OpenRequester' line opens the sub-deck -
    "simplereq" is the name of the sub-deck.
    "YesNo" is the name of the card in the SimpleReq deck to display.
    "Quit" is the name that the sub-deck will return so we know which routine caused the requester to appear. Each routine that uses a requester will use a unique name to identify it. The name is passed to the sub-deck and then back to the main deck.
    The remainder of the line is the text that will appear on the requester.

   After executing the 'ask to quit' routine, a requester will appear asking
  if the user really wants to quit. If the user clicks the 'Yes' gadget then
  the sub-deck will return the following message to the main deck -

    "Quit",TRUE

   If the user clicked the 'No' gadget, the sub-deck will return -

    "Quit",FALSE

   In both cases, the first argument passed will be "Quit" - the name that
  was passed to it in the first place.  The 'process messages' routine
  contains (in part) the following script -

   If ARG1 = "Quit"
        If ARG2 = TRUE
            Quit
        EndIf
    EndIf

   This checks to see which routine sent the original message - in this case
  the 'ask to quit' routine. This is identified by the first argument (ARG1)
  being "Quit". The second argument is either TRUE or FALSE depending on
  which gadget the user clicked. A simple "If ARG2 = TRUE" test then either
  quits or returns to the program.



   There are a lot of routines in DiskLister. If you want to study them,
  either load DiskLister into CanDo, or print them out using ThePrinter
  program that comes with CanDo. We learnt a lot about CanDo from doing this
  project - and hope it is of some use to you also. We would welcome any
  comments, questions or improvements.

   Gary Smith and Charles Hawes.



   <> 34 <%> 34 <%> 34 <%> 34 <%> 34 <%> 34 <%> 34 <%> 34 <%> 34 <%> 34 <>