home *** CD-ROM | disk | FTP | other *** search
/ Piper's Pit BBS/FTP: ibm 0010 - 0019 / ibm0010-0019 / ibm0010.tar / ibm0010 / CLIPB51.ZIP / C5P78.EXE / GET.DOC < prev    next >
Encoding:
Text File  |  1990-05-31  |  12.6 KB  |  403 lines
  1. Notes on the predefined Get object class.
  2.  
  3. Note:  this information supersedes the information in the
  4. pre-release documentation.
  5.  
  6.  
  7. o Get Objects
  8.  
  9.   Note:  for a general discussion of Clipper 5.0 predefined
  10.   objects, refer to the "Basic Concepts" chapter of the
  11.   documentation.
  12.   
  13.   A Get object is a general purpose mechanism for editing data. 
  14.   It is used in Clipper 5.0 to implement the @...GET and READ
  15.   commands.  Get objects provide a sophisticated architecture for
  16.   formatting and editing data, including cursor navigation and
  17.   data validation.  Data validation is performed via
  18.   user-supplied code blocks, and display formatting can be
  19.   controlled using standard picture strings.
  20.  
  21.   Normally, a Get object is associated with a particular variable
  22.   (referred to below as the "Get variable").  The Get object does
  23.   not directly access this variable; instead, the variable is
  24.   manipulated by evaluating a supplied code block.  When a Get
  25.   object is created using the standard @..GET commands, a code
  26.   block is automatically created which provides access to the
  27.   variable named in the command.  For Gets created with the
  28.   GetNew() function, an appropriate code block must be supplied.
  29.  
  30.   A Get evaluates the supplied code block to retrieve the value
  31.   of the Get variable.  The value is converted to displayable
  32.   form and copied into a buffer (the "editing buffer") that is
  33.   displayed on the screen for editing.  Programmable behaviors
  34.   allow the navigation of the editing buffer and subsequent
  35.   copying of its contents back to the Get variable.
  36.  
  37.  
  38. o Exported Instance Variables
  39.  
  40.   badDate
  41.   
  42.   Contains a logical value.  The value is true (.T.) if the Get
  43.   is a date type and the date represented by the contents of the
  44.   editing buffer is invalid.  If the date is valid or if the Get
  45.   is not editing a date value, badDate is false (.F.).
  46.   
  47.   
  48.   block   (Assignable)
  49.   
  50.   Contains a code block that is used to associate the Get object
  51.   with a variable.  The block must take an optional parameter. 
  52.   When the parameter is supplied, the block must assign the
  53.   parameter value to the variable.  Otherwise, the current value
  54.   of the variable is returned.
  55.   
  56.   
  57.   buffer  (Assignable)
  58.   
  59.   Contains a character value that defines the editing buffer used
  60.   by the Get object.  This variable is meaningful only while the
  61.   Get object has input focus.  At other times, its value is NIL
  62.   and attempts to assign a new value are ignored.
  63.   
  64.   
  65.   cargo   (Assignable)
  66.   
  67.   Contains a value of any data type.  This instance variable is
  68.   unused by the Get object.  It is provided as a user-definable
  69.   slot, allowing arbitrary information to attached to a Get
  70.   object and retrieved later.
  71.   
  72.   
  73.   col  (Assignable)
  74.   
  75.   Contains a numeric value that defines the screen column where
  76.   the Get will be displayed.
  77.   
  78.   
  79.   colorSpec  (Assignable)
  80.   
  81.   Contains a character string that defines the display attributes
  82.   for the Get object.  The string must contain two color
  83.   specifiers.  The first, called the unselected color, determines
  84.   the color of the Get object when it does not have input focus. 
  85.   The second, called the selected color, determines the color of
  86.   the Get when it does have input focus.
  87.   
  88.   If no colors are specified for a Get, the colors are
  89.   initialized using the current SETCOLOR() colors.  The
  90.   SETCOLOR() unselected and enhanced colors are used as the Get
  91.   object's unselected and selected colors, respectively.  See
  92.   SETCOLOR() in the Standard Functions chapter of this book for
  93.   more information on color specifiers.
  94.   
  95.   
  96.   decPos
  97.   
  98.   Contains a numeric value that indicates the decimal point
  99.   position within the editing buffer.  This variable is
  100.   meaningful only when the value being edited is numeric and the
  101.   Get has input focus.  At other times, its value is NIL.
  102.   
  103.   
  104.   hasFocus
  105.   
  106.   A logical value.  The value is true (.T.) if the Get object has
  107.   input focus; otherwise false (.F.).
  108.   
  109.   
  110.   name (Assignable)
  111.   
  112.   Contains an optional character string representing the name of
  113.   the Get variable.  For Get objects created using the standard
  114.   @..GET commands, the name is present.
  115.   
  116.   The Get object itself ignores this variable; it is used by the
  117.   standard READ command to implement the READVAR() function (see
  118.   READVAR() in the Standard Functions chapter of this book).
  119.   
  120.   
  121.   original
  122.   
  123.   Contains a value of any data type.  This instance variable
  124.   contains a copy of the value that was in the Get variable at
  125.   the time the Get object acquired input focus.  This copy is
  126.   used to implement the undo message.  The value is meaningful
  127.   only while the Get has input focus.  At other times, its value
  128.   is NIL.
  129.   
  130.   
  131.   picture (Assignable)
  132.   
  133.   Contains a character value that defines the PICTURE string used
  134.   to control formatting and editing for the Get object.  See the
  135.   @...GET entry in the Standard Commands chapter for more
  136.   information on PICTURE strings.
  137.   
  138.   
  139.   pos
  140.   
  141.   Contains a numeric value indicating the position of the cursor
  142.   within the editing buffer.  This variable is meaningful only
  143.   while the Get object has input focus.  At other times, its
  144.   value is NIL.
  145.  
  146.   
  147.   postBlock  (Assignable)
  148.   
  149.   Contains an optional code block that can be used to validate a
  150.   newly entered value.  If present, the postBlock should contain
  151.   an expression that evaluates to true (.T.) for a legal value;
  152.   otherwise false (.F.).  For Get objects created with the
  153.   standard @..GET..VALID command, postBlock is present and
  154.   contains the expression specified in the VALID clause.
  155.   
  156.   The Get object itself ignores this variable; it is used by the
  157.   standard READ command to implement the VALID clause.  In the
  158.   standard READ command, a parameter is supplied to the postBlock
  159.   when it is evaluated: the value of the Get variable after any
  160.   editing.  The parameter allows the postBlock to validate the
  161.   value without directly referring to the Get variable.
  162.   
  163.   
  164.   preBlock   (Assignable)
  165.   
  166.   Contains an optional code block that can be used to decide
  167.   whether or not editing should be permitted.  If present, the
  168.   preBlock should evaluate to true (.T.) if editing is to be
  169.   permitted; otherwise false (.F.).  For Get objects created with
  170.   the standard @..GET..WHEN command, preBlock is present and
  171.   contains the expression specified in the WHEN clause.
  172.   
  173.   The Get object itself ignores this variable; it is used by the
  174.   standard READ command to implement the WHEN clause.  
  175.   
  176.   
  177.   rejected
  178.   
  179.   Contains a logical value.  The value is true (.T.) if the last
  180.   insert or overStrike message specified a character that was
  181.   rejected (not placed in the editing buffer).  Note that any
  182.   subsequent text entry message will reset this variable.
  183.   
  184.   
  185.   row  (Assignable)
  186.   
  187.   Contains a numeric value that defines the screen row where the
  188.   Get will display.
  189.   
  190.   
  191.   type
  192.   
  193.   Contains a single letter representing the data type of the Get
  194.   variable.  For information on type-letters, refer to VALTYPE()
  195.   in the Standard Functions chapter of this book.
  196.   
  197.   
  198.   typeOut
  199.   
  200.   Contains a logical value.  The value is true (.T.) if the most
  201.   recent message attempted to move the cursor out of the editing
  202.   buffer (or if there are no editable positions in the buffer). 
  203.   Note that this variable is reset by any message which moves the
  204.   cursor.
  205.  
  206.  
  207.  
  208. o State Change Methods
  209.  
  210.   assign() <-- self
  211.   
  212.   Assigns the value in the editing buffer to the Get variable by
  213.   evaluating the associated code block with the new value as a
  214.   parameter.  This message is meaningful only while the Get has
  215.   input focus.
  216.   
  217.   
  218.   display() <-- self
  219.   
  220.   Displays the Get on the screen.  If the Get has input focus, it
  221.   is displayed in its selected color and the hardware cursor is
  222.   placed at the screen location corresponding to the current
  223.   editing position within the editing buffer.  If the Get does
  224.   not have input focus, it is displayed in its unselected color
  225.   with no cursor.
  226.   
  227.   
  228.   killFocus() <-- self
  229.   
  230.   Takes input focus away from the Get object.  Upon receiving
  231.   this message, the Get object redisplays its editing buffer and
  232.   discards its internal state information.
  233.   
  234.   
  235.   reset() <-- self
  236.   
  237.   Resets the Get object's internal state information.  This
  238.   includes resetting the editing buffer to reflect the current
  239.   value of the Get variable, and setting the cursor position to
  240.   the first editable position within the buffer.  This message
  241.   has meaning only while the Get object has input focus.
  242.   
  243.   
  244.   setFocus() <-- self
  245.   
  246.   Gives input focus to the Get object.  Upon receiving this
  247.   message, the Get object creates and initializes its internal
  248.   state information, including the exported instance variables
  249.   buffer, pos, decPos, and original.  The contents of the editing
  250.   buffer are then displayed in the Get's selected color.
  251.   
  252.   
  253.   undo() <-- self
  254.   
  255.   Sets the Get variable back to the value it had when the Get
  256.   acquired input focus.  This message has meaning only while the
  257.   GET has input focus.
  258.   
  259.   The effect of the undo message is equivalent to assigning the
  260.   Get variable from the saved value in the "original" instance
  261.   variable, and then sending the reset message.
  262.   
  263.   
  264.   updateBuffer() <-- self
  265.   
  266.   Sets the editing buffer to reflect the current value of the Get
  267.   variable, and redisplays the Get.  This message has meaning
  268.   only while the Get has input focus.
  269.  
  270.  
  271.  
  272. o Cursor Movement Methods
  273.  
  274.   end() <-- self
  275.   
  276.   Moves the cursor to the rightmost editable position within the
  277.   editing buffer.
  278.   
  279.   
  280.   home() <-- self
  281.   
  282.   Moves the cursor to the leftmost editable position within the
  283.   editing buffer.
  284.   
  285.   
  286.   left() <-- self
  287.   
  288.   Moves the cursor left to the nearest editable position within
  289.   the editing buffer.  If there is no editable position to the
  290.   left, the cursor position is left unchanged.
  291.   
  292.   
  293.   right() <-- self
  294.   
  295.   Moves the cursor right to the nearest editable position within
  296.   the editing buffer.  If there is no editable position to the
  297.   right, the cursor position is left unchanged.
  298.   
  299.   
  300.   toDecPos() <-- self
  301.   
  302.   Moves the cursor to the immediate right of the decimal point
  303.   position in the editing buffer.  This message is only
  304.   meaningful when editing numeric values.
  305.   
  306.   
  307.   wordLeft() <-- self
  308.   
  309.   Moves the cursor one word to the left within the editing
  310.   buffer.  If the cursor is already at the leftmost editable
  311.   position, it is left unchanged.
  312.   
  313.   
  314.   wordRight() <-- self
  315.   
  316.   Moves the cursor one word to the right within the Get buffer. 
  317.   If the cursor is already at the rightmost editable position, it
  318.   is left unchanged.
  319.  
  320.  
  321.  
  322. o Editing Methods
  323.  
  324.   backspace() <-- self
  325.   
  326.   Deletes the character to the left of the cursor, and moves the
  327.   cursor one position to the left.  If the cursor is already at
  328.   the leftmost editable position in the editing buffer, the
  329.   message has no effect.
  330.   
  331.   
  332.   delLeft() <-- self
  333.   
  334.   Deletes the character to the left of the cursor.
  335.   
  336.   
  337.   delRight() <-- self
  338.   
  339.   Deletes the character to the right of the cursor.
  340.   
  341.   
  342.   delWordLeft() <-- self
  343.   
  344.   Deletes the word to the left of the cursor.
  345.   
  346.   
  347.   delWordRight() <-- self
  348.   
  349.   Deletes the word to the right of the cursor.
  350.  
  351.  
  352.  
  353. o Text Entry Methods
  354.  
  355.   insert(<cChar>) <-- self
  356.   
  357.   Inserts <cChar> into the editing buffer at the current cursor
  358.   position, shifting the existing contents of the buffer to the
  359.   right.  The cursor is placed one position to the right of the
  360.   inserted string.
  361.   
  362.   
  363.   overStrike(<cChar>) <-- self
  364.   
  365.   Puts <cChar> into the editing buffer at the current cursor
  366.   position, overwriting the existing contents of the buffer.  The
  367.   cursor is placed one position to the right of the inserted
  368.   string.
  369.  
  370.  
  371.  
  372. o The GetNew() function
  373.  
  374.   The GetNew() function is used to create a new Get object.  The
  375.   syntax is show below:
  376.  
  377.   GetNew(<nRow>, <nCol>, <bBlock>, [<cPicture>], [<cColorSpec>])
  378.   
  379.   Returns a new Get object with the row, col, block, picture, and
  380.   colorSpec instance variables set from the supplied arguments.
  381.  
  382.  
  383.  
  384. o The ReadModal() function
  385.  
  386.   ReadModal() performs the standard Clipper 5.0 READ command.  It
  387.   takes a single parameter which is an array of Get objects:
  388.   
  389.   ReadModal(aGetList)
  390.   
  391.   The standard READ command is preprocessed into a call to
  392.   ReadModal() with the current (or system) get list as the
  393.   parameter.  The source code for ReadModal() can be found in
  394.   GETSYS.PRG in the SOURCE directory.
  395.   
  396.  
  397.  
  398. o Examples
  399.  
  400.   Refer to the files GETSYS.PRG and TBDEMO.PRG in the SOURCE
  401.   directory.
  402.  
  403.