POV-Ray : Documentation : Keyword Expansion and CodeList
  POV-Ray 3.6 Documentation Online View Switching between Editor windows Configuring the Internal Editor Keyword Expansion and CodeList

This facility is designed to speed up the authoring of POV-Ray scene files by allowing you to quickly insert any of the standard keywords by typing part of the word and pressing TAB (provided you have the 'Overlay Keyword Expansion On Tab Key' option in the Editor Menu turned on).

If this option is enabled, the tab key serves two functions: it firstly will function to invoke keyword expansion, and secondly, if it appears that keyword expansion is not desired at the current edit position, it functions as a normal tab key (inserting tabs or spaces as defined by your configuration of the editor). A Quick Example

Before getting into the explanation below, we suggest you try it for yourself. Firstly, make sure that 'Overlay Keyword Expansion On Tab Key' is turned on (this is the default so unless you have turned it off it will already be on).

Now, open an editor if you don't already have one open, and position the edit cursor ('caret') on a blank line and type the letters 'am', then press TAB. The word 'ambient' should now appear where you had 'am'. Now press it again and you will see the word 'ambient' become 'ambient_light'. Now press SHIFT+TAB (shift and tab together) and you will see that it goes back to 'ambient', and, if pressed again, back to plain 'am'. How Keyword Expansion Works

When you press TAB, the editor firstly looks at the characters to the left and right of the current edit caret position. If there is blank space to the left of the caret, or there is no blank space to the right of the caret then keyword expansion does not occur and the TAB key will function normally. Note that for the purposes of this test, the start of the line is not considered blank space, but the end of the line is.

To pass the above test, therefore, the caret must be at the end of a word containing at least one character, followed by a space, tab, or the end of the line. The editor will then get this word from the line and compare it (with case-sensitivity) against the list of known POV-Ray scene file keywords that it holds internally.

If the above comparision yields a perfect match (that is, the word on the left of the caret is exactly the same as a keyword), then keyword expansion does not occur and the tab key functions normally.

If the above test fails (that is, the word is not a perfect match), then a test is made for a partial match. If the word on the left of the caret does not even partially match any word in the keyword list, then expansion does not occur and the tab key functions normally.

If the above test passes, the word on the left of the caret must be a partial keyword (for example, 'pigm' is considered a partial keyword since the editor knows that 'pigment' is a keyword). Given this fact, the editor extracts the list of all keywords that match the partial keyword (in the above example, 'pigment', 'pigment_map', and 'pigment_pattern' all contain the prefix 'pigm' and as such would be included in the list).

The editor stores this list in memory and then completes the partial keyword with the first one (alphabetically) from the list it stored (in the above example, this would be 'pigment'). Once this has occurred, the editor is in 'keyword expansion' mode. The editor remains in this mode until you move the edit position or otherwise make any change to the text other than via TAB and SHIFT-TAB expansion.

Pressing TAB again will cause the next keyword in the stored list of possible matches to appear, replacing the first one, and so forth. If you reach the end of the list, pressing TAB will cause the caption bar of POV-Ray for Windows to flash. This is a visual indication that there are no more keywords in the forward direction.

Pressing SHIFT+TAB causes the previous keyword to appear, and if you are at the first keyword in the list, it will cause the original text you typed to be restored. If you are at the original word and press SHIFT+TAB, the caption bar will flash to indicate that you cannot go back any further.

While all this sounds complex in theory, it is in practice very straightforward and natural to use, and once you get used to it you probably won't want to go back to the old way of doing things.

The advantage of keyword expansion becomes clear if you look at the following example: suppose you wanted to enter the 'smooth_color_triangle' keyword. You could of course type the entire keyword in (a total of twenty-one keystrokes). Or, using keyword expansion, you could enter it using only four keystrokes by typing 'sm' then TAB and TAB again. The first tab expands it to 'smooth' and the second tab expands it all the way to 'smooth_color_triangle'.

Hint: if you use keyword expansion and accidentally expand to a word you don't want, if you haven't yet exited keyword expansion mode, the best way to get back is to use SHIFT+TAB to go backwards. It is very easy to just hit the normal 'Undo' key out of habit. While this will work, it won't always restore the caret position. Using SHIFT+TAB also moves the edit caret back to its starting position as well as restoring the starting word. CodeList

The CodeList feature is, like Keyword Expansion, designed to make editing POV-Ray scene files more convenient. It is by default assigned to the keystroke CTRL+SPACE (you can change this from the Keyboard Configuration property page).


Unlike keyword expansion (which allows you to cycle through a list of keywords, one at a time), CodeList allows you to see many of them at once, and select one with the cursor keys or mouse. Using CodeList

When you press CTRL+SPACE, the editor will extract the word under or immediately to the left of the edit caret (note that this differs from keyword expansion, which requires that the caret be at the end of a word). If this word is blank (that is, the caret was on blank space), or if the word does not even partially match any keyword, an alphabetically-sorted list of all POV-Ray scene file keywords is displayed slightly to the right of and below the edit position. If the extracted word was blank, the list will be positioned at the first entry, otherwise it will be positioned at the keyword that is closest (alphabetically) to the extracted word.

If, however, the extracted word perfectly matches a keyword, and is not part of any other keyword in the list, then the list box does not appear. Instead, the keyword that it matched is inserted into the line and the edit caret is moved to the end of that keyword.

If the above match does not occur, then the alphabetically-sorted list of keywords is displayed, and the list is positioned such that the keyword that the extracted word most closely matches is highlighted and is as close as possible to the center of the displayed portion of the list.

If you look at the above image, you will see an example of this situation. The partial keyword (just above and to the left of the top left-hand corner of the list box) is 'phon', and the list has been positioned to the closest keyword, which is 'phong'.

Once the list is displayed, you can cause the highlighted entry to be inserted into the line by just pressing ENTER, SPACE, TAB, or CTRL+SPACE again, or by double-clicking on a list entry. Pressing the ESCAPE key will remove the listbox without altering the line you are editing. You can navigate the listbox by using the up, down, page-up and page-down keys on your keyboard, by the mouse, or by typing (see below). If you cause text to be inserted by any of the above methods other than SPACE, the edit caret will be positioned immediately at the end of the inserted word. If, however, you press SPACE, the word will be inserted followed by a space, and the new edit position will be after the space.

While the list is displayed, even though the up and down arrow keys map to the listbox, the normal character keys still map to the editor. If you continue to type, the letters will be typed into the line at the editor caret position, and, additionally, the list box will automatically scroll so that the highlighted line is always the keyword that has the closest match to what you have typed in. Summary

Just like keyword expansion, the codelist feature can seem complicated when explained in words. However, once you get used to it, it will become quite natural to use. Switching between Editor windows Configuring the Internal Editor

Copyright 2003-2004 Persistence of Vision Raytracer Pty. Ltd.