diff --git a/harbour/doc/en/command.txt b/harbour/doc/en/command.txt index 6d00eaae49..f80a47485c 100644 --- a/harbour/doc/en/command.txt +++ b/harbour/doc/en/command.txt @@ -15,34 +15,51 @@ /* $DOC$ * $COMMANDNAME$ - * CLASS + * [CREATE] CLASS * $CATEGORY$ - * Oop Command + * OOP Command * $ONELINER$ * Define a Class for Object Oriented Programming * $SYNTAX$ - * CLASS [ ] + * [CREATE] CLASS [ [,] ] [STATIC] * $ARGUMENTS$ * Name of the class to define. By tradition, Harbour * classes start with "T" to avoid collisions with user- - * created classes. + * created classes. + * + * 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. * - * The Parent class to use for inheritance * $DESCRIPTION$ * CLASS creates a class from which you can create objects. - * Each Class is defined in a separate .PRG file dedicated to that - * purpose. You cannot create more than one class in a .PRG. - * After the CLASS command begins the definition, the DATA + * The CLASS command begins the class specification, in which the DATA * elements (also known as instance variables) and METHODS of the - * class are named. + * class are named. The following scoping commands may also appear. + * They control the default scope of DATA and METHOD commands that follow them. + + EXPORTED: + VISIBLE: + HIDDEN: + PROTECTED: + * - * Classes can inherit from a single , but the chain of - * inheritance can extend to many levels. + * The class specification ends with the END CLASS command. * - * A program uses a Class by calling the Class Constructor, the + * Classes can inherit from multiple , 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. + * 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$ * CLASS TBColumn @@ -66,9 +83,9 @@ * $STATUS$ * R * $COMPLIANCE$ - * CLASS is a Harbour extension. + * CLASS is a Harbour extension. * $PLATFORMS$ - * All + * All * $SEEALSO$ * TClass(),Object Oriented Programming,DATA,METHOD * $END$ @@ -78,42 +95,52 @@ * $COMMANDNAME$ * DATA * $CATEGORY$ - * Oop Command + * OOP Command * $ONELINER$ - * Define a DATA instance variable for the objects of a class + * Alternate syntax for VAR: instance variable for the objects. * $SYNTAX$ * DATA [,] [ AS ] [ INIT ] - * [ EXPORTED] [PROTECTED] [HIDDEN] [ READONLY] + * [[EXPORTED | VISIBLE] | [PROTECTED] | [HIDDEN]] [READONLY | RO] * $ARGUMENTS$ - * Name of the DATA + * Name of the DATA * Optional data type specification from the following: - * Character, Numeric, Date, Logical, Codeblock, Nil + * Character, Numeric, Date, Logical, Codeblock, Nil. - * Optional initial value when creating a new object + * Optional initial value when creating a new object. * - * EXPORTED This clause tell that this data is visible in where - * was defined and all subclasses. + * EXPORTED Specifies that this DATA is accessible to functions and + * methods outside of the class. VISIBLE is a synonym for EXPORTED. * - * PROTECTED This clause tell that the data is visible only where is - * defined + * PROTECTED Specifies that this DATA is only accessible to functions and methods within this class and its subclasses. * - * HIDDEN This clause say that the data is only visible on the - * class that was defined,and is not inherit by the + * 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. + * Usually a class also defines methods to manipulate the DATA. * * You can use the "AS " 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. + * whatever value is first assigned to it. * * Use the "INIT " clause to initialize that DATA to - * whenever a new object is created. + * 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$ * CLASS TBColumn @@ -136,11 +163,11 @@ * $STATUS$ * R * $COMPLIANCE$ - * DATA is a Harbour extension. + * DATA is a Harbour extension. * $PLATFORMS$ - * All + * All * $SEEALSO$ - * Object Oriented Programming,CLASS,METHOD,CLASSDATA + * Object Oriented Programming,CLASS,METHOD,CLASSDATA,VAR * $END$ */ @@ -148,18 +175,18 @@ * $COMMANDNAME$ * CLASSDATA * $CATEGORY$ - * Oop Command + * OOP Command * $ONELINER$ * Define a CLASSDATA variable for a class (NOT for an Object!) * $SYNTAX$ - * CLASSDATA [,] [ AS ] [ INIT ] + * CLASSDATA [,] [ AS ] [ INIT ] * $ARGUMENTS$ - * Name of the DATA + * Name of the DATA * Optional data type specification from the following: - * Character, Numeric, Date, Logical, Codeblock, Nil + * Character, Numeric, Date, Logical, Codeblock, Nil - * Optional initial value at program startup + * 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 @@ -170,9 +197,9 @@ * * You can use the "AS " 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. + * whatever value is first assigned to it. * Use the "INIT " clause to initialize that DATA to - * whenever the class is first used. + * whenever the class is first used. * $EXAMPLES$ * CLASS TWindow @@ -183,9 +210,9 @@ * $STATUS$ * R * $COMPLIANCE$ - * CLASSDATA is a Harbour extension. + * CLASSDATA is a Harbour extension. * $PLATFORMS$ - * All + * All * $SEEALSO$ * Object Oriented Programming,CLASS,METHOD,DATA * $END$ @@ -195,7 +222,7 @@ * $COMMANDNAME$ * METHOD * $CATEGORY$ - * Oop Command + * OOP Command * $ONELINER$ * Declare a METHOD for a class in the class header * $SYNTAX$ @@ -208,27 +235,27 @@ * METHOD ( [] ) OPERATOR * METHOD ( [] ) CLASS * $ARGUMENTS$ - * Name of the method to define + * Name of the method to define - * Optional parameter list + * 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: + * using this syntax: * - * METHOD ( [] ) CLASS + * METHOD ( [] ) CLASS * * Methods can reference the current object with the keyword "Self:" or - * its shorthand version "::". - * - * CLAUSES: + * 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. + * object. * * INLINE Fast and easy to code, INLINE lets you define the * code for the method immediately within the definition @@ -236,31 +263,31 @@ * must be fully defined after the ENDCLASS command. * The following INLINE receives a parameter * of Self. If you need to receive more parameters, use - * the BLOCK clause instead. + * the BLOCK clause instead. * * BLOCK Use this clause when you want to declare fast 'inline' * methods that need parameters. The first parameter to - * must be Self, as in: + * must be Self, as in: * - * METHOD BLOCK {|Self,,, ...,|...} + * METHOD BLOCK {|Self,,, ...,|...} * * EXTERN If an external function does what the method needs, * use this clause to make an optimized call to that - * function directly. - * + * function directly. + * * SETGET For calculated Data. The name of the method can be - * manipulated like a Data element to Set or Get a value. + * 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. + * when you are first creating and testing a Class. * * OPERATOR Operator Overloading for classes. - * See example Tests/TestOp.prg for details. + * See example Tests/TestOp.prg for details. * - * CLASS + * CLASS * Use this syntax only for defining a full method after - * the ENDCLASS command. + * the ENDCLASS command. * $EXAMPLES$ * CLASS TWindow @@ -287,9 +314,9 @@ * $STATUS$ * R * $COMPLIANCE$ - * METHOD is a Harbour extension. + * METHOD is a Harbour extension. * $PLATFORMS$ - * All + * All * $SEEALSO$ * TClass(),Object Oriented Programming,DATA,CLASS * $END$ @@ -299,36 +326,36 @@ * $COMMANDNAME$ * MESSAGE * $CATEGORY$ - * Oop Command + * OOP Command * $ONELINER$ * Route a method call to another Method * $SYNTAX$ * MESSAGE METHOD ( [] ) * MESSAGE () METHOD ( [] ) * $ARGUMENTS$ - * The pseudo-method name to define + * The pseudo-method name to define * The method to create and call when - * is invoked. + * is invoked. - * Optional parameter list for the method + * 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. + * 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). + * 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(). + * function BeginPaint(). * $EXAMPLES$ * CLASS TWindow @@ -340,9 +367,9 @@ * $STATUS$ * R * $COMPLIANCE$ - * MESSAGE is a Harbour extension. + * MESSAGE is a Harbour extension. * $PLATFORMS$ - * All + * All * $SEEALSO$ * METHOD,DATA,CLASS,Object Oriented Programming * $END$ @@ -352,18 +379,18 @@ * $COMMANDNAME$ * ERROR HANDLER * $CATEGORY$ - * Oop Command + * OOP Command * $ONELINER$ * Designate a method as an error handler for the class * $SYNTAX$ * ERROR HANDLER ( [] ) * $ARGUMENTS$ - * Name of the method to define + * Name of the method to define - * Optional parameter list + * Optional parameter list * $DESCRIPTION$ * ERROR HANDLER names the method that should handle errors for the - * class being defined. + * class being defined. * $EXAMPLES$ * CLASS TWindow @@ -373,9 +400,9 @@ * $STATUS$ * R * $COMPLIANCE$ - * ERROR HANDLER is a Harbour extension. + * ERROR HANDLER is a Harbour extension. * $PLATFORMS$ - * All + * All * $SEEALSO$ * Object Oriented Programming,ON ERROR,CLASS,METHOD,DATA * $END$ @@ -385,19 +412,19 @@ * $COMMANDNAME$ * ON ERROR * $CATEGORY$ - * Oop Command + * OOP Command * $ONELINER$ * Designate a method as an error handler for the class * $SYNTAX$ * ON ERROR ( [] ) * $ARGUMENTS$ - * Name of the method to define + * Name of the method to define - * Optional parameter list + * 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. + * class being defined. * $EXAMPLES$ * CLASS TWindow @@ -407,9 +434,9 @@ * $STATUS$ * R * $COMPLIANCE$ - * ON ERROR is a Harbour extension. + * ON ERROR is a Harbour extension. * $PLATFORMS$ - * All + * All * $SEEALSO$ * Object Oriented Programming,ERROR HANDLER,CLASS,METHOD,DATA * $END$ @@ -419,14 +446,14 @@ * $COMMANDNAME$ * ENDCLASS * $CATEGORY$ - * Oop Command + * OOP Command * $ONELINER$ * End the declaration of a class. * $SYNTAX$ - * ENDCLASS + * ENDCLASS * $DESCRIPTION$ - * ENDCLASS marks the end of a class declaration. - * It is usually followed by the class methods that are not INLINE. + * ENDCLASS marks the end of a class declaration. + * It is usually followed by the class methods that are not INLINE. * $EXAMPLES$ * CLASS TWindow @@ -436,9 +463,9 @@ * $STATUS$ * R * $COMPLIANCE$ - * ON ERROR is a Harbour extension. + * ON ERROR is a Harbour extension. * $PLATFORMS$ - * All + * All * $SEEALSO$ * Object Oriented Programming,CLASS,METHOD,DATA * $END$