zCommandItem
============================================================================

	Summary  A class to manage lists of command items for the command line.

	Remarks  zCommandItem is a class that defines the objects manipulated
             by the status line class. Note that it is perfectly acceptable
             to have objects that are non-displayable (i.e. don't have any
             text). These will not be shown by the status line, but the
             associated keystroke will still generate the appropriate
             command. Also note that zCommandBar will only display as many
             items as the bounding rectangle can hold. The rest will not be
             shown, and cannot be selected with the highlight bar. They
             still will respond to the keystrokes, though.

zCommandBar
============================================================================

	Summary  A view class for managing command-line (status lines).

	Derived  None.

	Remarks  This class used to be called status line class except it
	         was decided that the name is a misnomer. A better name would
	         be a menu class or a command-line class. A 'command line' here
			 is defined as a set of command items which can be selected
			 either by a hotkey or by highlighting and pressing Enter.
             zCommandBar is a sophisticated class for managing status
             lines. For our purposes, a status line is defined as an area
             on the screen that has multiple items (of zCommandItem type)
             which can respond to user commands. zCommandBar is responsible
             for drawing the items, and managing the interaction. It is not
             a true status line in the general sense because it provides a
             highligh bar for selecting the items, as well as hotkeys. It
             is more of a command line in this respect.

             zCommandBar should occupy a rectangle that has a height of 1
             and a width of at least 4, but not more than 80 characters.
             This is defined by the 'bounds' parameter to the constructor.
             You can also change the default palette and set up your custom
             colors and background characters.

             zCommandBar can only process keystrokes in its handle() method
             if it has the 'focus' bit set in its 'options' data member.
             You can also hide and unhide the line (refer to the 'options'
             data member).


	COMMANDS
	------------------------------------------------------------------------

		Summary  Special command constants generated by the command line.

		Syntax   const short cmNoCommand = -1;
                 const short cmCancel = -2;

		Remarks  Both constants are reserved by the class for use as return
		         values in the zCommandBar::handle() method. The first
		         specifies that no command was generated this time, and
		         the second - that Escape was pressed by the user.


	OPERATORS
	------------------------------------------------------------------------

		Summary  Operator for building the lists for command items.

		Syntax   zCommandItem* operator+(zCommandItem *item,
		                                 zCommandItem &link);

		Remarks  Used for constructing the list of status item in an
		         easier and more readable way. This operator will append
		         the 'link' to the last item in the 'item' pointer's list.
		         You would then use the 'list' pointer as an argument to
		         the zCommandBar constructor. Of course, you can skip the
		         assignment and construct the list straight in the
		         constructor's call, but it is less readable.

		Return   A pointer to the 'item' that can be used for chaining.

		Example  zCommandItem *list = new zCommandItem("~F~irst", 'F', 1)
                                   + *new zCommandItem("~S~econd", 'S', 2)
                                   + *new zCommandItem("~T~hird", 'T', 3);


	ZCOMMANDITEM::ZCOMMANDITEM
	------------------------------------------------------------------------

		Summary  Constructs a command-line command object.

		Syntax   zCommandItem(const char *aText, ushort aKey,
		                      ushort aCmd, zCommandItem *next);

		Remarks  Constructs a menu item. The 'aText' parameter can be 0,
		         in which case the item is non-displayable (but will still
		         react to user keys). 'aKey' parameter defines the hotkey
		         used to activate the item. This can be a regular key (not
		         case-sensitive, either upper or lowercase will match), or
		         it can be a kbXXX constant, in which case it should match
		         the keypress exactly. 'aCmd' is the command ID that will
		         be generated when this item is selected either by the
		         hotkey, or by pressing Enter when the item is highlighted.
		         The 'next' parameter is used for linking the next item to
		         this one. Note that you have to allocate the items
		         dynamically as the destructor of the status line will
		         'delete' them all. If they are static, this will cause
		         your program to misbehave. The 'aText' parameter can
		         contain highlight characters itself. They should be
		         enclosed in two '~' (tilde) characters. You can have as
		         many of those as you will, but they must be in pairs for
		         correct operation. Note that the first and last characters
		         can also be made special (and displayed in different
		         colors), which is great if you like your items enclosed in
		         brackets. Refer to the 'options' data member for
		         zCommandBar for more information about this.


	ZCOMMANDBAR::ZCOMMANDBAR
	------------------------------------------------------------------------

		Summary  Create but does not display the command-bar object.

		Syntax   zCommandBar(const zRect &bounds, zCommandItem *aList);

		Remarks  Constructs (but does not display) a status line. Note that
		         the 'bounds' parameter can be only 1 row high, and should
		         not be more than 80 characters wide. The most common
		         setting here (in the ProBoard environment) would be
		         zRect(1,24,81,25). The 'aList' parameter points to the
		         first item in the zCommandItem list that has been
		         previously constructed. By default all items in the list
		         will be enabled. To change this, refer to the
		         enableCommand() method below.

		See also zCommandBar::enableCommand, zCommandBar::draw


	ZCOMMANDBAR::~ZCOMMANDBAR
	------------------------------------------------------------------------

		Summary  Destroys the command-line and performs all cleanup.

		Syntax   ~zCommandBar();

		Remarks  Disposes of all items in the zCommandItem list. All of
		         these should have been allocated dynamically before that.


	ZCOMMANDBAR::OPTIONS
	ZCOMMANDBAR::HIDE, ZCOMMANDBAR::FOCUS, ZCOMMANDBAR::DELIM
	------------------------------------------------------------------------

		Summary  Enumeration constants for determining the state of the line.

		Syntax   enum { hide, focus, delim };
                 ushort zCommandBar::options;

		Remarks  Controls the various aspects of the zCommandBar
		         behavior. By default, it will be set to (focus | delim)
		         which will make the status line visible, focused, and will
		         also define the first and last character of each menu item's
		         text as special characters (will use different colors for
		         them). This is a bit-mapped integer that is publicly
		         accessible to you. Note that changes will not take effect
		         after you change it, until you call the draw() method. You
		         can use any combination of the above three enumerated items:

                          hide  - make the line invisible if set
                          focus - focus the line if set
                          delim - treat first and last chars if set

                 The 'hide' flag, if set, will make the line invisible. How
                 it is drawn will depend on the focus state. It will always
                 display as the background character in the background color
                 and the whole bounding area will be cleared. Does not
                 affect the focus state. The 'focus' flag, if set will enable
                 the status line's keystroke processing capabilities.
                 Otherwise, the line will be drawn in its inactive state and
                 the handle() method will return a cmNoCommand constant every
                 time it is called. The 'delim' flag specifies how the first
                 and last characters of the menu items should be treated. If
                 set, they are assumed to be special and the three additional
                 palette colors will be used to display them. Otherwise,
                 they will appear as all other normal characters in the item.
                 Setting this to on (the default) makes great-looking menus
                 that have the items enclosed in brackets (as in the
                 example).


	ZCOMMANDBAR::HANDLE
	------------------------------------------------------------------------

		Summary  Handles the keystrokes and maps the commands.

		Syntax   virtual short handle(ushort aKeyCode);

		Remarks  This is the heart of the status line object. It will
		         process incoming kbXXX constants or regular keys (see
		         the zEventManager class). This function will process the
		         left and right direction keys, as well as Home and End to
		         move the selection bar as applicable. It will also recognize
		         Enter (and return the current item's command) and Escape
		         (and return cmCancel). If a hotkey was pressed, the items
                 list will be searched and on a match, the item found will be
                 focused and its command returned. If no command can be
                 generated (due to any reason), returns cmNoCommand. This
                 method handles all drawing and updating itself. Note that
                 disabled items will be focused on the line, but the method
                 will still return cmNoCommand. If the object is not focused,
                 ignores keystrokes and always returns cmNoCommand;


	ZCOMMANDBAR::DRAW
	------------------------------------------------------------------------

		Summary  Draws the status line according to its current state.

		Syntax   virtual void draw();

		Remarks  The principal drawing routine. Takes into consideration the
		         width of the rectangle, the current state, and the palette
		         settings. Will always redraw the whole line. You will not
		         usually need to call it directly unless when you want to
		         display the status line after creating it, or when you have
		         changed the 'options' data member and would like to change
		         the appearance accordingly.


	ZCOMMANDBAR::SETPALETTE
	------------------------------------------------------------------------

		Summary	 Changes the color palette for the status line.

		Syntax   void setPalette(const char *aPalette);

		Remarks  Changes the current palette. Changes will not take effect
		         until the draw() method is called. The 'aPalette' parameter
		         is simply an array of 15 bytes. The default settings (used
		         when this method is called with 0 as an argument) are as
		         follows:

                 [0]  - focused text                    : white on black
                 [1]  - focused highlight characters    : cyan on black
                 [2]  - focused disabled text           : dark grey on black
                 [3]  - focused highlight bar           : yellow on blue
                 [4]  - focused disabled highlight bar  : cyan on blue
                 [5]  - focused background color        : black on black
                 [6]  - focused background character    : space
                 [7]  - non-focused text                : black on grey
                 [8]  - non-focused highlight chars     : red on grey
                 [9]  - non-focused disabled text       : dark grey on grey
                 [10] - non-focused background color    : black on grey
                 [11] - non-focused background character: space
                 [12] - focused first and last chars    : bright blue on black
                 [13] - focused highlight first and last: bright blue on blue
                 [14] - non-focused first and last      : white on grey

                 Note that the last three entries will only be used if the
                 'delim' flag is on (see the 'options' data member). You can
                 specify the colors using the normal PC attribute format
                 (refer to the manual for textattr() function).


	ZCOMMANDBAR::GETCOLOR
	------------------------------------------------------------------------

		Summary	 Return the palette contents for a specific color.

		Syntax   uchar getColor(short aColor);

		Remarks  Return the palette setting for the 'aColor' index. Rarely
		         used in applications.


	ZCOMMANDBAR::ENABLECOMMAND
	------------------------------------------------------------------------

		Syntax  Enable or disable command items in the command list.

		Syntax  void enableCommand(ushort aCommand, Boolean enable);

		Remarks Enables or disables a command in the list. The 'aCommand'
		        parameter should match a value given in one of the
		        zCommandItem constructors. The 'enable' parameter determines
		        if the command will be enabled (True) or disabled (False).
		        The visual appearance will not change until the draw()
		        method is called. A disabled item can be selected with the
		        highlight bar (if visible), but will not generate the
		        command associated with it.


	ZCOMMANDBAR::SETSTATE
	------------------------------------------------------------------------

		Summary	 Changes the focused state for the status line.

		Syntax   void setState(Boolean focused);

		Remarks  Sets the focused state of the command bar to the 'focused'
		         argument of this method. This is a shortcut of the normal
		         sequence of setting the 'options' member and then calling
		         the draw() method.


	ZCOMMANDBAR::SHOW
	------------------------------------------------------------------------

		Summary	 Hides or displays the command bar.

		Syntax   void show(Boolean enable);

		Remarks  If the 'enable' argument is True, the command bar's state
		         will be set so that it can be displayed. Otherwise, the
		         state is set to hidden. The command bar is then redrawn.
		         This is a shortcut for the normal sequence of events which
		         requires you to set the 'options' data member and then
		         call the draw() method manually.


