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.

Text Completion Field Constructor and Destructor

The VkCompletionField constructor accepts the standard ObjectPak component name and parent widget arguments:

VkCompletionField(const char *name, Widget parent)

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.

Setting/Clearing the Text Completion Field Expansion List

You can add individual strings to the completion list by passing them as arguments to the VkCompletionField::add() function:

void add(char *name)

You can clear the completion list by calling the VkCompletionField::clear() function:

void clear(VkNameList *nameList = NULL)

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.

Retrieving the Text Completion Field Contents

The VkCompletionField::getText() function duplicates the contents of the text field and then returns a pointer to the duplicate string:

char *getText()

---

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:

openFile = fileName->getText();

Responding to Text Completion Field Activation

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.

Deriving Text Completion Field Subclasses

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:

virtual void expand(struct XmTextVerifyCallbackStruct *cb)

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:

VkNameList *_currentMatchList

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:

VkNameList *_nameList

You can override the protected member function VkCompletionField::activate(), called whenever the user presses the <Enter> key while typing in the text field:

virtual void activate(struct XmTextVerifyCallbackStruct *cb)

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.