Calltips are little yellow boxes that pop up to remind you what the arguments and return type of a function are. More generally, they're a UI mechanism to present a small amount of crucial information in a prominent location. To display a calltip, select some text and choose "Show Calltip" from the Search menu. To kill a displayed calltip, hit Esc.
Calltips get their information from one of two places -- either a tags file (see "Finding Declarations (ctags)") or a calltips file. First, any loaded calltips files are searched for a definition, and if nothing is found then the tags database is searched. If a tag is found that matches the highlighted text then a calltip is displayed with the first few lines of the definition -- usually enough to show you what the arguments of a function are.
You can load a calltips file by using choosing "Load Calltips File" from the File menu. You can unload a calltips file by selecting it from the "Unload Calltips File" submenu of the File menu. You can also choose one or more default calltips files to be loaded for each language mode using the "Default calltips file(s)" field of the Language Modes dialog.
The calltips file format is very simple. calltips files are organized in blocks separated by blank lines. The first line of the block is the key, which is the word that is matched when a calltip is requested. The rest of the block is displayed as the calltip.
Almost any text at all can appear in a calltip key or a calltip. There are no special characters that need to be escaped. The only issues to note are that trailing whitespace is ignored, and you cannot have a blank line inside a calltip. (Use a single period instead -- it'll be nearly invisible.) You should also avoid calltip keys that begin and end with '*' characters, since those are used to mark special blocks.
There are five special block types--comment, include, language, alias, and version--which are distinguished by their first lines, "* comment *", "* include *", "* language *", "* alias *", and "* version *" respectively (without quotes).
Comment blocks are ignored when reading calltips files.
Include blocks specify additional calltips files to load, one per line. The ~ character can be used for your $HOME directory, but other shell shortcuts like * and ? can't be used. Include blocks allow you to make a calltips file for your project that includes, say, the calltips files for C, Motif, and Xt.
Language blocks specify which language mode the calltips should be used with. When a calltip is requested it won't match tips from languages other than the current language mode. Language blocks only affect the tips listed after the block.
Alias blocks allow a calltip to have multiple keys. The first line of the block is the key for the calltip to be displayed, and the rest of the lines are additional keys, one per line, that should also show the calltip.
Version blocks are ignored for the time being.
You can use calltips in your own macros using the calltip() and kill_calltip() macro subroutines and the $calltip_ID macro variable. See the Macro Subroutines section for details.