/* $DOC$ $AUTHOR$ Copyright 2000 Brian Hays $TEMPLATE$ Command $NAME$ CLASS $CATEGORY$ Class $SUBCATEGORY$ Definition $ONELINER$ Define a Class for Object Oriented Programming $SYNTAX$ [CREATE] CLASS [ [, ] ] [STATIC] $ARGUMENTS$ Name of the class to define. By tradition, Harbour classes start with "T" to avoid collisions with user- 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. $DESCRIPTION$ CLASS creates a class from which you can create objects. The CLASS command begins the class specification, in which the VAR 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 VAR and METHOD commands that follow them. EXPORTED: VISIBLE: HIDDEN: PROTECTED: The class specification ends with the END CLASS command. 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 VAR 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$ #include "hbclass.ch" CREATE CLASS TBColumn VAR Block // Code block to retrieve data for the column VAR Cargo // User-definable variable VAR ColorBlock // Code block that determines color of data items VAR ColSep // Column separator character VAR DefColor // Array of numeric indexes into the color table VAR Footing // Column footing VAR FootSep // Footing separator character VAR Heading // Column heading VAR HeadSep // Heading separator character VAR Width // Column display width VAR ColPos // Temporary column position on screen METHOD New() // Constructor ENDCLASS METHOD New() CLASS TBColumn RETURN Self $STATUS$ R $COMPLIANCE$ H $PLATFORMS$ All $SEEALSO$ HBClass(), VAR, METHOD $END$ */ /* $DOC$ $AUTHOR$ Copyright 2000 Brian Hays $TEMPLATE$ Command $NAME$ VAR $CATEGORY$ Class $SUBCATEGORY$ Data $ONELINER$ Alternate syntax for VAR: instance variable for the objects. $SYNTAX$ VAR [, ] [ AS ] [ INIT ] [[EXPORTED | VISIBLE] | [PROTECTED] | [HIDDEN]] [READONLY | RO] $ARGUMENTS$ Name of the VAR Optional data type specification from the following: Character, Numeric, Date, Logical, Codeblock, NIL. Optional initial value when creating a new object. EXPORTED Specifies that this VAR is accessible to functions and methods outside of the class. VISIBLE is a synonym for EXPORTED. PROTECTED Specifies that this VAR is only accessible to functions and methods within this class and its subclasses. HIDDEN Specifies that this VAR 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$ VAR 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 VAR elements are referenced with the colon `:` as in `MyObject:Heading := "Last name"`. Usually a class also defines methods to manipulate the VAR. You can use the `AS ` clause to enforce that the VAR is maintained as a certain type. Otherwise it will take on the type of whatever value is first assigned to it. Use the `INIT ` clause to initialize that VAR to whenever a new object is created. VAR can be a synonym for VAR, or it can use a slightly different syntax for compatibility with other dialects. $EXAMPLES$ #include "hbclass.ch" CREATE CLASS TBColumn VAR Block // Code block to retrieve data for the column VAR Cargo // User-definable variable VAR ColorBlock // Code block that determines color of data items VAR ColSep // Column separator character VAR DefColor // Array of numeric indexes into the color table VAR Footing // Column footing VAR FootSep // Footing separator character VAR Heading // Column heading VAR HeadSep // Heading separator character VAR Width // Column display width VAR ColPos // Temporary column position on screen METHOD New() // Constructor ENDCLASS METHOD New() CLASS TBColumn RETURN Self $STATUS$ R $COMPLIANCE$ H $PLATFORMS$ All $SEEALSO$ CLASS, METHOD, CLASS VAR, VAR $END$ */ /* $DOC$ $AUTHOR$ Copyright 2000 Brian Hays $TEMPLATE$ Command $NAME$ CLASS VAR $CATEGORY$ Class $SUBCATEGORY$ Data $ONELINER$ Define a CLASS VAR variable for a class (NOT for an Object!) $SYNTAX$ CLASS VAR [, ] [ AS ] [ INIT ] $ARGUMENTS$ Name of the VAR Optional data type specification from the following: Character, Numeric, Date, Logical, Codeblock, NIL Optional initial value at program startup $DESCRIPTION$ `CLASS VAR` variables can also be thought of as the "properties" of an entire class. Each `CLASS VAR` 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 existence for this class. You can use the `AS ` clause to enforce that the `CLASS VAR` is maintained as a certain type. Otherwise it will take on the type of whatever value is first assigned to it. Use the `INIT ` clause to initialize that `VAR` to whenever the class is first used. $EXAMPLES$ #include "hbclass.ch" CREATE CLASS TWindow VAR hWnd, nOldProc CLASS VAR lRegistered AS LOGICAL ENDCLASS $STATUS$ R $COMPLIANCE$ H $PLATFORMS$ All $SEEALSO$ CLASS, METHOD, VAR $END$ */ /* $DOC$ $AUTHOR$ Copyright 2000 Brian Hays $TEMPLATE$ Command $NAME$ METHOD $CATEGORY$ Class $SUBCATEGORY$ Method $ONELINER$ Declare a METHOD for a class in the class header $SYNTAX$ METHOD ( [] ) [CONSTRUCTOR] METHOD ( [] ) INLINE METHOD ( [] ) BLOCK METHOD ( [] ) EXTERN ( [] ) METHOD ( [] ) SETGET METHOD ( [] ) VIRTUAL METHOD ( [] ) OPERATOR METHOD ( [] ) CLASS $ARGUMENTS$ Name of the method to define 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 ( [] ) CLASS 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 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 must be Self, as in: 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. 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 Use this syntax only for defining a full method after the ENDCLASS command. $EXAMPLES$ // FIXME #include "hbclass.ch" CREATE CLASS TWindow VAR hWnd, nOldProc METHOD New() CONSTRUCTOR METHOD Capture() INLINE SetCapture( ::hWnd ) METHOD End() BLOCK {| Self, lEnd | iif( lEnd := ::lValid(), ; ::PostMsg( "close" ), ), lEnd } METHOD EraseBkGnd( hDC ) METHOD cTitle( cNewTitle ) SETGET METHOD Close() VIRTUAL ENDCLASS METHOD New() CLASS TWindow LOCAL nVar, cStr // ... ... // ... ... RETURN Self $STATUS$ R $COMPLIANCE$ H $PLATFORMS$ All $SEEALSO$ HBClass(), VAR, CLASS $END$ */ /* $DOC$ $AUTHOR$ Copyright 2000 Brian Hays $TEMPLATE$ Command $NAME$ MESSAGE $CATEGORY$ Class $SUBCATEGORY$ Method $ONELINER$ Route a method call to another Method $SYNTAX$ MESSAGE METHOD ( [] ) MESSAGE () METHOD ( [] ) $ARGUMENTS$ The pseudo-method name to define The method to create and call when is invoked. 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$ // FIXME #include "hbclass.ch" CREATE CLASS TWindow VAR hWnd, nOldProc METHOD New() CONSTRUCTOR MESSAGE BeginPaint METHOD xBeginPaint() ENDCLASS $STATUS$ R $COMPLIANCE$ H $PLATFORMS$ All $SEEALSO$ METHOD, VAR, CLASS $END$ */ /* $DOC$ $AUTHOR$ Copyright 2000 Brian Hays $TEMPLATE$ Command $NAME$ ERROR HANDLER $CATEGORY$ Class $SUBCATEGORY$ Method $ONELINER$ Designate a method as an error handler for the class $SYNTAX$ ERROR HANDLER ( [] ) $ARGUMENTS$ Name of the method to define Optional parameter list $DESCRIPTION$ `ERROR HANDLER` names the method that should handle errors for the class being defined. $EXAMPLES$ #include "hbclass.ch" CREATE CLASS TWindow ERROR HANDLER MyErrHandler() ENDCLASS METHOD MyErrHandler() CLASS TWindow RETURN Self $STATUS$ R $COMPLIANCE$ H $PLATFORMS$ All $SEEALSO$ ON ERROR, CLASS, METHOD, VAR $END$ */ /* $DOC$ $AUTHOR$ Copyright 2000 Brian Hays $TEMPLATE$ Command $NAME$ ON ERROR $CATEGORY$ Class $SUBCATEGORY$ Method $ONELINER$ Designate a method as an error handler for the class $SYNTAX$ ON ERROR ( [] ) $ARGUMENTS$ Name of the method to define 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$ #include "hbclass.ch" CREATE CLASS TWindow ON ERROR MyErrHandler() ENDCLASS METHOD MyErrHandler() CLASS TWindow RETURN Self $STATUS$ R $COMPLIANCE$ H $PLATFORMS$ All $SEEALSO$ ERROR HANDLER, CLASS, METHOD, VAR $END$ */ /* $DOC$ $AUTHOR$ Copyright 2000 Brian Hays $TEMPLATE$ Command $NAME$ ENDCLASS $CATEGORY$ Class $SUBCATEGORY$ Definition $ONELINER$ End the declaration of a class. $SYNTAX$ ENDCLASS $ARGUMENTS$ (This statement has no arguments) $DESCRIPTION$ ENDCLASS marks the end of a class declaration. It is usually followed by the class methods that are not INLINE. $EXAMPLES$ #include "hbclass.ch" CREATE CLASS TWindow VAR hWnd, nOldProc ENDCLASS $STATUS$ R $COMPLIANCE$ H $PLATFORMS$ All $SEEALSO$ CLASS, METHOD, VAR $END$ */