"Overview of the navigator object"

	This is a TreeView control based on PB's datawindow technology.
	In past, there have been a few successful attempts at creating a datawindow-based
TreeView control. This object is radically different from most other attempts in it's
approach towards the actual logic of forming the tree structure at run-time. It heavily
relies on following two techniques:
1. Create 'hidden' datawindow columns, use them in conditional expressions for attributes
   of different datawindow objects (like line, text), populate these columns through
   event-scripts to manipulate the behaviour of the datawindow objects at run-time on a
   'row-by-row basis'.
2. Dynamic creation of a datawindow's internal objects on an 'as-required' basis.
	It's the use of the first technique which gives this object a major performance boost as
compared to other similar efforts, restricting it's size at the same time. And it's the
second technique which enables us to have as many levels in the tree structure as desired,
thus providing complete flexibility.

	Though this object was originally designed with the intention of providing TreeView
functionality for PB4 applications, it does offer, and has the potential to offer, much more
than basic navigational functionality for hierarchical data.
	Keeping in mind that PB is a database front-end tool, it has been created to cater to the
data retrieved from database, rather than data inserted manually by programming the object.
However, it can very well be enhanced to serve that cause also.
	The major benefit provided by the object is that it completely automates the task of
retrieving data from the database and allowing user to navigate through it. Absolutely no
coding is required. With this object, all you need to do is to give the names of related
database objects which actually contain the data (tables from which the data comes, the
primary key columns, columns to be actually displayed and the relationships between the
tables in the form of foreign keys). The object works as a stand-alone component which can
be used in plug-and-play mode.

Usage:
1. Create a standard user object based on dw control under the scope of the application.
2. Place the navigator user object on the window. Let's call it uo_nav.
3. Populate essential instance array variables in the
   ue_preconstructor event of uo_nav. These include variables required to display data,
   bitmap variables, variable containing name of standard dw-based user object.
4. Populate other instance variables to customize visual and/or behavioural
   attributes of the component.
5. Save the window and run the application.

Example:
   The following piece of code displays data from customer, sales_order and
sales_order_items	tables from PS Demo DB database:

is_table[1] = "customer"
is_id_column[1] = "id"
is_text_column[1] = "fname"
is_parent_column[1] = "state_id2"
is_expand_bmp[1] = "~'C:\Work\Pick9.bmp~'"    // A database column which contains the bmp file name
is_collapse_bmp[1] = "~'C:\Work\Next2.bmp~'"  // path can be given here instead

is_sort_col_num[1] = "3"         // Provides sort functionality.


is_table[2] = "sales_order"
is_id_column[2] = "id"
is_text_column[2] = "region"
is_parent_column[2] = "cust_id"
is_expand_bmp[2] = "~'C:\Work\Pick3.bmp~'"
is_collapse_bmp[2] = "~'C:\Work\Next2.bmp~'"

is_table[3] = "sales_order_items"
is_id_column[3] = "line_id"
is_text_column[3] = "quantity"
is_parent_column[3] = "id"
is_expand_bmp[3] = "~'C:\Work\Pick9.bmp~'"
is_collapse_bmp[3] = "~'C:\Work\Pick9.bmp~'"

is_sql_tail[3] = "WHERE quantity < 10"     // Applies constraints for filtering data

is_udw_name = "u_dw"
is_apex_bmp = "C:\Work\Norstan.bmp"

// Controlling other features.
ii_select_level = -10
il_back_color = 12632256
il_line_color = 0
ib_hide_buttons = TRUE

Features provided:
1. You can sort the items under a branch by the primary key value or the text displayed, or
   a database column dedicated to store the sort order; and can also control the order
   (ascending/descending). The setting done to the dedicated sort column gets the precedence
   if conflicting settings are done.
   Variable is_sort_column[] is used to provide name of dedicated sort column.
   Variable is_sort_col_num[] is used to provide index of some other column on which a sort
   is desired. Values are :
   1 - sort on primary key
   3 - sort on text displayed

   Variable is_sort_order[] is used to control the 'sort sense'. Values are 'A' and 'D'.

2. You can display a different picture at each level and for each state within that level
   (expanded/collapsed); or you can store the name of the bmp in a database column against
   each item and then display a different picture for each item.
   Giving file name:
   is_collapse_bmp[2] = "~'C:\Work\Next2.bmp~'"
   Giving name of database column containing the filename:
   is_collapse_bmp[2] = "collapse_bmp"

3. Values from more than one database columns can be displayed as text (label). If a column
   is not non-character, convert it to character.
   Eg;
   is_text_column[3] = "Convert (Varchar(20), quantity) + ~'   ~' + Convert (Varchar(20), ship_date)"

4. One can be selective while grabbing data from database. This is done by applying
	constraints to the data in the form of a WHERE clause.
   Eg;
   is_sql_tail[1] = is_sql_tail[1] = "WHERE state = 'CA'"

5. Following visual attributes can be controlled:
   Background color, line color.

6. You can have a choice regarding highlighting the items using the ii_select_level instance
   variable. Options and their corresponding values are:
   None : 0
   A particular level : index of that level
   All levels : -1
   Leaf items only : -10 or index of lowest level

7. The DoubleClicked! event of the navigator dw is exposed to the outer environment
   ('ue_dw_doubleclicked') and can be coded at the descendent level. There the handles of all
   items highlighted at that time are made available to the user through an array of structure
   instance variable istr_item_handle[]. It gives you the item_id and the item_text of the
   selected item.

8. The RButtonDown! event of the navigator dw is also exposed to the outer environment
   ('ue_dw_rbuttondown') and can be coded at the descendent level. There it returns dw row
   number of the right-clicked row. Usually, it can be used to display a popup menu with
   menu items operating on the right-clicked row or the entire data displayed.

9. The 'Expand-All'/'Collapse-All' functionality has been provided using CommandButtons which
   can be hidden by setting the flag 'ib_hide_buttons'.
   Additionally, events 'ue_expand_all', 'ue_collapse_all' and 'ue_expand_below' (expands
   completely the right-clicked branch only) have been given so that they can be called from
   an object like an external popup menu.

10. Exposes a 'ue_ok' event to the environment, which can be Triggered from outside, say, an Ok
   button, and can be coded at the descendent level. Here again the handles of all items
   highlighted at that time are made available to the user.

11. An upward arrow shows when there are items above the first one displayed in the navigator.
   Also, if there is no room on the object's display area to accommodate child items of an
   expanded branch, the expanded item scrolls up to become the first one on the page.

Assumptions about database schema:
These asssumptions do impose some restrictions on the definition of data, but they are based
on the situations which we often come across and resemble the standard way of implementing
hierarchical data structure in a relational model.
1. The primary key has to be a numeric one. Composite keys are not supported.
2. Relationships should be implemented using normalized table structures and foreign keys.
   It is NOT required that referential integrity be enforced using domain level integrity
	constraints or triggers. A relationship implemented using denormalization is not supported.

A word of caution:
1. We recommend not to use custom-made bmp's made using MS Photo Editor etc.. They take too
   much time to load. We need to do more experimentation in this area. For best performance,
	you may use bmp's shipped with PB or downloaded from a PB resource site, for now.
2. The SQL coded is known to support Sybase SQL server, Sybase SQL anywhere and MS SQL server.
   It has not been verified for other databases, so far.

Scope for future extensions:
1. Support a parent-child relationship implemented using one table.
2. Provide functions and events to manipulate the items manually and individually (not
   programmatically and not in bulk as it does right now).
3. Allow user to control more visual attributes such as text font size, color of hightlight,
   row height.
4. Give an interface similar to Microsoft TreeView class (+/- signs and a bmp for each row).

Please NOTE: Logic-wise, all of these extensions, except the last one, are simple additions
to the already existing architecture of the object; and I have the crude logic in my head for
them. These things could not be implemented due to sheer lack of time. If somebody wants to
use this object and likes to make these enhancements, I am ready to play my role in it by
providing an insight to the internal working of this object and logic help.


