Text Auto-Completion

May 17, 2000
by Gary Rosenzweig

Here is something that I recently developed for a Lingo-based Xtra. You know when you are using a browser and you begin to type the URL and the browser fills in the rest of the name? Like if I were to type "http://clev", the browser would fill in "http://clevermedia.com" without me having to type in the other letters.

This is called auto-completion and it is a very nice interface technique. If you are allowing the user to type in something and you have a pretty good idea of what they might be trying to type, you can use this to speed up their experience.

For instance, what if you asked the user to choose their favorite color? There might be too many to list for them to choose from, so you leave a blank text entry area instead. But, instead of having them type "magenta", you can fill in the word "magenta" once they have typed "ma".

Try it in this Shockwave example. You may have to click on the Shockwave movie to assign keyboard focus first.

So, how to do this? First, you need a list of words. Place that in a text member. One word per line. Then, you need a text member on the Stage. Don't make it editable. Instead, just make it a plain, non-editable, text member. The frame behavior we will write will do all the work.

This frame behavior will accept key presses with an on keyUp handler and use them to build the word. The text member will simply be used to display it.

The behavior starts with an on beginSprite handler that reads in the words from the word list and converts it to a Lingo list. It will also set two properties to empty: pKeyword and pCompleteWord. The first is a record of what keys the user has typed. The second is the complete word that the behavior believes the user is trying to type.

property pKeyword, pCompleteWord, pData, pWordList

on beginSprite me

  -- get words from text list
  pWordList = []
  text = member("word list").text

  repeat with i = 1 to text.line.count
    add pWordList, text.line[i]
  end repeat
  sort pWordList

  -- set keyword and complete word
  pKeyword = ""
  pCompleteWord = ""

  -- show blank
  showWord(me)

end

As each key is pressed, a character is added to pKeyword. If the backspace key is pressed, the last letter is removed. The "on findCompleteWord" handler is called to do the auto-completion.

on keyUp me

  -- take new key press
  k = the key

  if k = BACKSPACE then

    -- remove character from keyword
    if length(pKeyword) > 0 then
      delete the last char of pKeyword
    end if

  else if "abcdefghijklmnopqrstuvwxyz" contains k then
    -- accept new character
    put k after pKeyWord
  end if

  -- get new word
  findCompleteWord(me)
  showWord(me)

end

To find a word, the pKeyword property is compared to every word in the list. Once a word is found that starts with pKeyword, the search is done. Therefore, if you type "p", the auto-complete will first return "pink." If the user types "pu" then it will get more specific and return "purple."

on findCompleteWord me

  -- if blank, clear
  if length(pKeyword) < 1 then
    pCompleteWord = ""
    pData = ""
  else

    -- get first word from list that matches
    pCompleteWord = ""

    repeat with i = 1 to pWordList.count
      if pWordList[i] starts pKeyword then
        -- set new word
        pCompleteWord = pWordList[i]
        exit repeat
      end if
    end repeat

  end if

end

The "on showWord" handler will place the results of the typing and search into a single text member. It will color the letters typed black and the rest of the word grayish blue. This helps the user understand where their typing ends and the auto-completion begins.

on showWord me

  -- fill in text member
  if pCompleteWord = "" then
    -- blank out
    member("Keyword").text = pKeyword
  else
    -- fill with complete word
    member("Keyword").text = pCompleteWord
    -- color all in blue
    member("Keyword").color = rgb("9999FF")
    -- color type letters in black
    member("Keyword").char[1..length(pKeyword)].color = rgb("000000")
  end if

end

on exitFrame me
  go to the frame
end

After the user has entered the word, they can press Return, hit a button, or move on to do other things on the same screen. That is up to you. You could even check to make sure that pCompleteWord is not empty and insure that the user has typed a valid response. This way, a long pop-up menu can be converted to a small text member very easily. With a little work, you could convert this to a behavior that has a pFocus property and enables the user to tab through more than one auto-completing field on a screen.

Gary Rosenzweig's latest book is "Advanced Lingo for Games." In it, you can find the source code for more than 20 complete games. More information about the book can be found at http://clevermedia.com/resources/bookstore/book4.html. It can be purchased there, or in your local bookstore.

Gary Rosenzweig is the Chief Engineer, founder, and owner of CleverMedia, a game and multimedia development company in Denver, Colorado. He is the author of ten books on Macromedia Director and Flash, including his latest, Special Edition Using Director MX.