% Toolbox M_NAMEBOX (names on m_maps)
% Version 0.5 30-Jun-2001
% Author Jan Even Nilsen, Geophysical Institute, Bergen (even@gfi.uib.no)
% Available at www.gfi.uib.no/~even/matlab/m_namebox/m_namebox.html
% Developed using M_Map v1.3f in MATLAB 5.3.0.10183 (R11) on NT4.0
% Checked to some degree by MATLAB 6.0 users.
%
% M_NAMES               Puts names of places on m_maps
% M_MOVETEXT            Customization of text objects in figures
% M_NEWNAME             GTEXT-type function for adding names to an m_map
% M_SAVENAME            Save names on an m_map to a database
% M_NAME_DEMO           A demo of the m_name-toolbox
% M_NAMEBASE.MAT        The main database of names and their positions
% M_NAMEBASE.HTML       HTML-documentation
% CONTENTS.M            This file
%
% SYNTHESIS:
% When an M_MAP of any projection or scale has been made, simply calling
% M_NAMES, puts names from the database in their right place on the map.
% The names might not be placed perfectly, but M_NAMES initiates M_MOVETEXT,
% with which you can choose any name with a mouseclick on it, move and
% change it with key-control.  M_NAMES also makes a listbox where you can
% choose names from all available names in the area, including the invisible
% ones (those too small for M_NAMES' size-limit).  More names can easily be
% added with M_NEWNAME('name'), or with keypress 'n' (see M_MOVETEXT), and
% names can be saved to the default database, or to a special base just for
% a particular map.  The toolbox works primarily as a keypress controlled
% "suite" after running M_NAMES, but the functions are stand alone functions
% and have more utilities than those accessed by M_MOVETEXT.  Please see the
% documentation of the functions, for detailed help.
%
% PRINCIPLE:
% The names are placed according to a 'between-two-points' principle: The
% file m_namebase.mat (or other namebase of yours) contains a database
% consisting of names, their two corresponding long/lat-points, along with
% other text-appearance properties. The name is centered on the line between
% the points and font-size is chosen to make the name fill the distance
% between points. Thus the names are placed and sized according to the shape
% of country or landmark they describe, independent of the size, projection
% and rotation of the map. Furthermore, the names are never plotted
% upside-down.  See M_SAVENAME on database-structure.
%
% CUSTOMIZATION: 
% The path and name of the main m_name-database (M_NAMEBASE), should be
% edited in the file M_NAMES.M. Below the help section there is a
% customization section you can edit. There is also a minimum font-size for
% the names to show on map, that might have to be set right for your system.
%
% DATABASES: 
% Although you can make several m_name-databases, it is recommended that you
% keep a well maintained default (main) database, since this is what you
% probably will be using every time you start putting names on a
% map. Furthermore, if you make maps with many new names, i.e. for uncovered
% areas, I'd be thankful if you sent your database.mat file to me,
% even@gfi.uib.no, so that I can expand the main-database for distribution
% with the m_names-toolbox. See M_SAVENAME for detailed instructions on
% building m_name-databases.
%
% KNOWN PROBLEMS: 
% 1) The routine may make visible too many or too few of the names according
% to the font-limit for text-visibility. This limit can be set to fit your
% terminal, in the customization-section in this file (M_NAMES.M).
% 2) When setting "NUM LOCK" on (which is needed for the M_MOVETEXT) the
% mouse buttons no longer work on some systems. However, the same
% characters on the main keyboard will work just as well.
% 3) A problem in MATLAB 6.0 was encountered by Roy Hourston, concerning
% some required field for the text objects "BeingDeleted", but he also
% fixed it, we hope ... ;-)
%
% FEEDBACK:
% As this toolbox is not widely used (yet), please feel free to send any
% questions and complaints to me (even@gfi.uib.no).