UsersGuide:Chapter 10:Class Interfaces

From Real Software Documentation

Jump to: navigation, search

Contents

Class Interfaces

A class interface is a construct that you can use to tie together classes that do not share a super class but have something in common in your application. Class interfaces are used to specify what an object does without specifying how it does it.

In order to understand class interfaces better, it’s helpful to think of a class as consisting of two components, the (public) interface to the class and the implementation. The interface consists of the class’s Public method calls and the implementation is the code that implements the methods. The interface says what the class does and the implementation says how it does it.

In the object hierarchy, a subclass inherits both the interface and the implementation from its super class. That is, it gets both the method calls and the specific implementation of the method.

Class interfaces enable you to separate the two constructs. If two or more classes need to do the same thing but do it in different ways, you use an interface instead of a super class.

A class interface operates as a “spec” that contains a list of methods that custom classes in your project use. It does not actually contain any code for the methods themselves.

The methods in the class interface are placeholders for methods that are actually contained in each custom class that “implements” the class interface. Also, a custom class can implement more than one class interface.

The term “implement” simply means that the class has methods of the same names and declarations that are found in the class interface. The class interface specifies the methods and their declarations but not the code.

Many class interfaces are built into Real Studio. You can implement any of these in your classes or add and implement your own. For example, the Readable and Writeable interfaces specify methods for reading and writing data. Each class that uses the Readable or Writeable interfaces supplies the implementations. For example, a class that reads data from the Serial port would use a different implementation than a class that reads data from a binary file.

When you specify that a class implements a class interface, the class must implement all the methods in the class interface and the method declarations must match. However, the classes are free to implement the methods in different ways. For example, a method that changes the font in a Label would be implemented in a different way than a method that changes the font in a Canvas control that displays text via calls to the Graphics class.

The process involves three basic phases:

  • Creating the class interface,
  • Creating the classes that implement the class interface,
  • Adding the classes to your project and calling the class interface methods in your program. Typically, that means writing generic code that tests whether a class implements a class interface and executing class interface methods where appropriate.

To create a class interface, do this:


  1. If the Project Editor is not displayed, click on its tab and then click the Add Class Interface button or choose Project ↠ Add ↠ Class Interface.
    A new class interface is added to the Project Editor. Its icon is hollow, indicating that it doesn’t actually hold code. The Properties pane shows that the only property that you can modify is its name. It has no Super Class, as it is not part of the object hierarchy.
    The Project Editor with a new class interface.

  2. If desired, use the Properties pane to change the name of the class interface.
    The Aggregates property enables you to specify one or more interfaces for this interface to implement. Clicking the small buttons with three dots displays a dialog in which you can choose among the existing interfaces that you would like to implement.
  3. If desired, click the three dots and choose one or more interfaces.
    The Project Editor displays the chosen interfaces.
    A new interface that implements the existing Writeable interface.
  4. Double-click the Class Interface item in the Project Editor to display the Code Editor for the class interface.
    The Code Editor for a class interface has items only for methods, shared methods, and notes. You cannot create properties or constants for a class interface.
  5. Click the Add Method button or choose Project ↠ Add ↠ Method to add a method declaration to the class interface.
    The Method declaration area appears above the Code Editor area.
    The Method declaration area for a Class Interface.
  6. Enter the name of the method, its parameters, and, if it will return a value, the data type of the value being returned.
    In other words, declare the method in the normal manner. The only difference is that there is no way to specify the Scope of a method in a class interface. This is because the code for the method does not live in the class interface at all. You use the Method declaration only to provide the “spec” for the methods that will be written (a.k.a., “implemented”) elsewhere. The method will have several implementations, one in each class that implements the class interface.
    For more information on declaring a method, see the section Adding Methods to Windows in Chapter 5.
  7. Repeat steps 4 and 5 for each method or function declaration of the Class Interface.
    After you have created your class interface, you must “hook it up” to one or more custom classes. To be non-trivial, we assume it will be two or more custom classes.
    You add the code for the methods declared in the class interface in each class that implements the class interface.

To implement a class interface, do this:


  1. In the Project Editor, select the class to which you want to add the class interface or, if it does not yet exist, click the Add Class button in the Project Editor or choose Project ↠ Add ↠ Class.
    Notice that the Properties pane for the class contains a field for specifying the class interface (or interfaces) for the class.
    You can specify the class interface or interfaces that the class implements by entering their names in the Interfaces field in the Properties pane or via the Project pane’s contextual menu. If desired, you can specify more than one class interface for the class.
  2. In the Properties pane’s Interfaces field, click on the ellipsis (the box on the right with three dots in it) or right+click (Control-click on Macintosh) on the name of the class in the Project Editor and choose Implement Interface.
    The Implement Interface dialog box appears. It presents a list of all the currently defined class interfaces in the application.
    The Implement Interfaces dialog box.

  3. Click the checkboxes for the class interface or interfaces you wish to add.
    When you do so, the names of the class interfaces are added to the Interfaces field in the class’s Properties pane. Real Studio also adds an Interfaces column to the Project Editor that shows the names of the newly added interfaces.
    When you choose a class interface, Real Studio adds all the method declarations for the interface to the class’s Method Editor. The class’s Method Editor then displays the first such method, ready for you to write the method. Each method that is generated by the Implement Interface dialog has a comment line that explains which Class Interface the method belongs to.
  4. If desired, choose the “Include #error” option.
    If you select the “Include #error in the source of each method” option in the Implement Interfaces dialog, it also includes an uncommented line with the directive “#error”. This line causes the compiler to generate a syntax error. The purpose of the line is to remind you to implement the method. If it weren’t there and you forget to implement the method, you would satisfy the technical requirement that the method exists, but it would be an empty method. The resulting compiler error would remind you to implement the method.
    When you finish implementing the method, you should remove or comment out this line.
    Here is an example method that was generated by the Implement Interface dialog.
The Flush method of the Writeable class interface.

You can also enter the names of class interfaces directly into the Interfaces field in the Properties pane. Click in the text area of the Interfaces field to get an insertion point and enter the name of the interface into the Interfaces field of the Properties pane. When you enter an interface, Real Studio displays a dialog asking you whether you’d like it to generate all the method declarations for the interface.

The Add Methods dialog.

If you click Yes, it displays the Implement Interface dialog where you can choose the interface you entered.

If you don’t accept this choice, you must take care to implement all the methods yourself.

When you add a class interface to a class, the Project Editor adds a third column and it lists the class interfaces for the class’s interfaces.

Specifying the Interface

In rare cases you may find that a class implements more than one method with the same name but from different class interfaces. You may have decided that a method implements two interfaces that both have a method that shares the same name and declaration. Normally, there is no way to tell them apart. However, there is a way to specify the class interface to which each method belongs. You can do so using the optional Interfaces field in the method declaration dialog box.
Suppose you have two class interfaces, Foo and Bar, that both contain a method named “wahoo” It has no parameters. Let’s say the method Baz implements both methods. Here is the Project Editor for this example.

The Project Editor for the Show Implements example.


In order to tell them apart, you use the optional “Implements” field in the method declaration dialog box.
To specify the interface, do this:


  1. Right+click on the method name in the Project window.
    The contextual menu for the method appears.
  2. Choose Show Implements from the contextual menu.
    The “Implements” field is added to the method declaration area, just below the Return Type field.
    The “Implements” field in the Method declaration dialog.
  3. Enter the name of the interface and the method that implements this version of a set of identically named methods.

Use the dot notation to specify it in the format interfacename.methodname. This illustration shows the completed specification for this example.

The “Implements” field shows the source interface for this method.

Implementing Methods

The next task is to implement the methods of the class interfaces that you added to the class. If you used the Implement Interfaces dialog box, you have a head start on this task because it adds the method names and declarations of each class interface to the class automatically. If you entered the names of the class interfaces manually, you now need to add the required methods to the class.

To implement a method, do this:


  1. If the methods are not already added, click the Add Method button or choose Project ↠ Add ↠ Method.
    The Add Method pane appears.
  2. Enter a method name and the declaration that was defined in the class interface and click OK.
    This time, the Code Editor supports code entry.
  3. With the Code Editor, write the implementation of each class interface method for this class.
  4. Repeat steps 4 to 6 for every method declaration in each class interface that is implemented by this class.
  5. Repeat the entire process (steps 1 to 7) for each class that implements the class interface.
    The above illustrations, two classes implement the class interface, FontInterfaceManager, shown in the Project Editor. Different classes can implement the same method in different ways.


Modifying and Deleting Interfaces

If you change your mind and want to delete or replace an interface, you do so via the Interfaces field in the Project Editor.

Click in the Interfaces field to get an insertion point and then select the name of the interface you want to modify or delete. Type to make the desired changes.

Please note that any methods that were added to the class while the interface was implemented are not modified or deleted when you remove the interface that they belonged to. That is, if you add an interface via the Implement Interfaces dialog, the methods that are specified by that interface remain as part of the class even if you delete the interface itself. You must take care of any “clean up” activities.

A Class Interface Example Project

The following very simple example illustrates the basic concepts. The application has custom classes based on the TextField and Label classes that implement a class interface. The class interface has one method specification for updating a font. The user chooses a font from the popup menu and a message is sent to all controls in a window that implement the class interface.

The class interface, FontInterfaceManager, contains one method specification:

The UpdateFont method specification.


This method declaration area specifies that each class that implements this class interface has to have a method called UpdateFont and it must take one parameter as a String.

Two custom classes based on TextField and Label implement this method, as is shown in the Project Editor:

The Project Editor with two classes that implement the class interface.


The implementation of the UpdateFont method happens to be the same in both classes, but this is not a requirement of class interfaces in Real Studio. It is simply:

Sub UpdateFont (s As String)
Self.TextFont=s

With these objects in place, generic code can be written that determines whether a control in a window implements the FontInterfaceManager class interface.

Suppose several instances of CustomTextFields and CustomStaticTexts are added to a window. The following code in the Change event of a PopupMenu changes the font displayed by all such controls based on the user’s selection. The IsA operator tests whether a control implements the class interface. If it does, the UpdateFont method of the class interface is called, as implemented by each custom class. The term Me.Text contains the current selection of the PopupMenu.

Dim i as Integer
For i=0 to Self.ControlCount - 1 //number of controls in the window
If Self.Control(i) IsA FontInterfaceManager then
FontInterfaceManager(Self.Control(i)).UpdateFont(Me.Text)
End if
Next

As you can see, you can specify that any custom class implements a class interface, regardless of its super class. In this way, class interfaces can group together classes that are not related to one another via the object hierarchy and give them functionality that can be managed in one place in your project.

Creating a new Class Interface from an Existing Class

If an existing class in your project contains methods that you want to reuse as a class interface, you can generate the new class interface from the Project Editor.

To use an existing class as the basis of a class interface, do this:

  1. Right+click (Control-click on Macintosh) on the class you want to use as the starting point for the new class interface.
    The contextual menu for the class appears.
  2. Choose Extract Interface from the contextual menu.
    The Extract Interface dialog box appears.
    The Extract Interface dialog box.

    The Extract Interface dialog lists all the methods in the current class.
  3. Enter the name of the new class interface in the Interface Name field.
    The name of the class you clicked on, followed by Interface is entered by default.
  4. Click the checkbox for each method you want to include in the new class interface.
  5. When you are finished, click OK to save the result.

Real Studio creates the new class interface, adds it to the project, and makes the current class an implementor of the new interface. That is, the name of the new class interface is now shown in the Interfaces field of the class’s Project pane.

Retrieved from "http://docs.realsoftware.com/index.php/UsersGuide:Chapter_10:Class_Interfaces"
Personal tools