METHOD ... SETGET              Define a SetGet Method
------------------------------------------------------------------------------


 SYNTAX:

    [<preScope>] METHOD <cUdf>[(param)] [<postScope>] SETGET

    METHOD <cUdf>[(param)]:SETGET



 PARAMETER:

  <Scope>      Specifies the visibility of the SetGet method. 
               Please press  Related Topics:  and select  METHOD  for
               more detailed informations about method scopes


  <cUdf>       Is the actual name of the SetGet method, optionally with a
               parameter declaration. A method of this name must be defined
               in the same module ( .PRG ) as the class definition, using
               the METHOD <cUdf>( params ) command.



 DESCRIPTION:

  SetGet Methods are used to assign and retrieve data from variables or
  other Sources under the supervision of the controlling method.
  
  For every DATA/VAR that you declare, Clipper in fact defines two Messages:

      - one Message with the given <xVar> name to access the DATA,
      - and one Message <_xVar> with a leading underscore to assign a new
        value to the DATA.     

  Exactly this is accomplished by a SetGet method. If you define xyz as your
  SetGet Method, under the hood you create two new messages: one is xyz, and
  the other one is _xyz. This implies, that

            METHOD xyz SETGET  

            is the same as :

            MESSAGE xyz
            MESSAGE _xyz METHOD xyz


  With this knowledge it is possible to create a method that behaves exactly
  as if it was an Instance Variable :


    +--------------------------------------------------------------+
    |  /* Declare a SetGet Function */                             |
    |  CREATE CLASS dummy                                          |
    |    METHOD record SETGET                                      |
    |  ENDCLASS                                                    |
    |                                                              |
    |  /* Create the method */                                     |
    |  METHOD record( nRecNo )                                     |
    |    IF VALTYPE( nRecNo ) == "N"                               |
    |       DBGOTO( nRecNo )                                       |
    |    ENDIF                                                     |
    |  RETURN Recno()                                              |
    |                                                              |
    |  /* Now use o:Record like a variable: */                     |
    |  MsgInfo( oTb:record )  // invokes recno without parameter,  |
    |                         // calling recno()                   |
    |                                                              |
    |  oTb:record := 2        // invokes recno with nRec == 2,     |
    |                         // calling dbGoto( 2 )               |
    |                                                              |
    +--------------------------------------------------------------+


  You see that the SetGet Method RECORD() will now be invoked by the message
  RECNO with or without argument, depending on the assign/access operation.
  The advantages of using SetGet functions are obvious : 

  - To encapsulate variables with methods, that perform validations before
    assigning a value to the Var.    
       
  - You can access external functions just like a variable, launching certain
    actions to retrieve or assign a value. In our above example you can see
    that oTB:recno := 2 will in fact call clippers dbGoto() to move the
    record pointer. 

  - Have you ever been in the need to know if a variable has been changed ?
    No problem if you use a SetGet method, simply set a Flag if the Method
    is invoked with a new value.


  There are many, many situations where SETGET methods can be used. When you
  look at the benefits, you will understand that many OOP Programmers will
  allow manipulations of Instance Variables only by SetGet Methods !

   

 EXAMPLE:


    +--------------------------------------------------------------+
    |  /* SetGet the title of a window */                          |
    |  ...                                                         |
    |  VAR oWnd               // Window                            |
    |  METHOD cTitle:SETGET                                        |
    |  ...                                                         |
    |                                                              |
    |  METHOD cTitle( cStr )                                       |
    |      IF VALTYPE( cStr ) == "C"                               |
    |         SetWindowText( ::oWnd:hWnd, cStr )                   |
    |      ENDIF                                                   |
    |  RETURN GetWindowText( ::oWnd:hWnd )                         |
    |                                                              |
    |                                                              |
    |  /* Set a new Caption : */                                   |
    |  o:cTitle  := "New Title"                                    |
    |  ?? oWnd:Title         // -> "New Title"                     |
    |                                                              |
    +--------------------------------------------------------------+