home *** CD-ROM | disk | FTP | other *** search
/ Piper's Pit BBS/FTP: ibm 0010 - 0019 / ibm0010-0019 / ibm0010.tar / ibm0010 / CLIPB51.ZIP / C5P78.EXE / TBROWSE.DOC < prev   
Encoding:
Text File  |  1990-05-31  |  17.5 KB  |  530 lines
  1. Notes on the predefined TBrowse object class.
  2.  
  3. Note:  this information supersedes the information in the
  4. pre-release documentation.
  5.  
  6.  
  7. o TBrowse
  8.  
  9.   Note:  for a general discussion of Clipper 5.0 predefined
  10.   objects (and Tbrowse objects), refer to the "Basic
  11.   Concepts" chapter of the documentation.
  12.   
  13.   A TBrowse object is a general purpose browsing mechanism for
  14.   table-oriented data.  TBrowse objects provide a sophisticated
  15.   architecture for acquiring, formatting, and displaying data. 
  16.   Data retrieval and file positioning are performed via
  17.   user-supplied code blocks, allowing a high degree of
  18.   flexibility and interaction between the browsing mechanism and
  19.   the underlying data source.  The format of individual data
  20.   items can be precisely controlled via the data-retrieval code
  21.   blocks; overall display formatting and attritubutes can be
  22.   controlled by sending appropriate messages to the TBrowse
  23.   object.
  24.  
  25.   A TBrowse object relies on one or more TBColumn objects.  A
  26.   TBColumn object contains the information necessary to define a
  27.   single column of the browse (see the section on TBColumn
  28.   objects below).
  29.  
  30.   During operation, a TBrowse object retrieves data by evaluating
  31.   code blocks.  The data is organized into rows and columns, and
  32.   displayed within a specified rectangular area of the screen. 
  33.   The TBrowse object maintains an internal "browse cursor."  The
  34.   data item on which the browse cursor rests is displayed in a
  35.   highlighted color.  (The actual screen cursor is also
  36.   positioned to the first character of this data item.)
  37.  
  38.   Initially, the browse cursor is placed on the data item at the
  39.   top left of the browse display.  Messages can then be sent to
  40.   the TBrowse object to navigate the displayed data, causing the
  41.   browse cursor to move.  These messages are normally sent in
  42.   response to user keystrokes.
  43.  
  44.   New data is automatically retrieved as required by navigation
  45.   requests.  When navigation proceeds past the edge of the
  46.   visible rectangle, rows or columns beyond that edge are
  47.   automatically brought into view.  When new rows are brought
  48.   into view, the underlying data source is repositioned by
  49.   evaluating a code block.
  50.  
  51.  
  52. o Exported Instance Variables
  53.  
  54.   cargo   (Assignable)
  55.   
  56.   Contains a value of any data type.  This instance variable is
  57.   unused by the standard TBrowse object.  It is provided as a
  58.   user-definable slot.
  59.   
  60.   
  61.   colCount
  62.   
  63.   Contains a numeric value indicating the total number of data
  64.   columns in the browse.  For each column, there is an associated
  65.   TBColumn object.
  66.   
  67.   
  68.   colorSpec  (Assignable)
  69.   
  70.   Contains a character string defining a color table for the
  71.   TBrowse display.  By default, the current SETCOLOR() value is
  72.   copied into this variable when the TBrowse object is created
  73.   (see the Standard Functions chapter).
  74.   
  75.   
  76.   colPos  (Assignable)
  77.   
  78.   Contains a numeric value that indicates which data column the
  79.   browse cursor is currently on.  Columns are numbered from one,
  80.   starting with the leftmost column.
  81.   
  82.   
  83.   colSep  (Assignable)
  84.   
  85.   Contains a character value which defines a default column
  86.   separator for TBColumns which don't specify a column separator
  87.   (see the section on the TBColumn class).
  88.   
  89.   
  90.   freeze  (Assignable)
  91.   
  92.   Contains a numeric value that defines the number of data
  93.   columns frozen on the left side of the display.  Frozen columns
  94.   are always visible, even when other columns are panned off the
  95.   display.
  96.   
  97.   
  98.   goBottomBlock (Assignable)
  99.   
  100.   Contains a code block that is executed in response to the
  101.   goBottom message.  This block is responsible for repositioning
  102.   the data source to the last record which is to take part in the
  103.   browse.  Typically, the data source is a database file and this
  104.   block contains a call to a function that executes a GO BOTTOM
  105.   command.
  106.   
  107.   
  108.   goTopBlock (Assignable)
  109.   
  110.   Contains a code block that is executed in response to the goTop
  111.   message.  This block is responsible for repositioning the data
  112.   source to the first record which is to take part in the
  113.   browse.  Typically, the data source is a database file and this
  114.   block contains a call to a function that executes a GO TOP
  115.   command.
  116.   
  117.   
  118.   headSep (Assignable)
  119.   
  120.   Contains a character value which defines a default heading
  121.   separator for TBColumns which don't specify a heading separator
  122.   (see the section on the TBColumn class).
  123.   
  124.   
  125.   hitBottom  (Assignable)
  126.   
  127.   Contains a logical value.  A true (.T.) value indicates that an
  128.   attempt was made to navigate past the end of the available
  129.   data.  During stabilization, the TBrowse object sets this
  130.   variable if the skip block indicates that it was unable to skip
  131.   forward as many records as requested.
  132.   
  133.   
  134.   hitTop  (Assignable)
  135.   
  136.   Contains a logical value.  A true (.T.) value indicates that an
  137.   attempt was made to navigate past the beginning of the
  138.   available data.  During stabilization, the TBrowse object sets
  139.   this variable if the skip block indicates that it was unable to
  140.   skip backward as many records as requested.
  141.   
  142.   
  143.   nBottom (Assignable)
  144.   
  145.   Contains a numeric value that defines the bottom screen row
  146.   used for the TBrowse display.
  147.   
  148.   
  149.   nLeft   (Assignable)
  150.   
  151.   Contains a numeric value that defines the leftmost screen
  152.   column used for the TBrowse display.
  153.   
  154.   
  155.   nRight  (Assignable)
  156.   
  157.   Contains a numeric value that defines the rightmost screen
  158.   column used for the TBrowse display.
  159.   
  160.   
  161.   nTop (Assignable)
  162.   
  163.   Contains a numeric value that defines the top screen row used
  164.   for the TBrowse display.
  165.   
  166.   
  167.   rowCount
  168.   
  169.   Contains a numeric value indicating the number of data rows
  170.   that are visible in the browse display.  Only data rows are
  171.   included in the count; rows occupied by headings, footings, or
  172.   separators are not included.
  173.   
  174.   
  175.   rowPos  (Assignable)
  176.   
  177.   Contains a numeric value that indicates which data row the
  178.   browse cursor is currently on.  Data rows are numbered from
  179.   one, starting with the topmost data row.  Screen rows
  180.   containing headers, footers or seperators are not considered
  181.   data rows.
  182.   
  183.   
  184.   skipBlock  (Assignable)
  185.   
  186.   Contains a code block that takes a single numeric parameter. 
  187.   During stabilization, this code block is executed when the
  188.   TBrowse object needs to reposition the data source.  The
  189.   numeric parameter passed to the block represents the number of
  190.   records to be skipped.  A positive value means skip forward and
  191.   a negative value means skip backward.  A value of zero
  192.   indicates that the data source does not need to be
  193.   repositioned, but the current record may need to be refreshed. 
  194.   Typically, the data source is a database file and this block
  195.   calls a function that executes SKIP commands to reposition the
  196.   record pointer.
  197.   
  198.   The block must return the number of rows (positive, negative or
  199.   zero) actually skipped.  If the value returned is not the same
  200.   as the value requested, the TBrowse object assumes that the
  201.   skip operation encountered beginning or end of file.
  202.   
  203.   
  204.   stable  (Assignable)
  205.   
  206.   Contains a logical value that is true (.T.) if the TBrowse
  207.   object is stable and false (.F.) otherwise.  The browse is
  208.   considered stable when all data has been retrieved and
  209.   displayed, the data source has been repositioned to the record
  210.   corresponding to the browse cursor, and the current cell has
  211.   been highlighted.  When navigation messages are sent to the
  212.   TBrowse object, this flag is set to false (.F.).  After
  213.   stabilization is performed (using the stabilize message), the
  214.   flag is set to true (.T.).
  215.  
  216.  
  217. o Cursor Movement Methods
  218.   
  219.   down() <-- self
  220.   
  221.   Moves the browse cursor down one row.  If the cursor is already
  222.   on the bottom row, the display is scrolled and a new row is
  223.   brought into view.  If the data source is already at logical
  224.   end-of-file and the browse cursor is already on the bottom row,
  225.   hitBottom is set true (.T.).
  226.   
  227.   
  228.   end() <-- self
  229.   
  230.   Moves the browse cursor to the rightmost data column that is
  231.   currently visible.
  232.   
  233.   
  234.   goBottom() <-- self
  235.   
  236.   Repositions the data source to logical bottom-of-file (by
  237.   evaluating the goBottomBlock), refills the display with the
  238.   bottom-most available data, and moves the browse cursor to the
  239.   lowermost data row for which data is available.  The pan
  240.   position of the window is not changed.
  241.   
  242.   
  243.   goTop() <-- self
  244.   
  245.   Repositions the data source to logical top-of-file (by
  246.   evaluating the goTopBlock), refills the display with the
  247.   topmost available data, and moves the browse cursor to the
  248.   uppermost data row for which data is available.  The pan
  249.   position of the window is not changed.
  250.   
  251.   
  252.   home() <-- self
  253.   
  254.   Moves the browse cursor to the leftmost unfrozen column on the
  255.   display.
  256.   
  257.   
  258.   left() <-- self
  259.   
  260.   Moves the browse cursor left one data column.  If the cursor is
  261.   already on the leftmost displayed column, the display is panned
  262.   and the previous data column (if there is one) is brought into
  263.   view.
  264.   
  265.   
  266.   pageDown() <-- self
  267.   
  268.   Repositions the data source downward and refills the display. 
  269.   If the data source is already at logical end-of-file (i.e. the
  270.   bottom-most available record is already shown), the browse
  271.   cursor is simply moved to the lowermost row containing data. 
  272.   If the data source is already at logical end-of-file and the
  273.   browse cursor is already on the bottom row, hitBottom is set
  274.   true (.T.).
  275.   
  276.   
  277.   pageUp() <-- self
  278.   
  279.   Repositions the data source upward and refills the display.  If
  280.   the data source is already at logical beginning-of-file (i.e.
  281.   the topmost available record is already shown), the browse
  282.   cursor is simply moved to the top data row.  If the data source
  283.   is already at logical beginning-of-file and the browse cursor
  284.   is already on the first data row, hitTop is set true (.T.).
  285.   
  286.   
  287.   panEnd() <-- self
  288.   
  289.   Moves the browse cursor to the rightmost data column, causing
  290.   the display to be panned all the way to the right.
  291.   
  292.   
  293.   panHome() <-- self
  294.   
  295.   Moves the browse cursor to the leftmost data column, causing
  296.   the display to be panned all the way to the left.
  297.   
  298.   
  299.   panLeft() <-- self
  300.   
  301.   Pans the display without changing the browse cursor (if
  302.   possible).  When the screen is panned with panLeft, at least
  303.   one data column which was out of view to the left is brought
  304.   into view, while one or more columns are panned off screen to
  305.   the right.
  306.   
  307.   
  308.   panRight() <-- self
  309.   
  310.   Pans the display without changing the browse cursor (if
  311.   possible).  When the screen is panned with panRight, at least
  312.   one data column which was out of view to the right is brought
  313.   into view, while one or more columns are panned off screen to
  314.   the left.
  315.   
  316.   
  317.   right() <-- self
  318.   
  319.   Moves the browse cursor right one data column.  If the cursor
  320.   is already at the right edge, the display is panned and the
  321.   next data column (if there is one) is brought into view.
  322.   
  323.   
  324.   up() <-- self
  325.   
  326.   Moves the browse cursor up one row.  If the cursor is already
  327.   on the top data row, the display is scrolled and a new row is
  328.   brought into view.  If the data source is already at logical
  329.   beginning-of-file and the browse cursor is already on the top
  330.   data row, hitTop is set true (.T.).
  331.  
  332.  
  333. o Miscellaneous Methods
  334.  
  335.   addColumn(<objColumn>) <-- method>
  336.   
  337.   Adds a new column to the browse.  The parameter is a TBColumn
  338.   object.  The column count of the TBrowse object is increased by
  339.   one.
  340.   
  341.   
  342.   configure() <-- self
  343.   
  344.   Causes the TBrowse object to reexamine all instance variables
  345.   and TBColumn objects, and reconfigure its internal settings as
  346.   required.  This message can be used to force re-configuration
  347.   when a TBColumn object is modified directly.
  348.   
  349.   
  350.   getColumn(<nColumn>) <-- method>
  351.   
  352.   Returns the TBColumn object specified by nColumn.
  353.   
  354.   
  355.   refreshAll() <-- self
  356.   
  357.   Internally marks all data rows as invalid, causing them to be
  358.   refilled and redisplayed during the next stabilize loop.
  359.   
  360.   
  361.   refreshCurrent() <-- self
  362.   
  363.   Internally marks the current data row as invalid, causing it to
  364.   be refilled and redisplayed during the next stabilize loop.
  365.   
  366.   
  367.   setColumn(<nColumn>, <objColumn>) <-- objColumn
  368.   
  369.   Replaces the TBColumn object indicated by nColumn with the
  370.   TBColumn object specified by objColumn.
  371.   
  372.   
  373.   stabilize() <-- lStable
  374.   
  375.   Performs incremental stabilization.  Each time this message is
  376.   sent, some part of the stabilization process is performed. 
  377.   Stabilization is performed in increments so that it can be
  378.   interrupted by a keystroke or other asynchronous event.
  379.   
  380.   If the TBrowse object is already stable, a value of true (.T.)
  381.   is returned; otherwise a value of false (.F.) is returned,
  382.   indicating that further stabilize messages should be sent.  The
  383.   browse is considered stable when all data has been retrieved
  384.   and displayed, the data source has been repositioned to the
  385.   record corresponding to the browse cursor, and the current cell
  386.   has been highlighted.
  387.  
  388.  
  389.  
  390. o The TBrowseNew() function
  391.  
  392.   TBrowseNew(<nTop>, <nLeft>, <nBottom>, <nRight>) <-- objTBrowse
  393.  
  394.   Returns a new TBrowse object with the specified coordinate
  395.   settings.  The TBrowse object is created with no columns and no
  396.   code blocks for data source positioning.  These must be
  397.   provided before the TBrowse can be used.
  398.  
  399.  
  400.  
  401. o The TBrowseDB() function
  402.  
  403.   TBrowseDB(<nTop>, <nLeft>, <nBottom>, <nRight>) <-- objTBrowse
  404.  
  405.   Returns a new TBrowse object with the specified coordinate
  406.   settings and default code blocks for data source positioning. 
  407.   The default code blocks execute GO TOP, Go BOTTOM, and SKIP
  408.   commands for data source positioning.
  409.  
  410.   The TBrowse object is created with no columns.  These must be
  411.   provided before the TBrowse can be used.
  412.  
  413.  
  414.  
  415. o TBColumn Objects
  416.  
  417.   A TBColumn object is a simple object containing the information
  418.   needed to fully define one data column of a TBrowse object (see
  419.   the section on the TBrowse class).  TBColumn objects have no
  420.   methods, only exported instance variables.
  421.  
  422.  
  423. o Exported Instance Variables
  424.  
  425.   block   (Assignable)
  426.   
  427.   Contains a code block that is used to retrieve data for the
  428.   column.  Any code block is valid, and no block parameters are
  429.   supplied when the block is executed.  The code block must
  430.   return the appropriate data value for the column.
  431.   
  432.   
  433.   cargo   (Assignable)
  434.   
  435.   Contains a numeric value.  This instance variable is a
  436.   user-definable slot, allowing arbitrary information to be
  437.   attached to a TBColumn and retrieved later.
  438.   
  439.   
  440.   colorBlock (Assignable)
  441.   
  442.   An optional code block that determines the color of data items
  443.   as they are displayed.  If present, this block is executed each
  444.   time a new value is retrieved via the data retrieval block. 
  445.   The newly retrieved data value is passed as a parameter to the
  446.   colorBlock, which must return an array containing two numeric
  447.   values.  The values returned are used as indexes into the color
  448.   table of the TBrowse object as described below for defColor.
  449.   
  450.   The colorBlock allows display colors for data items to be based
  451.   on the value of the data being displayed.
  452.   
  453.   colSep  (Assignable)
  454.   
  455.   
  456.   An optional character string used to draw a vertical separator
  457.   to the left of this data column (if this data column is
  458.   displayed with another column to the left of it).  If no value
  459.   is supplied for colSep, the column separator specified in the
  460.   TBrowse object is used.
  461.   
  462.   
  463.   defColor   (Assignable)
  464.   
  465.   An array containing two numeric values.  The values are used as
  466.   indexes into the color table in the TBrowse object.  The first
  467.   value determines the unselected color.  The unselected color is
  468.   used to display headings, footings, etc.  It is also used to
  469.   display data values when the browse cursor is not on the data
  470.   value being displayed.  The second value determines the
  471.   selected color.  The selected color is used to display data
  472.   values when the browse cursor is positioned to the data item
  473.   being displayed.  The default value for defColor is {1, 2}. 
  474.   This causes the first two colors in the TBrowse color table to
  475.   be used for unselected and selected, respectively.  Note that
  476.   colors set using the colorBlock instance variable override
  477.   those set by defColor.
  478.   
  479.   
  480.   footing (Assignable)
  481.   
  482.   Contains a character value that defines the footer for this
  483.   data column.
  484.   
  485.   
  486.   footSep (Assignable)
  487.   
  488.   Contains a character value used to draw a horizontal line
  489.   between the data values and the footer.
  490.   
  491.   
  492.   heading (Assignable)
  493.   
  494.   Contains a character value that defines the header for this
  495.   data column.
  496.   
  497.   
  498.   headSep (Assignable)
  499.   
  500.   An optional character string used to draw a horizontal
  501.   separator between the header and the data values.  If no value
  502.   is supplied, the heading separator specified in the TBrowse
  503.   object is used.
  504.   
  505.   
  506.   width   (Assignable)
  507.   
  508.   Contains a numeric value that defines the display width for the
  509.   column.  If not assigned, the width is determined by examining
  510.   a data value returned by the data retrieval block.
  511.  
  512.  
  513.  
  514. o The TBColumnNew() function
  515.  
  516.   TBColumnNew(<cHeading>, <bBlock>) <-- objTBColumn
  517.   
  518.   Returns a new TBColumn object with the specified heading and
  519.   data retrieval block.  Other elements of the TBColumn object
  520.   can be assigned directly using the syntax for assigning
  521.   exported instance variables.
  522.  
  523.  
  524.  
  525. o Examples
  526.  
  527.   For examples of TBrowse and TBColumn, refer to the file
  528.   TBDEMO.PRG in the SOURCE directory.
  529.  
  530.