zEditLine, zEditNumber, zEditDate, zEditFile, zEditCombo, zEditPassword, edit
-----------------------------------------------------------------------------

	Summary  View classes for text input with horizontal scrolling.

	Derived  The base class is zEditLine, everything else descends in one
	         form or another from it. Each class notes the descendancy.

	Remarks  zEditLine is a sophisticated class for inputting a line of
	         text. It supports the direction keys, as well as horizontal
	         scrolling in both directions. zEditNumber is a descendant of
	         zEditLine and is used for inputting numbers. A variety of
	         options are supported, including hexadecimal input mode.
	         zEditDate is a descendant of zEditNumber and is used for
	         inputting dates. Supports European and American-style date
	         strings, and other options too. zEditFile is another descendant
	         of zEditLine and is used for inputting file names and paths.
	         This class does perform some limited validation and allows for
	         wildcards and/or filenames and paths. zEditCombo is another
	         derivative of zEditLine and is used to select from a list of
	         predetermined strings. It supports incremental searches.
	         zEditPassword is a class for inputting passwords. It supports
	         various options for replacement characters as well as using
	         the ProBoard's definition. edit is a class used for grouping
	         all options that are useful for customizing the behavior of all
	         other classes. The options are separated into groups, depending
	         on the class they apply to. This is different from the previous
             implementation where each class specified its own options. This
             is mainly done for ease of use because the name is shorter and
             easier to remember. All classes need to know the output area
             they can occupy on the screen. This is done with the 'bounds'
             parameter in the constructors. Note that the height should be
             set to 1. Also note that the actual string will occupy two
             characters less than the size of the given rectangle. The
             additional space is used by the class to display the scrolling
             indicators whenever necessary. Also note that the classes will
             change the current cursor location as well as the output colors.
             Make sure you adjust the appropriate settings.

             Here is a list of supported keystrokes and the actions they
             perform:

                Action              Native              Alternative
                -------------------------------------------------------
                Cursor left		    Left arrow		    Ctrl+S
                Cursor right	    Right arrow		    Ctrl+D
                Home cursor		    Home			    Ctrl+Q + S
                End of line		    End				    Ctrl+Q + D
                Word to the left    Ctrl+Left arrow	    Ctrl+A
                Word to the right   Ctrl+Right arrow    Ctrl+F
                Toggle insert mode  Ins   			    Ctrl+V
                Delete character    Del				    Ctrl+G
                Backspace		    Backspace		    Ctrl+H
                Delete line		    Ctrl+Y			    Ctrl+Y
                Delete word		    Ctrl+T			    Ctrl+T
                Mark whole line	    Ctrl+K + L		    Ctrl+K + L
                Unmark selection    Ctrl+K + H		    Ctrl+K + H

             Note that some of the keys might be disabled or behave
             differently in the derived classes. The mappings listed here
             are for the base zEditLine class. Note that both styles can be
             used locally, but only some of the native-style keys will be
             recognized remotely. In particular, the Ctrl+Arrow combinations
             will not work correctly in ProBoard. You should use the
             alternative style. Note that zEditCombo differs greatly in the
             way characters are handled. The Space and Shift+Space cause
             toggling of the item displayed in forward and reverse order
             respectively. Typing will generate incremental searches through
             the items list. Backspace will remove the last character from
             the search criteria, and Home will remove the search criteria.
             The user will not be able to select anything that is not on the
             list.

	Notes    It is very easy to create classes that add functionality or
	         handle special input cases (like number and date). All you need
	         to do is derive the new class from the appropriate base (usually
	         zEditLine, but it can be any of the other descendants, like
	         zEditNumber too), and then overrride the three virtual functions
	         getData(), setData(), and handle(). Usually, you may need to
	         filter or map keystrokes in the handle method to ensure proper
	         operation. See the zEditNumber and zEditDate classes for
	         examples of that behavior.


	ZEDITLINE::ZEDITLINE
	------------------------------------------------------------------------

		Summary  Constructs a editor line object.

		Syntax   zEditLine(const zRect &bounds, short maxLen);

		Remarks  Constructs a line editor object. Does not display the
		         empty string (call draw() to force it). Note that the
		         'bounds' rectangle should have a height of 1, and a
		         minimum width of 4. 'maxLen' specifies the maximum
		         allowable length of the input string. This number can be
		         larger than the horizontal extent of the bounding rectangle.
		         The class will scroll the view as necessary. This number
		         should not exceed 255 characters.


	ZEDITNUMBER::ZEDITNUMBER
	------------------------------------------------------------------------

		Summary  Creates a number input line.

		Syntax   zEditNumber(const zRect &bounds, short maxLen,
		                     short Options);

		Remarks  Refer to zEditLine's constructor for 'bounds' and 'maxLen'.
                 Note that there will be no length validation performed on
                 the input string. You will need to restrict it yourself to
                 the required length. The 'Options' parameter can be one
                 (or bitwise OR combination) of these:

                            edit::hex    -  allow hex input
                            edit::blank  -  blank is treated as 0
                            edit::pos    -  only positive numbers

                 The 'hex' flag will allow inputting and converting strings
                 that contain hexadecimal digits, and optionally, a leading
                 '0x' hex indicator. This option forces the 'edit::pos'
                 option too. The 'blank' flag will force a 0 in the data
                 line if it is blank. This will also ensure a 0 in the
                 getData() method. The 'pos' flag will force positive
                 numbers only to be allowed for input. This will disable
                 the signs (both of them).


	ZEDITDATE::ZEDITDATE
	------------------------------------------------------------------------

		Summary  Creates a date input editing object.

		Syntax   zEditDate(const zRect &bounds, short Options);

		Remarks  Refer to the zEditLine's constructor for a description of
		         the 'bounds' parameter. Note that this class forces
		         'maxLen' to 10 characters. You cannot change this. The
		         'Options' parameter can be a combination of the following:

                         edit::european  -  european date style
                         edit::american  -  american date style
                         edit::show	     -  display hint
                         edit::strict    -  will validate the date

                 Note that the date styles are currently used only to show
                 the appropriate hint with the 'show' flag. No data
                 validation will be performed by the getData() or the input
                 methods. If you do not specify a style, the American format
                 (MM/DD/YY) will be used. In strict mode, date validation
                 will be performed. The user will not be able to enter
                 invalid dates.


	ZEDITFILE::ZEDITFILE
	------------------------------------------------------------------------

		Summary  Creates a file (path) text input object.

		Syntax   zEditFile(const zRect &bounds, short maxLen, short Options);

		Remarks  Refer to the zEditLine's constructor for a description of
		         the 'bounds' and 'maxLen' parameters. The 'Options' flag
		         can be 0 or a combination of the following:

                        edit::path	     -  path mode
                        edit::wildcards  -  wildcards allowed
                        edit::upper	     -  convert input to uppercase

                 If you do not specify the 'path' flag, the class will only
                 accept valid file names (this will be strictly enforced),
                 without any directory specifications. This will restrict
                 the size of the buffer and ignore maxLen completely if it
                 is larger. If you decide to use wildcard characters, note
                 that the extended set (Grep/Glob) will be used (that is,
                 the range characters will be valid too). In 'path' mode,
                 the class will allow inputting of whole filepaths.


	ZEDITCOMBO::ZEDITCOMBO
	------------------------------------------------------------------------

		Summary  Creates a combo box input object.

		Syntax   zEditCombo(const zRect &bounds, short Options,
		                    zDoubleList *items);

		Remarks  Refer to the zEditLine's constructor for a description of
		         the 'bounds' parameter. Note that the 'maxLen' member will
		         be set internally to the largest possible value depending
		         on the length of the strings in the 'items' list. 'Options'
		         can be 0 or any combination of the following:

                         edit::init	    -  display the first string on init
                         edit::dispose  -  dispose of the 'items' list

                 The 'init' option controls how the input rectangle starts
                 up. It will default to empty, but if you specify the 'init'
                 flag, the first item from the list will be displayed. The
                 'dispose' flag controls the destructor. If it is set, the
                 'items' list will be deleted by the object on cleanup. This
                 is useful if you only make the list for use with this one
                 object.


	ZEDITPASSWORD::ZEDITPASSWORD
	-----------------------------------------------------------------------

		Summary  Creates a text input object for passwords.

		Syntax   zEditPassword(const zRect &bounds, short aMaxLen,
		                       short aOptions);

		Remarks  Refer to the zEditLine's constructor for a description of
		         the 'bounds' and 'maxLen' parameters. The 'Options' flag
		         can be 0 or one of the following:

                    edit::proboard  - load the character from ProBoard
                    edit::secure    - display a random character

                 By default, pwdChar (the character shown) will be a '*'.
                 You can change this behavior by either calling the
                 setPwdChar() member function or by using one of the above
                 two parameters. Note that 'edit::secure' takes precedence
                 if both are specified. In 'secure' mode, random characters
                 will be displayed to distract the snoopers from the
                 keyboard. The current password character setting is ignored
                 if this flag is on. The 'proboard' option will cause the
                 object to read the ProBoard configuration and get the
                 character specified in ProCFG as the password character.


	ZEDITLINE::~ZEDITLINE
	------------------------------------------------------------------------

		Summary  Destroys the line editor object.

		Syntax   zEditLine::~zEditLine();

		Remarks  Disposes of the internal buffers. You cannot retrieve the
		         string text after the destructor is called.


	ZEDITCOMBO::~ZEDITCOMBO
	------------------------------------------------------------------------

		Summary  Destroys the combo box object.

		Syntax   zEditCombo::~zEditCombo();

		Remarks  Depending on whether the 'edit::dispose' was specified in
                 the options to the constructor, the 'items' list will be
                 deleted.


	ZEDITLINE::LEFTARROW, ZEDITLINE::RIGHTARROW
	------------------------------------------------------------------------

		Summary	 The characters used by the objects to indicate direction.

		Syntax   static char zEditLine::leftArrow;
                 static char zEditLine::rightArrow;

		Remarks  These two characters are shared by all objects. They
		         define the characters used for the scrolling indicators.
		         Default to '' and '' respectively. There is rarely a
		         need to change them.


	ZEDITLINE::DRAW
	------------------------------------------------------------------------

		Summary  Draws the visible portion of the line editor.

		Syntax   virtual void draw();

		Remarks  This method performs the same function for all classes.
		         It displays the current string in the input line area,
		         adjusting colors and scrolling as necessary. You will
		         rarely need to call it directly except for initializing
		         areas. This method takes into account the state of the
		         object to determine the colors.


	ZEDITLINE::DRAWVIEW
	------------------------------------------------------------------------

		Summary	 Draw the view as focused.

		Syntax   virtual void drawView();

		Remarks  This method performs the same function for all classes.
		         It displays the current data regardless of the focused
		         state of the object. It will always display it as focused.
		         This does not change the state.


	ZEDITLINE::HANDLE
	------------------------------------------------------------------------

		Summary  Handle the keystrokes received by the object.

		Syntax   virtual void handle(ushort aKeyCode);

		Remarks  This method performs the same function for all classes. It
		         handles a keystroke. This method behaves differently in the
		         various classes, depending on the requirements. It expects
		         to be given a kbXXX constant to handle (see the zScanKey
		         classes for further information).


	ZEDITLINE::SETPALETTE
	------------------------------------------------------------------------

		Summary  Change the color and character definitions.

		Syntax   virtual void setPalette(const char *aPalette);

		Remarks  This changes the current object's palette. The palette
		         determines the colors for the various states of the input
		         line, as well as the background characters to use for the
		         fills. The layout is as follows (with the default settings
		         shown):

                     palette[0] - active foreground color (yellow on blue)
                     palette[1] - not used
                     palette[2] - active background color (blue on gray)
                     palette[3] - active background fill character ()
                     palette[4] - active selection color (blue on gray)
                     palette[5] - not used
                     palette[6] - inactive foreground color (cyan on blue)
                     palette[7] - not used
                     palette[8] - inactive background color (cyan on blue)
                     palette[9] - inactive background fill character (blank)

                 The 'aPalette' argument is simply an array of characters
                 with length 10 that specifies the new settings. The format
                 of the attribute bytes is the same as in Borland's
                 textattr() parameter (the standard PC color byte). Refer to
                 the <conio.h> manuals. Changing the palette does not force
                 a redraw, you will need to call the draw() method yourself.


	ZEDITLINE::SETSTATE
	------------------------------------------------------------------------

		Summary  Change the focused state of the line.

		Syntax   virtual void setState(Boolean enable);

		Remarks  Changes the state of the input line. If the 'enable'
		         parameter is True, the line will be focused, otherwise,
		         it will lose the focus. The focus state determines the
		         colors used to display the line. This function will cause
		         the line to be redrawn as appropriate.


	ZEDITLINE::GETSTATE
	------------------------------------------------------------------------

		Summary  Retrieves the current state of the object.

		Syntax   virtual Boolean getState();

		Remarks  Returns the current focus state of the input line. True
		         if the line is focused and False otherwise.


	ZEDITLINE::FORMATONDRAW
	------------------------------------------------------------------------

		Summary  Change the output dynamically.

		Syntax   virtual char formatOnDraw(char aChar);

		Remarks  This function is very useful if you want to change the way
		         the output looks like in a derived class. This function is
		         called for each character in the current buffer with the
		         character as a parameter. Whatever this function returns
		         will be used for the output (it will not change the
		         characters in the buffer). The default implementation
		         simply returns the same character, but the overriden
		         version in zEditPassword changes it.


	ZEDITLINE::SETDATA
	------------------------------------------------------------------------

		Summary  Copies new data into the input string.

		Syntax   virtual void setData(void *ptr);

		Remarks  Copies new data into the input string. Use this method to
		         force default settings that will display when the object
		         is first drawn. This function behaves differently according
		         to the class. The 'ptr' argument should point to a string
		         buffer. It will be cast to a (char *) and used as such to
		         copy bytes from the buffer. Only 'maxLen' or less bytes
		         will be copied, depending on the string length in the
		         buffer.


	ZEDITNUMBER::SETDATA
	------------------------------------------------------------------------

		Summary  Set the data using a number.

		Syntax   virtual void zEditNumber::setData(void *ptr);

		Remarks  The 'ptr' argument should point to a large integer. It
		         will be cast to (long *) and used as such. Depending on
		         the options for the object, the fucntion will display the
		         appropriate string that represents the number.


	ZEDITDATE::SETDATA
	------------------------------------------------------------------------

		Summary  Sets the date string.

		Syntax   virtual void zEditDate::setData(void *ptr);

		Remarks  The 'ptr' argument should point to a date-formatted string.
                 It will be expected to be in the form 'nn/nn/nn', where the
                 'nn' numbers vary according to the format. This method will
                 force the slash ('/') characters overwriting any other data
                 in those two positions.


	ZEDITFILE::SETDATA
	------------------------------------------------------------------------

		Summary  Sets the internal string.

		Syntax   virtual void zEditFile::setData(void *ptr);

		Remarks  The 'ptr' parameter is a pointer to a string. This one will
                 not be checked for validity, only length will be enforced.


	ZEDITCOMBO::SETDATA
	------------------------------------------------------------------------

		Summary  Sets the text from a list in the combo.

		Syntax   virtual void zEditCombo::setData(void *ptr);

		Remarks  Searches the list for a match to the string pointed to by
                 the 'ptr' argument. If found, sets it in the input line. If
                 not, defaults to the last string in the list.


	ZEDITPASSWORD::SETDATA
	------------------------------------------------------------------------

		Summary  Sets the internal password string.

		Syntax   virtual void zEditPassword::setData(void *ptr);

		Remarks  Same as zEditLine's setData() method.


	ZEDITLINE::GETDATA
	------------------------------------------------------------------------

		Summary  Retrieve the string from the internal buffer.

		Syntax   virtual void getData(void *ptr);

		Remarks  This is the reverse of the setData() method. Refer to
		         setData() for a description of the appropriate pointers
		         that need to be used. This function will extract the data
		         from the input line's buffer and convert it according to
		         the specifications. The 'ptr' parameter should be a pointer
		         to a buffer large enough to hold 'maxLen' characters. The
		         result will be a valid NUL-terminated string (buf must be
		         maxLen+1 long).


	ZEDITNUMBER::GETDATA
	------------------------------------------------------------------------

		Summary  Get the number represented by the string in the buffer.

		Syntax   virtual void zEditNumber::getData(void *ptr);

		Remarks  The 'ptr' parameter whould be a pointer to a long integer.
                 The function will convert the string according to the
                 options you specified in the constructor and place the
                 result in the location pointed to by 'ptr'.


	ZEDITDATE::GETDATA
	------------------------------------------------------------------------

		Summary  Retrieves the date string from the buffer.

		Syntax   virtual void zEditDate::getData(void *ptr);

		Remarks  The 'ptr' parameter should be a pointer to a buffer large
                 enough to hold 10 characters plus a NUL terminator. The
                 string created by this function will have the 'nn/nn/nn'
                 format. Note that no validation is performed: not all of
                 the characters are guaranteed to be valid or even present.
                 It is guaranteed, however, that the slashes ('/') will be
                 in their appropriate positions.


	ZEDITFILE::GETDATA
	------------------------------------------------------------------------

		Summary	 Get the path (file) specification from the buffer.

		Syntax   virtual void zEditFile::getData(void *ptr);

		Remarks  The 'ptr' argument should be large enough to accomodate the
                 resulting paths. Usually, the length you specified will be
                 sufficient as the buffer size.


	ZEDITCOMBO::GETDATA
	------------------------------------------------------------------------

		Summary	 Retrieve the string from the combo collection.

		Syntax   virtual void zEditCombo::getData(void *ptr);

		Remarks  Copies the current string to the character buffer pointed
		         to by the 'ptr' parameter. The buffer should be large
		         enough to accomodate the largest string in the items list.


	ZEDITPASSWORD::GETDATA
	------------------------------------------------------------------------

		Summary  Retrieve the password from the buffer.

		Syntax   virtual void zEditPassword::getData(void *ptr);

		Remarks  Same as zEditLine's getData() method.


	ZEDITDATE::VALID
	------------------------------------------------------------------------

		Summary  Checks keystroke for validity for the position.

		Syntax   Boolean zEditDate::valid(ushort aKeyCode);

		Remarks  Returns True if the character is valid for the current
		         position in the date string and False otherwise.


	ZEDITPASSWORD::SETPWDCHAR
	------------------------------------------------------------------------

		Summary  Sets the character used for displaying passwords.

		Syntax   char zEditPassword::setPwdChar(char aChar);

		Remarks  Sets the password character to 'aChar' and returns the
		         old one.

