=============================================================================
Locate - Flexible file search for RISC OS                        Version 2.12

(C) Stephen Fryatt, 2001-2016                                    28 July 2020
=============================================================================

  This file, and a StrongHelp version, are contained within the Locate
  application.  These can be accessed from the 'Help' entry in the Filer
  menu and from the 'Help' entry in Locate's iconbar menu.

Licence
-------

  Locate is licensed under the EUPL, Version 1.1 only (the "Licence"); you
  may not use this work except in compliance with the Licence.

  You may obtain a copy of the Licence at
  http://joinup.ec.europa.eu/software/page/eupl

  Unless required by applicable law or agreed to in writing, software
  distributed under the Licence is distributed on an "AS IS" basis, WITHOUT
  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

  See the Licence for the specific language governing permissions and
  limitations under the Licence.

  The source for Locate can be found alongside this binary download, at
  http://www.stevefryatt.org.uk/software

  The necessary libraries and build tools can be found at
  http://www.stevefryatt.org.uk/software/build



Introduction
------------

  Locate is a file find utility for RISC OS.  It will search a specified
  directory for files that match a set of conditions.  These conditions
  include the filename (including wildcards), file size, modification date,
  filetype, attributes and contents.

  Locate is loosely based on similar utilities available on other platforms:
  particularly the File Find tool that was once found on the '9x versions of
  Windows.

  Note that with the arrival of Locate 2, there are now two distinct versions
  of Locate in circulation.  While they share the same name and outward
  appearance, internally they are very different pieces of software.
  Locate 2 will load search settings saved from the original, but will
  currently not load old results (although it can load settings from those
  files so that searches can be repeated) -- this limitation might be removed
  in a future update.  It will never be possible to load files saved from
  Locate 2 into the original version.

  Unless it explicitly stated otherwise, references in this manual to
  "Locate" refer to Locate 2 -- this is now the only supported version of the
  software.



Installing Locate
-----------------

  Locate requires RISC OS 4 or later; it might work with earlier versions,
  but requires the Nested Wimp and its use is unsupported.  It can be run off
  a hard disc or floppy disc.

  It is 26/32-bit neutral, and should therefore run on all hardware systems
  as long as the 32-bit Shared C Library is installed.  If required, this can
  be found in the System Resources on RISC OS Open Ltd's website at
  https://www.riscosopen.org/content/downloads/common.

  To install Locate on a hard disc, copy the !Locate application to a
  suitable directory.  If you have installed Locate using a package
  management system, then please refer to the instructions which came with
  that.

  Under RISC OS Select, Locate will act as a Filer plugin for Find by
  default.  See the Filer Action Plugin section for details of how to disable
  this feature.



Simple Searches
---------------

  To use Locate, start it in the usual way by double-clicking on its icon in
  a directory window (or via your preferred application launcher).  When the
  Locate icon appears on the iconbar, click Select on it to open the search
  dialogue.

  By default, Locate will validate the default search paths configured in the
  'Search directories' field of the choices dialogue when it loads.  If any
  are invalid on the current machine (for example if the system only has
  USB-connected drives and therefore no ADFS, then the default path of
  ADFS::4.$ will not exist), then it will warn of the problem and offer the
  option to edit the settings.  Accepting this will open the choices
  dialogue; otherwise the problem can be ignored and the paths left as they
  are -- but they will need to be corrected in the search dialogue before a
  search can be carried out.  This validation can be disabled from the
  choices dialogue if not required.


  RISC OS Select Filer plugin
  ---------------------------

  If you have RISC OS Select, then Locate can also perform searches when the
  'Find' option in the Filer menu is used.  By default this will bypass the
  search window, simply searching for objects with the given name in the
  selected directories.  Unlike the Filer's normal find option, the Locate
  plugin uses wildcards in the filename as described below.

  To add more parameters to the search in this situation, stop the search
  from the results window menu and use the 'Modify search...' option.  It is
  possible to have the 'Find' option open a search window instead of starting
  a search directly: to change the behaviour of the plugin, see the choices
  window.  Instructions for disabling the plugin are also available in the
  Filer Action Plugin section, to allow the standard Filer Action search to
  be used instead.

  | (i) As standard, clicking Select on Locate's iconbar icon will open the
  |     search dialogue with the default settings.  By using the default
  |     option in the hotlist, however, it is possible to customise this
  |     'standard' search to individual requirements.


  Setting the search directory
  ----------------------------

  Before searching, you must make sure that the 'Search in' field contains
  the path-names of the directories that you wish to search, separated by
  commas.  All the files contained in these directories and their
  subdirectories will be checked recursively.  You can open all the
  directories shown to check their locations by double-clicking on the
  directory icon on the right of the field.

  To change the location, you can simply type the required paths into the
  field.  However, it is easier to use drag-and-drop to change the location.
  Dragging files, applications or directories into the field will add the
  paths of the objects to the list (files add the path of the parent
  directory).  Dragging with Shift held down will REPLACE the paths that are
  already shown with the new path.  Dragging the directory icon to the right
  of the field to a filer window will replace the field contents with the
  path of the directory.

  If an object is dragged to Locate's iconbar icon, the search window is
  opened ready to search that path.

  | (i) On most versions of RISC OS, you can drag the directory onto a Filer
  |     icon on the iconbar to set the search path to the default directory
  |     (usually the root on that drive).

  The default path used for the search is set in the choices window.


  Entering the object (file) name
  -------------------------------

  Enter the name of the object that you are looking for into the 'Object
  name' field.  The criteria should be left as 'is equal to' -- see Advanced
  Use for more details.

  Names are matched exactly: "Report" would match "report" but not
  "Reporter".  For more flexibility, wildcards are allowed. "#" will match
  any single character, so "Reporte#" would match "Reporter" and "Reported"
  but not "Reporters". "*" will match any zero or more characters, so
  "Report*" would match "Report", "Reported" etc.  Wildcards can appear
  anywhere in the name.  To search for a substring (in the same way that the
  Filer's search option does), put an asterisk at each end of the name (for
  example "*SubStr*").

  By default the case of the name is ignored; un-tick the 'Ignore case'
  switch to cause the case to matter.

  | (!) On RISC OS, all Filecore-based filing systems are case-insensitive: a
  |     file might be called "File", "FILE" or "file", but they would all be
  |     seen as the same by the filing system and only one can exist in any
  |     location at a time.  Other systems -- such as NFS shares over Sunfish
  |     -- take account of case in filenames: "File", "FILE" or "file" could
  |     all exist together in the same directory.


  Starting the search
  -------------------

  Assuming that you don't care about any other properties (which will be
  covered later in the Advanced Use section), click on 'Search' to locate all
  the files with matching names.  After a short pause, the results window
  will open and any matching objects will start to appear within it.  If any
  errors are returned by the filing system being searched (such as "broken
  directory"), Locate will remember them and continue the search in the
  parent directory to where the error occurred.  This means that any objects
  in the directory where the error occurred (including directories) that had
  not been checked will be missed; unfortunately it is not possible to just
  skip the object that caused the error, due to the way that RISC OS works.
  Any errors encountered will be shown in the results window.

  Clicking Select on 'Cancel' will close the search dialogue without
  performing the search; clicking with Adjust will reset all the fields to
  their original values.


  The search window menu
  ----------------------

  Clicking Menu will open a menu containing two options. 'Save search' allows
  the settings in the search window to be saved for future use.  The settings
  are saved exactly as they are at that point, including remembering which
  options tab is visible (this is useful for setting up quick searches where
  only one specific parameter will change).  In a similar way, 'Add to
  hotlist...' will add the settings to the hotlist for future use.



Viewing the results
-------------------

  The results window contains a list of the matching objects from a given
  search.  A full pathname is shown for each object, but they may be
  truncated from the start if they are too long to fit in the width: this in
  indicated by the name starting with '...'.  If this is the case, expanding
  the window will allow more of the names to be shown.

  Clicking Select or Adjust will select items in the usual 'Filer' way.  If a
  search is continuing in the background, objects will be added to the window
  as they are found; the info field at the bottom of the window will show the
  directory currently being searched.  At the end of the search the number of
  matching objects and the number of errors that occurred will be shown
  instead.

  Any errors that occurred during the search will be shown in the results
  window: they appear amongst the files, with a red 'hazard triangle' and
  their text in red.  The error returned is shown, along with the path of the
  directory being searched when the problem occurred.

  | (i) The directory reported for errors is the directory being searched at
  |     the time when the error occurred.  Although in some cases -- such as
  |     ArcFS errors -- it can actually be the object causing the error, this
  |     isn't always the case as the fault could lie in one of the objects
  |     within the reported directory.

  Double-clicking Select on an object will Filer_Run it: files will be
  loaded, applications run and directories opened.  Holding down Shift will
  have the expected effects: all files will be loaded into a text editor and
  application directories will be opened.  Double-clicking Adjust will open
  the parent directory of the object (to 'view' it); this can also be done
  for the selected item from the menu.  Finally, objects and selections can
  be dragged out of the window to load them into applications; currently this
  will not work for Filer windows.

  Selections can be made by clicking on items with Select or Adjust in the
  usual way; multiple objects can be altered at once by dragging a box around
  them with Select or Adjust.  The box can be started over an area of the
  window that does not contain a selectable item, or by holding down Ctrl
  while starting the drag.

  If an entry in the window is greyed out, the object referred to has been
  moved since the results were generated.  This is most likely to occur if a
  set of results is saved and re-loaded, as all the file info details are
  re-scanned at this point; otherwise it will only occur if an attempt is
  made to double-click on an object that has moved.


  The results window menu
  -----------------------

  Clicking Menu over the results window opens a menu giving various options
  relating to the results.  These are:

  The 'Display' submenu, which leads to the options 'Path only' and 'Full
  info'.  These toggle the display between only showing the path names of the
  objects and showing full details of size, type, attributes and the
  last-modified date.

  'Save' leads to several save options. 'Results' leads to a save window
  allowing the results (and the search parameters that created them) to be
  saved out in a file that can be loaded back into Locate. 'Path names' will
  allow a list of all the path names (or the current selection) to be saved
  out as a text file.  Direct transfer to other applications is possible and
  the complete names (not the truncated ones shown) will be saved.  Finally,
  'Search' leads to a save window allowing the search parameters from the
  search to be saved out in a file that can be loaded back into Locate.
  Re-loading this file will open the search window exactly as it was when the
  search was carried out.

  | (i) Saved results files can be dragged to the hotlist in just the same
  |     way as saved parameter files: the settings used to generate the
  |     results will be added to the hotlist.

  'Select all' will select all the items in the window.

  'Clear selection' will de-select any selected items.

  'Object info' leads to a window giving full details of the selected item.

  'Open parent' opens the directory containing the object, in the same way as
  Adjust-double-clicking on it.

  'Copy names' will copy the names of the files (or those that are currently
  selected) on to the global clipboard, ready to be pasted into another
  application.

  'Modify search...' opens a search window containing the parameters used
  before (clicking Select on the iconbar icon always opens a blank search
  window, although Adjust will recall the last search parameters used).  Note
  that you can only ever have one search window open at a time (but as many
  results windows as you have the free memory for -- up to the application
  space limit of 28Kb or course...).

  'Add to hotlist...' will add the parameters used for the search to the
  hotlist, opening a dialogue so that a name can be supplied for the new
  entry.

  'Stop search' will halt a search that is continuing in the background,
  keeping the window open with the results that have been found so far.  You
  cannot re-start a stopped search.



Advanced Use
------------

  It is possible to make Locate check more than just the name of the objects
  being searched.  Options are also available for size, modification date (or
  age), object file type, attributes and contents; with the exception of the
  object name, they are split between several tabs -- or sub-windows -- in
  the search dialogue to make things easier.  To view and enter the options
  for a given attribute, click Select on the relevant tab on the left of the
  search dialogue.  The options available are:

  * Object name
  * File size
  * Creation or modification date
  * Object or file type
  * Object attributes
  * File contents

  | (i) All the criteria (object name, size, date or age, type, attributes
  |     and contents) are always active; it's not just the one that is
  |     visible when you click on 'Search'.  This allows you to (say) search
  |     for "all text files between 1Kb and 10Kb in size, created before 27th
  |     January 1996, which are locked"; it can also be confusing if you
  |     forget that you set an option in a hidden tab.


  Search options
  --------------

  In addition to the matching critera, there are also various options that
  can be set to control how the search is carried out (and not what files are
  matched); these can be seen by clicking on 'Show search options'.  The
  default settings can be changed from the choices window.

  By default, Locate will only record details of the files that match a
  search.  By selecting 'Store all file details', it will record details of
  all the files that it scans in the search folder.  At present this is not
  particularly useful, but paves the way for future additions to Locate's
  abilities.

  If an image filing system is causing errors to be generated when Locate
  tries to read the files within one of its image directories, select 'Ignore
  Image FS's contents'.  This will cause Locate to check the name and
  attributes of the image file itself (for example a Spark archive) but not
  of the objects within it.  This is useful, for example, in the situation
  where you have ArcFS loaded and attempt to search a path containing Zip
  files; without this option on, ArcFS will halt the search with errors each
  time a Zip archive is encountered.

  The 'Suppress FS errors' is currently unused, as at present Locate 2 logs
  all errors in the results window.

  Finally, the 'Full info display' option determines whether or not the
  results window starts off in path only or full info mode.


  Recalling old searches
  ----------------------

  Locate remembers the parameters used for the last search so that they can
  be re-used easily.  In addition, it is possible to save the parameters,
  either on their own or along with the results of a search, and re-load them
  later.  This is done from the results window menu.

  The 'Modify search...' option in the results window menu allows the a
  search dialogue containing the parameters that produced the results shown
  to be opened.  This also works with re-loaded results.

  In addition, clicking Adjust on the iconbar icon will open a search
  containing the parameters from the previous search.

  More information on all of these options can be found in the section on
  Saving Searches.



Matching on object name
-----------------------

  It is possible to match objects based on their names.  This was briefly
  discussed in the section on Simple Searches, although some detail was left
  out.

  By default, names are matched exactly to whatever is entered into the field
  to the right of 'Object name' in the search window.  Unlike other sections
  of the search options, where the default critera is 'is not important', the
  default critera for the object name is 'is equal to' so as to give some
  compatibility with the behaviour of Locate 1.

  The requirement for an exact match means that "Report" would match "report"
  but not "Reporter".  For more flexibility, wildcards are allowed. "#" will
  match any single character, so "Reporte#" would match "Reporter" and
  "Reported" but not "Reporters". "*" will match any zero or more characters,
  so "Report*" would match "Report", "Reported" etc.  Wildcards can appear
  anywhere in the name.  To search for a substring (in the same way that the
  Filer's search option does), put an asterisk at each end of the name (for
  example "*SubStr*").

  By selecting a criteria of 'is not equal to', objects can be made to match
  if their names do NOT match based on the rules given above.  For
  compatibility with Locate 1, leaving the 'Object name' field blank or
  entering a single "*" will mean that the name is not tested; this can also
  be achieved by setting the critera to 'is not important'.

  By default the case of the name is ignored; un-tick the 'Ignore case'
  switch to cause the case to matter (but remember that all RISC OS Filecore
  filing systems are case insensitive anyway).



Matching on File Size
---------------------

  To check for certain sizes of file, select the 'Size' option in the left
  margin of the search dialogue.  Choose a search criteria from the drop down
  list (the default is 'not important' meaning that the size is ignored).
  Having selected a criteria, it is possible to enter the required size(s)
  into the fields below; select the units required for each field.  The
  larger units match a spread either side of the specified size, so 1Kb would
  match from 1Kb - 512bytes to 1Kb + 512bytes.

  Directories and applications will always match the size test, as their
  sizes are not very meaningful.



Matching on Creation or Modification Date
-----------------------------------------

  To check for certain modification dates, select 'Date' in the left margin
  of the search dialogue.  It is possible to specify this option in terms of
  an absolute date or as an 'age' relative to now: pick one using the options
  at the top left.  Only the selected item contributes to the search
  criteria: you cannot specify both date and age at the same time.

  | (!) All dates and ages refer to the last time that an object was
  |     MODIFIED, and not when it was first created: RISC OS does not
  |     maintain separate creation and modification dates.

  Again choose a search criteria.  If using the absolute date option, enter
  the dates and times as appropriate.  Dates are specified in the form
  'DD/MM/YYYY' and are rounded up or down if being used as upper or lower
  limits.  To specify a specific time, increase this notation to
  'DD/MM/YYYY.HH:MM'.

  Clicking on the 'Set...' button on the right of the date fields will open a
  dialogue box which allows the date to be set more easily (without
  remembering the order of the components demanded by Locate).  Enter the
  details in the box as required and click on 'Set'.

  If specifying the dates in terms of age, pick a unit from the drop down
  menu by the field and enter the required value. 'Exactly' and 'Any age but'
  match a window of the unit centred on the specified point in history:
  "exactly four months" would match a period of 15 days either side of the
  time four months ago when the search was started.

  | (i) Remember that dates and ages work in opposite directions: as dates
  |     get 'bigger' the objects get more recent; as ages get 'bigger' the
  |     objects get older.  Also note that, unlike in Locate 1, month and
  |     year now correctly take the calendar into account.

  The datestamps of directories and applications are tested, but the results
  may not always be as expected.  For applications the Filer shows the
  datestamp to be that of the !RunImage file inside (if one is present).
  Locate will check the datestamp of the application directory itself, as
  shown by using "*Info" at the command line.  Untyped files do not have
  datestamps, so these will ALWAYS match whatever date constraints are set.

  The default criteria for date is 'not important', meaning that the
  datestamp will be ignored.



Matching on Object or File Type
-------------------------------

  To check for certain object types, select 'Type' in the left margin of the
  search dialogue.  By default all objects (files, directories and
  applications) will be matched; deselect those that you don't care about
  from the list.

  If you are matching files, you can also specify the types that you want to
  match or ignore.  Choose a matching criteria from the drop down list (the
  default is to match all types) and enter the types into the field below;
  these can either be hexadecimal numbers such as "ff9" or the textual
  equivalents such as "Sprite" (if one has been defined) or a mixture of the
  two.  To enter more than one type, separate them by commas; eg: "Sprite,
  JPEG, GIF, TIFF" would match Sprites, JPEGs, GIFs and TIFFs (it could just
  as well be entered as "Sprite, JPEG, 695, ff0" or even "ff9, c85, 695,
  ff0").  Clicking on the pop-up menu to the right of the types field will
  give a list of filetypes for which names are currently known; other types
  can be entered into the field using their three-digit hexadecimal number.

  | (i) Unlike its predecessor, Locate 2 converts all filetypes in the list
  |     to numeric form before saving them: this means that saved settings
  |     will still work, even if they are loaded on a machine where some of
  |     the types have not been seen.

  To match untyped files (those with real Load and Exec addresses), enter the
  special type "Untyped".

  Although image directories will be viewed as directories when actually
  looking for files to check (assuming their ImageFS is currently loaded and
  'Ignore ImageFS's contents' has not been ticked), their actual filetype is
  matched for the purposes of this test and they are treated as files.



Matching on Object attributes
-----------------------------

  To check the file attributes, select 'Attributes' in the left margin of the
  search dialogue.  To check a given attribute, select its entry and set the
  icons on the right as required.

  All object types will be compared, even though it is not possible to give
  applications and directories private read and write access (at least under
  ADFS).  For this reason, Locate will only ever match files if these options
  are set to match "Yes".



Matching on File contents
-------------------------

  To check the contents of files, select 'Contents' in the left margin of the
  search dialogue.  Pick the search criteria from the drop-down menu: the
  default is not to check the file contents.  In the field below, enter the
  text to search for; this text is looked for within the file and can contain
  the usual wildcards ("#" to match any single character and "*" to match any
  zero or more characters, both including control characters).  The text is
  matched case sensitively unless 'Ignore case' is ticked.

  If 'Allow control chars' is selected, certain control characters can be
  entered using "\" sequences.  These are as follows:

  * "\a" -- Bell (ASCII 7)
  * "\b" -- Backspace (ASCII 8)
  * "\f" -- Formfeed (ASCII 12)
  * "\n" -- Newline (ASCII 10)
  * "\r" -- Carriage Return (ASCII 13)
  * "\t" -- Tab (ASCII 9)
  * "\v" -- Vertical Tab (ASCII 11)
  * "\\" -- Backslash (ASCII 92)

  The codes are always case-insensitive (so "\t" and "\T" are the same
  whatever the setting of the 'Ignore case' switch); if any other character
  follows the "\", both will be ignored.  If 'Allow control chars' is off, no
  conversion takes place and "\t" would match the text "\t" in the file.

  | (i) Since searching file contents takes time, this check will only occur
  |     if all the other criteria set have been checked and found to match.
  |     For this reason, it is a good idea to try and narrow down the search
  |     as much as possible (for example by specifying a list of filetypes to
  |     try, or a filename if known).



Saving Searches
---------------

  Sooner or later, some searches used in Locate will prove to be useful
  enough that it would be helpful to be able to repeat them.  To assist with
  this, various options are available including the hotlist and saved
  settings files.

  The settings from previous searches can always be recalled into the search
  dialogue.  If the results window is still on screen (either from the
  original search, or from reloading a set of results into Locate), then
  selecting 'Modify search...' from the window's menu will open the search
  dialogue with the same settings ready to be modified or re-used intact.  In
  addition, clicking Adjust on Locate's iconbar icon will recall the settings
  used for the last search to have been carried out.


  Saving search settings
  ----------------------

  In addition to saving the settings of a search with its results, they can
  be saved into a file on their own which can then be used to start a new
  search.  This can be done from a results window by selecting 'Save --
  Search options --' from the menu; the settings from a search dialogue can
  also be saved directly via the 'Save search --' entry in its menu.

  Double-clicking on a saved settings file, or dropping one on to Locate's
  iconbar icon, will open a search dialogue with the correct values set up.
  They can also be added to the hotlist, as described below.


  The hotlist
  -----------

  In addition to saved searches, Locate contains a hotlist, which can be
  accessed via the 'Hotlist...' entry in the iconbar menu.  This opens up the
  hotlist window, revealing a filer-like repository for storing searches: the
  main differences are that items in the hotlist can be arranged in any
  order, can have more descriptive names, and can be accessed from Locate's
  iconbar menu (either via the hotlist window, or via the corresponding entry
  in the 'Hotlist... --' submenu on the iconbar.  A search stored in the
  hotlist can also be marked as 'default' -- at which point it will be called
  up whenever Select is clicked on Locate's iconbar icon.

  Search settings can be added to the hotlist by selecting 'Add to
  hotlist...' from the results window menu.  This will open the Add search to
  hotlist window, into which a name can be entered; clicking on 'Add' will
  then add the search settings to the hotlist.  Settings can also be added
  via the 'Add to hotlist...' entry in the search dialogue's menu.  Items in
  the list can be re-ordered by dragging them around with the mouse.

  Searches in the hotlist window can be accessed by double-clicking on their
  icons, or by selecting them and clicking on the 'run' button in the
  toolbar.  They can be renamed by selecting them and choosing 'Entry --
  Rename...' from the menu, or by clicking on the 'rename' button in the
  toolbar.  Selected entries can be deleted with 'Entry -- Delete' from the
  menu, or the 'delete' button in the toolbar.  The selection itself can be
  manipulated using the 'Select all' and 'Clear selection' entries in the
  menu, or by clicking Select or Adjust respectively on the 'selection'
  button in the toolbar.

  A single search stored in the hotlist can be made the 'default' -- so that
  it is used whenever Select is clicked on Locate's iconbar icon -- by
  selecting it and then choosing 'Entry -- Default' from the menu, or by
  clicking on the 'default' button in the toolbar.  The current deafult entry
  is shown by a red star, which is overlaid on its file icon in the hotlist
  window.  There can only ever be one default, so selecting an entry will
  also clear any that is already set; similary, selecting the default and
  choosing 'Entry -- Default' or clicking on the 'default' button in the
  toolbar will remove the red star and ensure that its settings are not used
  for future searches started from the iconbar.

  The contents of the hotlist is saved automatically when Locate exits.  Its
  contents can also be saved into a separate hotlist file using the 'Save
  hotlist' menu item, or by clicking Select on the 'save' button in the
  toolbar; if there is a selection, then it is possible to include just these
  entries in the saved file.  Saved hotlist files can be dropped into a
  hotlist window to add the searches that they contain to the list.

  Finally, individual saved searches can be added to the hotlist window by
  dragging their files to the window (either saved settings or full results
  files).  They can also be saved out by dragging them, by using 'Entry --
  Save search --' or by clicking Adjust on the 'save' button in the toolbar.



Configuration
-------------

  Selecting 'Choices...' from its iconbar menu allows the default behaviour
  of Locate to be changed.

  The 'Default search options' section controls how the search options are
  set for new searches (these are remembered along with the other parameters
  for recalled searches).  The 'Search directories' field contains the
  default directories to be searched: either type a path in or drag an object
  into the field.  As with the corresponding field in the search dialogue,
  multiple paths can be entered separated by commas; dragging objects to the
  field will add to these unless Shift is held down -- in which case the new
  path will replace those already present. 'Store all file details', 'Ignore
  Image FSs' contents', 'Suppress FS errors' and 'Full info display' are the
  same as those in the search dialogue.

  The 'Plugin behaviour' section is only available to users of RISC OS
  Select, where Locate can act as a plugin for the 'Find' option in the
  Filer. 'Quit after use (no icon)' determines how Locate behaves if it is
  started by the Filer to deal with a search.  If selected, no icon is placed
  on the icon bar and Locate will quit as soon as all its windows have been
  closed.  If not, Locate will behave as though it was loaded by the user.
  If 'Open search window' is selected, the search window will open after
  'Find' is selected in the Filer, with the relevant fields filled in.  If it
  is not selected, the results window will open immediately; the search can
  be stopped and the parameters altered using the menu in the normal way.
  Fully disabling the plugin operation must be done from within the !Boot and
  !Run files of Locate: see the Filer Action Plugin section for details.

  When 'Scroll to new matches' is on, the results window scrolls down as new
  matches are found so that the last entry is always visible.  When off, the
  window does not scroll and new matches may be added out of sight.

  If 'Check paths on loading' is set, Locate will validate each of the paths
  in the 'Search directories' field of the choices dialogue (described above)
  whenever it loads; if any are invalid, it will warn of this and offer the
  chance to edit them.  If you do not wish this check to take place, turn the
  option off (and save the new settings so that they persist when Locate is
  quit).

  Click on 'Apply' to use the changes or 'Save' to save them and then use
  them (in both cases Adjust will keep the window open).  Click on 'Cancel'
  with Select to close the window and forget the changes; click with Adjust
  to reset the window contents to the state they were in when the window was
  last opened.


  Other configuration options
  ---------------------------

  There are a few configuration options that are not included in the choices
  dialogue.  These are features that most users will not need to alter, but
  they can help in some specific cases.

  The extra options are set by adding tokens to Locate's Choices file.  This
  will be stored as Choices:Locate.Choices on machines with the new boot
  structure (ie. anything running RISC OS 3.5 or later); if not, it will be
  found at !Locate.Choices.  If the file is in neither of these locations,
  open the choices window and click on 'Save' to cause a blank file to be
  written out.

  There are two options that can be set.  The first is "PathBufSize", which
  is the size in bytes of the 'Search in' field in the search window.  By
  default this is 4095 bytes long (4K); if you find yourself getting the
  message "There was not enough space in the search path buffer to add the
  new path" from Locate, you should increase this value.

  The second option is "OSGBPBReadSize".  This determines the maximum number
  of objects that Locate will read each time it gets catalogue information
  from the disc it is searching.  The default of reading up to 1000 items in
  one go makes the searches significantly faster.  If necessary, this can be
  reduced to resolve problems with some filing systems; for example, setting
  the number of objects read to 1, so that Locate will get each set of
  details separately.  This will slow the search down.

  To set these options, load the Choices file into a text editor and add the
  options you require.  Each option should go on a new line.  An example
  file, containing a few options from the choices window might look like
  this:

    # >ADFS::Gromit.$.!BOOT.Choices.Locate.Choices
    #
    # Config file for Locate
    # Last automatically generated on Fri,02 Aug 2002

    SearchPath: ADFS::Wallace.$.Programming
    PathBufSize: 8190
    OSGBPBReadSize: 1

  This will set the 'Search in' field to 8K long (8190 bytes) and read one
  object at a time. "SearchPath" is set from the choices window and can be
  ignored.  The lines starting with "#" are comments and are ignored by
  Locate; blank lines are also ignored.

  Once the file has been changed and saved, quit and re-start Locate for the
  new options to take effect.  The extra entries in the file will be
  preserved if the choices are saved in the normal way from the choices
  dialogue.

  If you manage to corrupt the Choices file, it can be deleted and Locate
  will create a new copy when the choices are next saved.  You will, however,
  lose any non-default settings you had made.



Filer Action Plugin
-------------------

  Locate acts as a Filer Action Plugin under RISC OS Select, so that the
  'Find' option in the Filer menu causes Locate to be used instead of the
  standard search.

  For this to work, click the mouse or press Return over the text field of
  the 'Find' option.  Any text that is entered will be put into the 'Object
  name' field of the search window, and selected applications and directories
  are put into the 'Search in' field.  Any files selected at the time will be
  ignored, as Locate can not search for files IN files; if the current
  selection consists entirely of files, the parent directory is used instead.

  This feature can be disabled if required.  Shift-double-click on !Locate
  and load the !Boot and !Run files into a text editor (Shift-double-click on
  them).  Find the line in each file that reads:

    Set Alias$@FilerAction_Find Run <Obey$Dir>.!Run -plugin

  Comment it out by inserting a vertical bar in front of it, like this:

    |Set Alias$@FilerAction_Find Run <Obey$Dir>.!Run -plugin

  Re-save the two files and after the machine has been re-started Locate will
  no longer behave as a plugin.

  To restore the plugin action, repeat the process but remove the vertical
  bar.

  Other details of the plugin operation can be set from the choices window.



Version History
---------------

  This is a complete list of all the changes made to the publicly released
  versions of Locate.  Note that some of the changes are very small and won't
  seem that important in general use.


  0.10 (20 March 2001)
  --------------------

  * Initial release version.


  0.11 (23 March 2001)
  --------------------

  * Corrected default shading of icons in search window.
  * Implemented correct Tab caret movement in the search window.
  * Fixed Wimp_TextOp code so that it works under RISC OS 3.1.


  0.20 (27 March 2001)
  --------------------

  * Improved error handling within search loop, so that claimed memory is
    returned.
  * Transferred results window formatting to ARM code for speed.
  * Results windows are re-formatted when the Desktop Font is changed, to
    ensure that as much text as possible is visible.
  * The option of case sensitivity added to filename matching.
  * Interactive help support is fully implemented.
  * The filetype menu in the search window is implemented in a basic way.
  * Keypresses are passed on to the Wimp correctly from the search window.
  * Adjust-'Cancel' now resets the search window without closing it.
  * Fixed possible -- but very unlikely -- problem with MessageTrans file
    handling.
  * Choices window implemented in a limited way (only allowing the search
    path to be changed).
  * Fixed problem with broken pointers when clicking over empty section of
    results window.
  * Results can be saved out as text files.


  0.21 (12 April 2001)
  --------------------

  * Fixed bug in search code that caused aborts and random crashes if the
    code returned to BASIC with the overflow flag set.


  0.30 (19 April 2001)
  --------------------

  * Searches can now multi-task if required.
  * Clicking Select on the iconbar will bring the search window to the front
    if it's already open.
  * The item under the pointer is transiently selected when the results
    window menu is called up and menu options now act on the selected item if
    appropriate.
  * Implemented 'Open parent' menu option.
  * Escape will exit from singletasking searches.
  * Further improvements to error trapping during searches.  It is now
    possible to continue a search if a filer error occurs, by dropping out of
    the current directory.
  * Error boxes brought in line with RISC OS 3.5 standards for those using
    the new(!) OS.
  * Caret movement within search window completed.
  * Dragging objects to the iconbar will open a search window to search that
    path.
  * It is possible to ignore the contents of Image FS's directories (ie.
    treat them as files).
  * The modification dates of files can be specified in terms of age.
  * Searches on dates now work as expected for 'not in' ranges.


  0.40 (19 June 2001)
  -------------------

  * Locate no longer crashes if the directory icon in the search window is
    dragged to a window that supports RAM transfers.
  * Corrected some apostrophes in the window templates.
  * File-system errors can be logged into the results window without raising
    an error during the search.
  * Search window tidied up, with 'advanced' search options hidden unless
    required.
  * Results can be saved in a format that can be loaded back into Locate,
    keeping all the search options available.
  * Icons redesigned and made more consistent.
  * A search history list allows the previous search parameters to be called
    up quickly for re-use.
  * Clicking Adjust on the iconbar opens the search window with the
    parameters from the last search.
  * Pressing Return in choices window now has an effect.
  * Multiple filetypes can be searched for, along with the option to look for
    'files not of type'.
  * Searching no longer tries to match applications and directories on the
    basis of their size, date or filetype: they now match by default.
  * Matching ImageFS's files as files is now possible: they are treated as
    directories for the files within (if the parent ImageFS is running) and
    as files for the matching.
  * File attributes (read and write access, locking) can now be matched.
  * Drag the iconbar icon to a directory to open a search window for that
    location.
  * Proper use of the !Boot.Choices is now made on systems which support this
    feature.
  * Documentation overhauled and converted to StrongHelp.


  0.50 (22 July 2001)
  -------------------

  * If no files are found, this now gets reported in the results window.
  * An information field is displayed at the bottom of the results window,
    showing the progress of a multitasking search.
  * The results window creation and formatting code has been rationalised.
  * Changes made to wildcard filename comparison code to speed it up.
  * File contents can now be searched with wildcards.
  * Searches can be saved from the search window, without the results.
  * Separate sprites for RISC OS 3 and RISC OS 4 now provided.
  * Selections can now be changed by drag-box in the results window (supports
    Wimp_AutoScroll on RISC OS 4).
  * No longer uses Wimp sprite pool for results window icons.
  * Fixed problem with panes not being located correctly on mode changes and
    re-sizes.
  * Fixed update of history field in choices window when reset.


  0.60 (30 September 2001)
  ------------------------

  * Files that are no longer present are handled more gracefully when run
    from the results window.
  * Save search option added to results window menu.
  * Filetype menu improved (faster generation, alphabetical sorting, icon
    sprites), using code provided by Harriet Bazley.
  * Bug with direct saving from search dialogue box fixed.
  * Fixed problem when a search settings file was loaded while the search
    window was open.
  * Interactive help in save window made context sensitive to the data being
    saved.
  * Objects and selections can be dragged out of results windows and on to
    other parts of the Desktop in the usual way.
  * The configured preference for DragASprite is read from CMOS on startup
    and honoured.
  * Datestamps of directories and applications are now checked when a date
    criteria has been set.
  * Fixed bug causing loose panes to be produced by an icon bar click if the
    search window was open.


  0.62 (2 October 2001)
  ---------------------

  * Fixed bug introduced in 0.60, which stopped dragging the directory to set
    the search path from working.
  * Support for the global clipboard added to results window.


  0.65 (12 May 2002)
  ------------------

  * Added option to stop the results window scrolling down as new matches are
    found and added.
  * Fixed (hopefully) widthing bug in filetype menu under RISC OS 3.1.
  * Can now search a comma-separated list of directories.
  * Search is now more tolerant of filename termination.
  * Filetype menu can be made alphabetical or numerical depending on if
    Select or Adjust is used.
  * History entries can be given names.
  * Acts as FilerAction plugin under Select, so that searches can be started
    from the Filer menu.


  0.66 (13 May 2002)
  ------------------

  * Bug which prevented Filer Action plugin from terminating correctly has
    been fixed.


  0.67 (14 May 2002)
  ------------------

  * Bug which caused "Unknown or missing variable" errors as plugin searches
    ended has been fixed.
  * Clicking on the close icon of the 'active' results window during a search
    no longer crashes Locate (the search terminates correctly).


  0.70 (10 July 2002)
  -------------------

  * BASIC string length restriction removed from search path list (now 4095
    characters long by default).
  * Dragging objects into the path lists with Shift held down /replaces/ the
    contents of the list.
  * A warning is given if a search is attempted with no paths specified.
  * Overlength strings are now caught on all drop-down menu insertions in the
    Search window.
  * Does not need an icon bar icon or search window when acting as a plugin,
    and can quit once the search is over.
  * Choices window re-designed.


  0.71 (3 August 2002)
  --------------------

  * Fixed broken filetypes and file sizes reported when dragging objects out
    of the results window.
  * Bug in search error handling fixed (triggered when error reporting
    switched on).


  0.72 (18 August 2002)
  ---------------------

  * Fixed bug introduced in 0.70 that caused Age details to be ignored.


  0.73 (22 August 2002)
  ---------------------

  * Fixed bug introduced in 0.70 causing the action of the 'Ignore ImageFS's
    contents' option to be inverted.
  * Fixed bug with Age searches using start and end values.


  0.80 (29 September 2002)
  ------------------------

  * Full info display option added for results window (Locate file format
    upgraded to Version 1).
  * Fixed various issues relating to manipulating and dragging selections in
    the results window.
  * Info bar at base of results window is now filled (as per Style Guide).
  * Added 'Select all' option to results window menu.
  * Added 'Object info' option to results window menu.
  * Menu-selected items in the results window deselect correctly if the menu
    tree closes.
  * Documentation merged into one central file, from which StrongHelp and
    text versions are derived automatically.  The contents of the original
    text help were discarded.
  * Save boxes now remember their filenames and settings until the menu tree
    is closed.
  * Size of selection drag boxes from results window (if DragASprite support
    is off) now calculated correctly if the window is scrolled to the end.
  * Search error counting bug fixed.
  * !Locate.!Help updated to set <Locate$HelpText> to point to the plain text
    version of this file.
  * Missing interactive help added for Date/Age options pane.
  * Date and time selection windows added, to make entering the modification
    dates easier.
  * Full support for the RISC OS Theme Manager has been added.  Creating
    additional sprites is left as an exercise for the user.
  * Results window entries are greyed out if they are found to have been
    moved since the files were located.
  * Results window menu fixed so it works correctly with all windows during
    searching.
  * Locate will refuse to load a file during a search (and hence not fall
    over in the process).  A better fix is required.


  0.85 (14 December 2002)
  -----------------------

  Public Beta release.

  * Code updated to be 26/32-bit neutral.
  * Search routines changed to use OS_GBPB 10, to avoid problems with several
    filesystems when using OS_GBPB 11.
  * Search can support Untyped files correctly (and the correct sprites are
    used under Select).


  0.86 (6 February 2003)
  ----------------------

  Public Beta release.

  * Corrected use of OS_HeapSort32.
  * Corrected bug in History menu width calculations under RISC OS 3.1.


  0.87 (4 July 2003)
  ------------------

  Public Beta release.

  * Fixed bug that caused corrption of search options when 'Object name'
    field was left blank.
  * Added 'Website' button to Program Info window.
  * Potential problem with aborted RAM transfers fixed.


  0.88 (9 November 2003)
  ----------------------

  Public Alpha release.

  * Added "-open" command line switch to allow a search window to be opened
    at startup.
  * Supplied StartLocate utility to allow Locate to be used with the STDMMK
    drivers.
  * Files with no read permissions are trapped cleanly and logged in the
    results window if a contents search is attempted.
  * Paths are checked for length, with Locate aborting the current directory
    if they get too long for BASIC strings (preventing a crash).


  0.89 (1 February 2004)
  ----------------------

  * Fixed bug with contents search routines that prevented matches from being
    reported.


  0.89a (6 June 2004)
  -------------------

  * Fixed bug preventing unused keys being passed on from History Add window.


  0.89b (8 December 2004)
  -----------------------

  * Fixed bug causing filetype searches to fail for typed files when used in
    conjunction with date or age restrictions.


  2.00 (19 April 2013)
  --------------------

  First Stable Release of Locate 2.

  * Complete re-implementation in C.


  2.10 (26 February 2016)
  -----------------------

  Second stable release.

  * 'Default' hotlist items added, to allow a standard search to be
    customised (ticket #475).
  * Implement FilerAction Plugin code for use on RISC OS Select
    (ticket #557).
  * Fix ZeroPain errors when parsing search dialogue box (ticket #561).
  * Display filenames for error locations (ticket #557).


  2.11 (6 March 2016)
  -------------------

  Update to second stable release.

  * Stop stray debug output from being sent to Reporter (tickets #580 &
    #586).


  2.12 (28 July 2020)
  -------------------

  Update to second stable release.

  * Remove all unbounded string operations from source code.
  * Correctly ensure that a C99-friendly version of the Shared C Library is
    present (ticket #634).
  * Use ResConf-style system variables to identify resources.



Future Plans
------------

  This version of Locate is still not finished and several intended features
  are not yet implemented.  A list of my future plans is included here; if
  there is something that you think would be useful that isn't on this list,
  let me know (my email address is on the index page).

  * Cache search results or file locations in a file for faster searching.
  * Correctly measure icon sprite widths when laying out the results window.
  * Search the contents of Squashed files.
  * Allow actions to be carried out on found objects (set type, delete,
    etc.).
  * Give the search in field a drop-down menu listing the individual paths;
    toggle each on and off, and open individual entries?
  * Allow Regular Expressions to be used in file contents search.
  * Allow searches of search results.
  * Add stop/modify search buttons to the status bar (or toolbar).



Updates and Contacting Me
-------------------------

  If you have any comments about Locate, or would like to report any bugs
  that you find, you can email me at the address below.

  Updates to Locate and more programs for RISC OS computers can be found
  on my website at http://www.stevefryatt.org.uk/software/

  Stephen Fryatt
  email: steve@stevefryatt.org.uk
