Keyword

Extends

Description

Used in a module method declaration to indicate that the method is to be called using the dot operator ("."), as if it were an object method of the first parameter.

Usage

Extends parameter As DataType

Part	Type	Description
parameter	same type as dataType	The name of the first parameter. If parameter is Nil, the Extends method is not executed, and a NilObjectException is generated.
DataType	data type or class	The data type for which the method can be called.

Notes

The Extends keyword allows you to call a user-defined method as if it were part of a class. You use the Extends keyword only for the first parameter in the method declaration. Extends indicates that this parameter is to be used on the left side of the dot operator. The remaining parameters in the declaration, if any, are used normally.

Extension methods can be used with classes or other data types. For example, you can define methods that extend String, Color, and Integer data types. You can also extend arrays.

Methods declared in this way are sometimes called "class extension methods" even though they are not actually part of a class. You can use Extends only for methods in a module. Extends cannot be used to override another method. Extension methods are not virtual, since they are not part of a class.

Extension methods are an example of "syntactic sugar". There is no difference in capability between an extension method and a normal module method; each specifies a particular calling syntax. (Many built-in methods are provided in both versions, so that either calling syntax will work.) Extension methods can make calling code more regular and readable, and if used consistently, can make it easier to remember which syntax to use. On the other hand, extension methods can make the dependency of a class on a module less obvious to a programmer.

Sample code

Extends can allow more readable and concise calling code. This example Extends the String data type with a function that determines whether one string contains another. In a module, create this function:

Function Contains(Extends Container As String, Contained As String) As Boolean
  Return Container.IndexOf(Contained) > 0
End Function

The Extends keyword indicates that the first parameter does not appear in the parameter list of the actual method call. Instead, it is used on the left side of the dot operator. The remaining parameter is used normally:

Var s1 As String = "hello world"
Var s2 As String = "world"
If s1.Contains(s2) Then
  ...
End If

Without Extends, the method call would be functionally equivalent, but less clear in meaning:

If Contains(s1, s2) Then ' which string is which?

Here's another example: controls and windows have built-in Left and Top properties, but not Bottom and Right properties. You can simulate these using Extends:

Function Right(Extends ctl As DesktopUIControl) As Integer
  Return ctl.Left + ctl.Width
End Function

Function Bottom(Extends ctl As DesktopUIControl) As Integer
  Return ctl.Top + ctl.Height
End Function

As with the previous example, the Extends keyword indicates that the first parameter is used before the dot operator. Since there are no other parameters, calls to these methods don't use a parameter list. Here's how you might use these functions to place a button below a text field, and to align it with the text field on the right:

MyButton.Top = MyTextField.Bottom + 10
MyButton.Left = MyTextField.Right - MyButton.Width

Compatibility

All project types on all supported operating systems.