Table of Contents
6.11 Completion - FileCompletion
The base class Completion (gb.form) enables the automatic completion of texts in text fields such as TextBox, TextArea or in the Gambas source editor. Some controls such as a TableView also have the Editor property, which can be assigned Completion.Editor to provide completions for table cells.
Note: The Completion class is only a template: you create a derived, specialised completion class from the template by having it inherit from the base Completion class and override its (base) methods.
You can create this class. This is how you create a new, specialised completion class for the specified control. The parameter 'hEditor' has the value of a special TextBox or a special TextArea:
Dim hCompletion As Completion hCompletion = New Completion ( hEditor As Control ) As "EventName"
The FileCompletion class is a specialised completion class. It is introduced to you in paragraph 6.11.4.
6.11.1 Properties
The Completion class has these properties:
| Property | Data type | Description |
|---|---|---|
| Delay | Integer | Returns or sets the delay in milliseconds between a key press and the display of the completion pop-up. The default value is 350. |
| Editor | Control | The TextBox or TextArea are the defaults for completions. Some controls, such as a TableView, have an Editor property that can also be assigned to the Completion.Editor property to provide completions on table cells. |
| Icons | String[ ] | Array of icon names to be displayed in the pop-up window next to the completion suggestions in the List property. The names are looked up in the Picture Cache. You fill this property in the Fill method of the special class that inherits from Completion. |
| List | String[ ] | The array of completion suggestions in the pop-up window. You fill this property in the Fill method of the special class that inherits from Completion. |
| Start | Integer | Specifies the character position within the editor where the pop-up list is displayed. You fill this property in the Fill method of the special class that inherits from Completion. |
Table 6.11.1.1 : Properties of the Completion class
6.11.2 Methods
The Completion class has these three methods:
| Method | Description |
|---|---|
| Open() | Opens the completion pop-up window. |
| Close() | Closes the completion popup window. |
| Fill( sText As String, bExplicit As Boolean ) | Fills the text to be completed. sText is the source text to be completed. The argument bExplicit is used by the code inside the completion class to indicate that Fill was called by the Open method. |
Table 6.11.2.1 : Methods of the Completion class.
Notes:
- The Fill(…) method must be re-implemented by all derived classes that inherit from Completion.
- Fill(…) is called whenever the completion popup needs to be displayed. You are given an initial string 'Text' and must fill the Completion.List property with all the completions of text that apply to your specific completion class. For example, the specific class FileCompletion fills the list with all files whose path each starts with 'Text' - here the character /.
- In addition, the 'Icons' property specifies the images that can be displayed in the pop-up window before each completion suggestion.
- The Completion.Start property allows you to set the horizontal position where the
- pop-up window - relative to the editor used - should be displayed.
6.11.3 Events
The Completion class has only the Activate() event. It is triggered when a completion proposal is selected from the list in the pop-up window.
6.11.4 Class FileCompletion
The derived class FileCompletion - based on the (base) class Completion - enables the automatic completion of path specifications in selected text fields such as in a TextBox:
Figure 6.11.4.1: Text completion in a TextBox
The class can be created. The parameter 'hEditor' has the value of a special TextBox or a special TextArea:
Dim hCompletion As FileCompletion hFileCompletion = New FileCompletion ( hEditor As Control ) As "EventName"
The following source code creates a new auto-complete for the specified TextBox1 control:
Private $hFileComplete As FileCompletion Public Sub Form_Open() $hFileComplete = New FileCompletion(TextBox1) End
If you enter a file path in the text box - as shown in Figure 6.11.4.1 - then the path will be auto-completed after you enter / or a few characters of the appropriate path. Good to know: The method FileCompletion.Fill(…) is executed automatically!
6.11.5 Additions
From the Gambas IDE you already know other completion classes, which complete properties or methods or names of images in the source code editor instead of files, among other things:
Figure 6.11.5.1: Text completion 1 IDE
Figure 6.11.5.2: Text completion 2 IDE