472 lines
16 KiB
Plaintext
472 lines
16 KiB
Plaintext
/*
|
|
* $Id$
|
|
*/
|
|
|
|
/*
|
|
* The following parts are Copyright of the individual authors.
|
|
* www - http://www.harbour-project.org
|
|
*
|
|
* Copyright 2000 Brian Hays <bhays@abacuslaw.com>
|
|
* Documentation for the commands
|
|
*
|
|
* See doc/license.txt for licensing terms.
|
|
*
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $COMMANDNAME$
|
|
* CLASS
|
|
* $CATEGORY$
|
|
* OOP Command
|
|
* $ONELINER$
|
|
* Define a Class for Object Oriented Programming
|
|
* $SYNTAX$
|
|
* [CREATE] CLASS <ClassName> [ <FROM, INHERIT> <SuperClass1> [,<SuperClassN>] ] [STATIC]
|
|
* $ARGUMENTS$
|
|
* <ClassName> Name of the class to define. By tradition, Harbour
|
|
* classes start with "T" to avoid collisions with user-
|
|
* created classes.
|
|
*
|
|
* <SuperClass1...n> The Parent class(es) to use for inheritance.
|
|
* Harbour supports Multiple Inheritance.
|
|
*
|
|
* STATIC This clause causes the class function to be declared
|
|
* as a static function. It will therefore not be available outside the current module.
|
|
*
|
|
* $DESCRIPTION$
|
|
* CLASS creates a class from which you can create objects.
|
|
* The CLASS command begins the class specification, in which the DATA
|
|
* elements (also known as instance variables) and METHODS of the
|
|
* class are named. The following scoping commands may also appear.
|
|
* They control the default scope of DATA and METHOD commands that follow them.
|
|
*
|
|
* <fixed>
|
|
* EXPORTED:
|
|
* VISIBLE:
|
|
* HIDDEN:
|
|
* PROTECTED:
|
|
* </fixed>
|
|
* The class specification ends with the END CLASS command.
|
|
*
|
|
* Classes can inherit from multiple <SuperClasses>, and the chain of
|
|
* inheritance can extend to many levels.
|
|
*
|
|
* A program uses a Class by calling the Class Constructor, usually the
|
|
* New() method, to create an object. That object is usually assigned
|
|
* to a variable, which is used to access the DATA elements and
|
|
* methods.
|
|
*
|
|
* Harbour's OOP syntax and implementation supports Scoping (Protect, Hidden and Readonly)
|
|
* and Delegating, and is largely compatible with Class(y)(tm), TopClass(tm)
|
|
* and Visual Objects(tm).
|
|
* $EXAMPLES$
|
|
<fixed>
|
|
* CLASS TBColumn
|
|
*
|
|
* DATA Block // Code block to retrieve data for the column
|
|
* DATA Cargo // User-definable variable
|
|
* DATA ColorBlock // Code block that determines color of data items
|
|
* DATA ColSep // Column separator character
|
|
* DATA DefColor // Array of numeric indexes into the color table
|
|
* DATA Footing // Column footing
|
|
* DATA FootSep // Footing separator character
|
|
* DATA Heading // Column heading
|
|
* DATA HeadSep // Heading separator character
|
|
* DATA Width // Column display width
|
|
* DATA ColPos // Temporary column position on screen
|
|
*
|
|
* METHOD New() // Constructor
|
|
*
|
|
* ENDCLASS
|
|
</fixed>
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* CLASS is a Harbour extension.
|
|
* $PLATFORMS$
|
|
* All
|
|
* $SEEALSO$
|
|
* TClass(),Object Oriented Programming,DATA,METHOD
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $COMMANDNAME$
|
|
* DATA
|
|
* $CATEGORY$
|
|
* OOP Command
|
|
* $ONELINER$
|
|
* Alternate syntax for VAR: instance variable for the objects.
|
|
* $SYNTAX$
|
|
* DATA <DataName1> [,<DataNameN>] [ AS <type> ] [ INIT <uValue> ]
|
|
* [[EXPORTED | VISIBLE] | [PROTECTED] | [HIDDEN]] [READONLY | RO]
|
|
* $ARGUMENTS$
|
|
* <DataName1> Name of the DATA
|
|
|
|
* <type> Optional data type specification from the following:
|
|
* Character, Numeric, Date, Logical, Codeblock, Nil.
|
|
|
|
* <uValue> Optional initial value when creating a new object.
|
|
*
|
|
* EXPORTED Specifies that this DATA is accessible to functions and
|
|
* methods outside of the class. VISIBLE is a synonym for EXPORTED.
|
|
*
|
|
* PROTECTED Specifies that this DATA is only accessible to functions and methods within this class and its subclasses.
|
|
*
|
|
* HIDDEN Specifies that this DATA is only accessible to the
|
|
* class where it was defined, and is not inherited by the
|
|
* subclasses.
|
|
|
|
* READONLY Restricts assignment to the variable. If specified with
|
|
* the EXPORTED clause, assignment is only permitted from the current
|
|
* class and its subclasses. If specified with the PROTECTED clause,
|
|
* assignment is only permitted from the current class.
|
|
* RO is a synonym for READONLY.
|
|
|
|
* $DESCRIPTION$
|
|
* DATA elements can also be thought of as the "properties" of an
|
|
* object. They can be of any data type, including codeblock.
|
|
* Once an object has been created, the DATA elements are referenced
|
|
* with the colon (:) as in MyObject:Heading := "Last name".
|
|
* Usually a class also defines methods to manipulate the DATA.
|
|
*
|
|
* You can use the "AS <type>" clause to enforce that the DATA is
|
|
* maintained as a certain type. Otherwise it will take on the type of
|
|
* whatever value is first assigned to it.
|
|
*
|
|
* Use the "INIT <uValue>" clause to initialize that DATA to <uValue>
|
|
* whenever a new object is created.
|
|
*
|
|
* VAR can be a synonym for DATA, or it can use a slightly different
|
|
* syntax for compatibility with other dialects.
|
|
|
|
* $EXAMPLES$
|
|
<fixed>
|
|
* CLASS TBColumn
|
|
*
|
|
* DATA Block // Code block to retrieve data for the column
|
|
* DATA Cargo // User-definable variable
|
|
* DATA ColorBlock // Code block that determines color of data items
|
|
* DATA ColSep // Column separator character
|
|
* DATA DefColor // Array of numeric indexes into the color table
|
|
* DATA Footing // Column footing
|
|
* DATA FootSep // Footing separator character
|
|
* DATA Heading // Column heading
|
|
* DATA HeadSep // Heading separator character
|
|
* DATA Width // Column display width
|
|
* DATA ColPos // Temporary column position on screen
|
|
*
|
|
* METHOD New() // Constructor
|
|
*
|
|
* ENDCLASS
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* DATA is a Harbour extension.
|
|
* $PLATFORMS$
|
|
* All
|
|
* $SEEALSO$
|
|
* Object Oriented Programming,CLASS,METHOD,CLASSDATA,VAR
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $COMMANDNAME$
|
|
* CLASSDATA
|
|
* $CATEGORY$
|
|
* OOP Command
|
|
* $ONELINER$
|
|
* Define a CLASSDATA variable for a class (NOT for an Object!)
|
|
* $SYNTAX$
|
|
* CLASSDATA <DataName1> [,<DataNameN>] [ AS <type> ] [ INIT <uValue> ]
|
|
* $ARGUMENTS$
|
|
* <DataName1> Name of the DATA
|
|
|
|
* <type> Optional data type specification from the following:
|
|
* Character, Numeric, Date, Logical, Codeblock, Nil
|
|
|
|
* <uValue> Optional initial value at program startup
|
|
* $DESCRIPTION$
|
|
* CLASSDATA variables can also be thought of as the "properties" of an
|
|
* entire class. Each CLASSDATA exists only once, no matter how many
|
|
* objects are created. A common usage is for a counter that is
|
|
* incremented whenever an object is created and decremented when one
|
|
* is destroyed, thus monitoring the number of objects in existance
|
|
* for this class.
|
|
*
|
|
* You can use the "AS <type>" clause to enforce that the CLASSDATA is
|
|
* maintained as a certain type. Otherwise it will take on the type of
|
|
* whatever value is first assigned to it.
|
|
* Use the "INIT <uValue>" clause to initialize that DATA to <uValue>
|
|
* whenever the class is first used.
|
|
* $EXAMPLES$
|
|
<fixed>
|
|
* CLASS TWindow
|
|
* DATA hWnd, nOldProc
|
|
* CLASSDATA lRegistered AS LOGICAL
|
|
* ENDCLASS
|
|
</fixed>
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* CLASSDATA is a Harbour extension.
|
|
* $PLATFORMS$
|
|
* All
|
|
* $SEEALSO$
|
|
* Object Oriented Programming,CLASS,METHOD,DATA
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $COMMANDNAME$
|
|
* METHOD
|
|
* $CATEGORY$
|
|
* OOP Command
|
|
* $ONELINER$
|
|
* Declare a METHOD for a class in the class header
|
|
* $SYNTAX$
|
|
* METHOD <MethodName>( [<params,...>] ) [ CONSTRUCTOR ]
|
|
* METHOD <MethodName>( [<params,...>] ) INLINE <Code,...>
|
|
* METHOD <MethodName>( [<params,...>] ) BLOCK <CodeBlock>
|
|
* METHOD <MethodName>( [<params,...>] ) EXTERN <FuncName>([<args,...>])
|
|
* METHOD <MethodName>( [<params,...>] ) SETGET
|
|
* METHOD <MethodName>( [<params,...>] ) VIRTUAL
|
|
* METHOD <MethodName>( [<param>] ) OPERATOR <op>
|
|
* METHOD <MethodName>( [<params,...>] ) CLASS <ClassName>
|
|
* $ARGUMENTS$
|
|
* <MethodName> Name of the method to define
|
|
|
|
* <params,...> Optional parameter list
|
|
* $DESCRIPTION$
|
|
* Methods are "class functions" which do the work of the class.
|
|
* All methods must be defined in the class header between the
|
|
* CLASS and ENDCLASS commands. If the body of a method is not fully
|
|
* defined here, the full body is written below the ENDCLASS command
|
|
* using this syntax:
|
|
*
|
|
* METHOD <MethodName>( [<params,...>] ) CLASS <ClassName>
|
|
*
|
|
* Methods can reference the current object with the keyword "Self:" or
|
|
* its shorthand version "::".
|
|
*
|
|
* CLAUSES:
|
|
*
|
|
* CONSTRUCTOR Defines a special method Class Constructor method,
|
|
* used to create objects. This is usually the
|
|
* New() method. Constructors always return the new
|
|
* object.
|
|
*
|
|
* INLINE Fast and easy to code, INLINE lets you define the
|
|
* code for the method immediately within the definition
|
|
* of the Class. Any methods not declared INLINE or BLOCK
|
|
* must be fully defined after the ENDCLASS command.
|
|
* The <Code,...> following INLINE receives a parameter
|
|
* of Self. If you need to receive more parameters, use
|
|
* the BLOCK clause instead.
|
|
*
|
|
* BLOCK Use this clause when you want to declare fast 'inline'
|
|
* methods that need parameters. The first parameter to
|
|
* <CodeBlock> must be Self, as in:
|
|
*
|
|
* METHOD <MethodName> BLOCK {|Self,<arg1>,<arg2>, ...,<argN>|...}
|
|
*
|
|
* EXTERN If an external function does what the method needs,
|
|
* use this clause to make an optimized call to that
|
|
* function directly.
|
|
*
|
|
* SETGET For calculated Data. The name of the method can be
|
|
* manipulated like a Data element to Set or Get a value.
|
|
*
|
|
* VIRTUAL Methods that do nothing. Useful for Base classes where
|
|
* the child class will define the method's behavior, or
|
|
* when you are first creating and testing a Class.
|
|
*
|
|
* OPERATOR Operator Overloading for classes.
|
|
* See example Tests/TestOp.prg for details.
|
|
*
|
|
* CLASS <ClassName>
|
|
* Use this syntax only for defining a full method after
|
|
* the ENDCLASS command.
|
|
* $EXAMPLES$
|
|
<fixed>
|
|
* CLASS TWindow
|
|
* DATA hWnd, nOldProc
|
|
* METHOD New( ) CONSTRUCTOR
|
|
* METHOD Capture() INLINE SetCapture( ::hWnd )
|
|
* METHOD End() BLOCK { | Self, lEnd | If( lEnd := ::lValid(),;
|
|
* ::PostMsg( WM_CLOSE ),), lEnd }
|
|
* METHOD EraseBkGnd( hDC )
|
|
* METHOD cTitle( cNewTitle ) SETGET
|
|
* METHOD Close() VIRTUAL
|
|
* ENDCLASS
|
|
*
|
|
* METHOD New( ) CLASS TWindow
|
|
* local nVar, cStr
|
|
* ... <code> ...
|
|
* ... <code> ...
|
|
* RETURN Self
|
|
</fixed>
|
|
* $TESTS$
|
|
<fixed>
|
|
* TestOp.prg
|
|
</fixed>
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* METHOD is a Harbour extension.
|
|
* $PLATFORMS$
|
|
* All
|
|
* $SEEALSO$
|
|
* TClass(),Object Oriented Programming,DATA,CLASS
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $COMMANDNAME$
|
|
* MESSAGE
|
|
* $CATEGORY$
|
|
* OOP Command
|
|
* $ONELINER$
|
|
* Route a method call to another Method
|
|
* $SYNTAX$
|
|
* MESSAGE <MessageName> METHOD <MethodName>( [<params,...>] )
|
|
* MESSAGE <MessageName>() METHOD <MethodName>( [<params,...>] )
|
|
* $ARGUMENTS$
|
|
* <MessageName> The pseudo-method name to define
|
|
|
|
* <MethodName> The method to create and call when <MessageName>
|
|
* is invoked.
|
|
|
|
* <params,...> Optional parameter list for the method
|
|
* $DESCRIPTION$
|
|
* The MESSAGE command is a seldom-used feature that lets you re-route
|
|
* a call to a method with a different name. This can be necessary if
|
|
* a method name conflicts with a public function that needs to be
|
|
* called from within the class methods.
|
|
*
|
|
* For example, your app may have a public function called BeginPaint()
|
|
* that is used in painting windows. It would also be natural to have a
|
|
* Window class method called :BeginPaint() that the application can
|
|
* call. But within the class method you would not be able to call the
|
|
* public function because internally methods are based on static
|
|
* functions (which hide public functions of the same name).
|
|
*
|
|
* The MESSAGE command lets you create the true method with a different
|
|
* name (::xBeginPaint()), yet still allow the ::BeginPaint() syntax
|
|
* to call ::xBeginPaint(). This is then free to call the public
|
|
* function BeginPaint().
|
|
* $EXAMPLES$
|
|
<fixed>
|
|
* CLASS TWindow
|
|
* DATA hWnd, nOldProc
|
|
* METHOD New( ) CONSTRUCTOR
|
|
* MESSAGE BeginPaint METHOD xBeginPaint()
|
|
* ENDCLASS
|
|
</fixed>
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* MESSAGE is a Harbour extension.
|
|
* $PLATFORMS$
|
|
* All
|
|
* $SEEALSO$
|
|
* METHOD,DATA,CLASS,Object Oriented Programming
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $COMMANDNAME$
|
|
* ERROR HANDLER
|
|
* $CATEGORY$
|
|
* OOP Command
|
|
* $ONELINER$
|
|
* Designate a method as an error handler for the class
|
|
* $SYNTAX$
|
|
* ERROR HANDLER <MethodName>( [<params,...>] )
|
|
* $ARGUMENTS$
|
|
* <MethodName> Name of the method to define
|
|
|
|
* <params,...> Optional parameter list
|
|
* $DESCRIPTION$
|
|
* ERROR HANDLER names the method that should handle errors for the
|
|
* class being defined.
|
|
* $EXAMPLES$
|
|
<fixed>
|
|
* CLASS TWindow
|
|
* ERROR HANDLER MyErrHandler()
|
|
* ENDCLASS
|
|
</fixed>
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* ERROR HANDLER is a Harbour extension.
|
|
* $PLATFORMS$
|
|
* All
|
|
* $SEEALSO$
|
|
* Object Oriented Programming,ON ERROR,CLASS,METHOD,DATA
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $COMMANDNAME$
|
|
* ON ERROR
|
|
* $CATEGORY$
|
|
* OOP Command
|
|
* $ONELINER$
|
|
* Designate a method as an error handler for the class
|
|
* $SYNTAX$
|
|
* ON ERROR <MethodName>( [<params,...>] )
|
|
* $ARGUMENTS$
|
|
* <MethodName> Name of the method to define
|
|
|
|
* <params,...> Optional parameter list
|
|
* $DESCRIPTION$
|
|
* ON ERROR is a synonym for ERROR HANDLER.
|
|
* It names the method that should handle errors for the
|
|
* class being defined.
|
|
* $EXAMPLES$
|
|
<fixed>
|
|
* CLASS TWindow
|
|
* ON ERROR MyErrHandler()
|
|
* ENDCLASS
|
|
</fixed>
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* ON ERROR is a Harbour extension.
|
|
* $PLATFORMS$
|
|
* All
|
|
* $SEEALSO$
|
|
* Object Oriented Programming,ERROR HANDLER,CLASS,METHOD,DATA
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $COMMANDNAME$
|
|
* ENDCLASS
|
|
* $CATEGORY$
|
|
* OOP Command
|
|
* $ONELINER$
|
|
* End the declaration of a class.
|
|
* $SYNTAX$
|
|
* ENDCLASS
|
|
* $DESCRIPTION$
|
|
* ENDCLASS marks the end of a class declaration.
|
|
* It is usually followed by the class methods that are not INLINE.
|
|
* $EXAMPLES$
|
|
<fixed>
|
|
* CLASS TWindow
|
|
* DATA hWnd, nOldProc
|
|
* ENDCLASS
|
|
</fixed>
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* ON ERROR is a Harbour extension.
|
|
* $PLATFORMS$
|
|
* All
|
|
* $SEEALSO$
|
|
* Object Oriented Programming,CLASS,METHOD,DATA
|
|
* $END$
|
|
*/
|