3.2.6.5 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).
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'.
3.2.6.5.2 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.
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.
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.
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.
|
