The VkCompletionField class, derived from VkComponent, provides a text input field component that supports name expansion. While typing in the field, if the user types a space, then the component attempts to complete the current contents of the field based on a list of possible expansions provided by the application. For example, in a field where the user is expected to enter a file name, the application could provide a list of all files in the current working directory.
The VkCompletionField constructor accepts the standard ObjectPak component name and parent widget arguments:
The constructor creates an OSF/Motif TextField widget as the component's base widget. You can access this widget using the baseWidget() function provided by VkComponent.
The VkCompletionField destructor destroys the component's widget and associated data, including the VkNameList object that stores the list of possible expansions. You should be aware of this in case you provide an existing VkNameList object as an argument to the VkCompletionField::clear() function, described in "Setting/Clearing the Text Completion Field Expansion List." Consult the VkNameList(3) reference page for more information on that class.
You can add individual strings to the completion list by passing them as arguments to the VkCompletionField::add() function:
You can clear the completion list by calling the VkCompletionField::clear() function:
If you provide a VkNameList object, clear() deletes the current completion list and uses the VkNameList object that you provide as the new completion list for the completion field. Consult the VkNameList(3) reference page for more information on that class.
The VkCompletionField::getText() function duplicates the contents of the text field and then returns a pointer to the duplicate string:
Note: Because getText() creates a copy of the text field's contents, you can safely change or delete the returned string.
For example, the following line retrieves the contents of a VkCompletionField object called fileName and assigns the string to the variable openFile:
The VkCompletionField class supplies an ObjectPak member function callback named VkCompletionField::enterCallback. This callback is activated whenever the user presses the <Enter> key while typing in the text field. The callback does not pass any call data. If you want to notify an ObjectPak component whenever the user presses the <Enter> key while typing in a VkCompletionField object, register a member function of that component as an enterCallback function.
The VkCompletionField class should be sufficient for most applications; however, if you want to have more control over the expansion process you can create a subclass of VkCompletionField.
The protected member function VkCompletionField::expand() is called whenever the user types in the text field:
By default, expand() checks whether the user has typed a space, and if so, tries to expand the current contents of the text field; if the user types any other character, expand() simply adds that character to the text field. At any point after an expansion, the VkNameList object pointed to by the protected data member _currentMatchList contains a list of all possible expansions:
You can override the expand() function to install your own expansion algorithm.You have access to the VkNameList object pointed to by the protected data member _nameList, which contains all possible expansions registered with the component:
You can override the protected member function VkCompletionField::activate(), called whenever the user presses the <Enter> key while typing in the text field:
activate() is called after expanding the current contents of the text field and after invoking all member functions registered with the enterCallback callback. By default, this function is empty.