CLASS/END CLASS Block

Purpose

Create the code and data for an object.

Syntax

CLASS name  [$GUID] [COMMON] [OPTIMIZE] [AS EVENT]
  INSTANCE ClassName AS STRING
  Class Method code blocks...
  INTERFACE name $GUID  [AS EVENT]
    INHERIT IUNKNOWN
    Method and Property code blocks...
  END INTERFACE
  EVENT SOURCE interface-name
END CLASS

Remarks

CLASS / END CLASS statements enclose the Interface implementation(s)  and Instance variable declarations of a Class.  METHOD and PROPERTY blocks contain the code to be executed on an object.  INSTANCE statements define the variables which are unique to each instance of an object of this class.

The name and optional $GUID are supplied by the programmer to identify the class.  By default, a class is considered private, so that the methods are accessible only from within the EXE or DLL where it is defined.  The AS COM attribute makes the class available externally, to virtually any process which is COM-aware.

With a private class, the $GUID may be freely omitted, as PowerBASIC can readily identify the class by name.  With a published COM class, you should insert a specific GUID of your choice.  If omitted, a  random GUID will be created by the compiler, but it will change every time you compile the program.  This will be difficult to synchronize with other programs which wish to identify and access your object.

COMMON

The optional COMMON descriptor may be included to specify that this class may be freely referenced by and between linked unit modules (Host/Main or SLL).  This has the added side effect of ensuring that the class will not be removed by #OPTIMIZE CODE ON.

AS EVENT

If a class is an Event Source (it generates events rather than handling events), one or more EVENT SOURCE statements are included to name the event interfaces.  The event interfaces must be declared and implemented separately.  An event is generated by executing a RAISEEVENT statement or OBJECT RAISEEVENT statement in the class. If a class is an Event Handler (it contains code to handle an event generated by an Event Source), the AS EVENT attribute must appear on the CLASS statement and each INTERFACE statement.  An Event Handler is also known as an "Event Sink".

OPTIMIZE

With code optimization enabled (#OPTIMIZE CODE ON), PowerBASIC removes code for subs and functions which are not called.  Where possible, this technique is even applied to individual methods and property methods within classes.

Of course, if an object variable is transferred out of the current module (to another EXE/SLL/DLL), there is no way to determine (at compile-time) which methods may be called on it at run-time, so none can be safely removed.  COMMON and EVENT classes allow variables to be transferred out of the module, so they block removal of any code in the class.

The OPTIMIZE descriptor allows you to control this code optimization to a high degree.  If you specify the OPTIMIZE option, you are stating that no object variables on this class will be transferred out of the module.  Therefore, PowerBASIC is free to remove any code in the class which is not referenced.  This is a powerful tool which can allow you to substantially reduce the size of your program.

The OPTIMIZE rules can be summarized:

  1. If a class is marked COMMON or EVENT, no methods or property methods are ever removed from it.

  2. If a class is marked OPTIMIZE, you state that no object variables from this class will be transferred out of the module.  Methods which are not referenced are removed from the final code.  OPTIMIZE may not be combined with COMMON or EVENT.

  3. If no classes in the module are marked COMMON or EVENT, all classes are considered to be marked OPTIMIZE.  All methods in all classes which are not referenced are extracted from the final code.

See also

#OPTIMIZE, EVENT SOURCE, EVENTS, INSTANCE, INTERFACE (Direct), INTERFACE (IDBind),  Just what is COM?, METHOD, PROPERTY, RAISEEVENT, What is an object, anyway?