Difference between revisions of "Documentation:Windows Section 2"

From POV-Wiki
Jump to navigation Jump to search
m (generic version)
 
(10 intermediate revisions by 3 users not shown)
Line 57: Line 57:
  
 
===Dragging and Dropping Files===
 
===Dragging and Dropping Files===
{{#indexentry:drag and drop, dropping files}}
+
{{#indexentry:drag and drop}}
 +
{{#indexentry:dropping files}}
 
<p>
 
<p>
 
Dragging and dropping (a.k.a. Drag'N'Drop) from Windows Explorer (a.k.a. 'My Computer') has the advantage that you  
 
Dragging and dropping (a.k.a. Drag'N'Drop) from Windows Explorer (a.k.a. 'My Computer') has the advantage that you  
 
can select more than one file at a time. You can drag and drop up to 512 POV and/or INI files.  
 
can select more than one file at a time. You can drag and drop up to 512 POV and/or INI files.  
 
POV-Ray for Windows will start processing the first file in the queue and add the rest to the  
 
POV-Ray for Windows will start processing the first file in the queue and add the rest to the  
queue. See <!--<linkto "File Queue">File Queue</linkto>--->[[Documentation:Windows Section 5.2#File Queue|File Queue]] in the Render Menu for more details.
+
queue. See <!--<linkto "File Queue">File Queue</linkto>--->[[Documentation:Windows Section 5.2#File Queue dialog|File Queue dialog]] in the Render Menu for more details.
 
</p>
 
</p>
  
Line 70: Line 71:
  
 
===File Associations===
 
===File Associations===
{{#indexentry:default program,file types,associations}}
+
{{#indexentry:default program, .POV files}}
 +
{{#indexentry:file, associations}}
 +
{{#indexentry:associations}}
 
<p>
 
<p>
 
When POVWIN is installed using the official installer, a file association is established between .POV files and POVWIN.
 
When POVWIN is installed using the official installer, a file association is established between .POV files and POVWIN.
Line 126: Line 129:
 
You can store a default set of options in the file called POVRAY.INI in the INI folder under
 
You can store a default set of options in the file called POVRAY.INI in the INI folder under
 
the POV-Ray documents folder. Unless you chose to install the user-specific files elsewhere
 
the POV-Ray documents folder. Unless you chose to install the user-specific files elsewhere
when you installed, this will be (for example) 'POV-Ray\v3.7\ini\povray.ini' within your
+
when you installed, this will be (for example) 'POV-Ray\vX.y\ini\povray.ini' within your
 
'My Documents' folder. There is a command in the Tools menu that allows you to open this
 
'My Documents' folder. There is a command in the Tools menu that allows you to open this
 
directly (regardless of where you installed).
 
directly (regardless of where you installed).
Line 197: Line 200:
 
</pre>
 
</pre>
  
<table class="centered" width="700x" cellpadding="0" cellspacing="10">
+
<p>If you select this INI file, the default resolution setting will be 120 x 100.
<tr>
+
As soon as you select the [High] section, however, the resolution becomes 640 x 480. See Edit Settings/Render  
  <td>
+
in the <!--<linkto "Render Menu">Render Menu</linkto>--->[[Documentation:Windows Section 5.2#Render Menu|Render Menu]] for instructions on selecting sections. The 'quick resolution' listbox in POVWIN is an example of this type of file. For more information on POV-Ray options and INI files consult the section on
    [[Image:WinImgResolution.gif|center|249px<!--left--->]]
 
  </td>
 
  <td>
 
    <p>If you select this INI file, the default resolution setting will be 120 x 100. As soon as you  
 
select the [High] section, however, the resolution becomes 640 x 480. See Edit Settings/Render  
 
in the <!--<linkto "Render Menu">Render Menu</linkto>--->[[Documentation:Windows Section 5.2#Render Menu|Render Menu]] for instructions on selecting sections. The 'quick resolution' combo box in POVWIN is an example of this type of file. For more information on POV-Ray options and INI files consult the section on
 
 
<!--<linkto "Setting POV-Ray Options">POV-Ray Options</linkto>--->[[Documentation:Tutorial Section 2.2#Setting POV-Ray Options|POV-Ray Options]].</p>
 
<!--<linkto "Setting POV-Ray Options">POV-Ray Options</linkto>--->[[Documentation:Tutorial Section 2.2#Setting POV-Ray Options|POV-Ray Options]].</p>
  </td>
 
</tr>
 
<tr>
 
  <td>
 
    <p class="caption">Quick resolution combo box</p>
 
  </td>
 
  <td></td>
 
</tr>
 
</table>
 
  
 
===Using the Internal Editor===
 
===Using the Internal Editor===
{{#indexentry:Editor|Internal Editor, Using}}
+
{{#indexentry:Editor}}
 +
{{#indexentry:Internal Editor, Using}}
 
<p>
 
<p>
 
The POV-Ray internal editor is an advanced programmer's editor, offering syntax highlighting for POV files (as well as C, Java, and a number of other languages), several indent styles, block indent/undent, column selections, OLE drag and drop, amongst other things. Most of the key mappings are configurable, as are the colors and a number of other options.
 
The POV-Ray internal editor is an advanced programmer's editor, offering syntax highlighting for POV files (as well as C, Java, and a number of other languages), several indent styles, block indent/undent, column selections, OLE drag and drop, amongst other things. Most of the key mappings are configurable, as are the colors and a number of other options.
Line 227: Line 216:
 
</p>
 
</p>
  
<p>Starting with version 3.7 there been two notable changes to the POVWIN IDE.</p>
+
<p>As of version 3.7 there been a few notable changes to the POVWIN IDE.</p>
 
<ol>
 
<ol>
<li>Firstly, it now has a Window menu, which is located where the GUIEXT menu used to be (the latter has moved to within the Options menu). While technically a Window menu is not necessary, as all open files are visible in tabs, the addition of this menu provides two advantages:</li>
+
<li>
<ul>
+
There is now a Window menu, which is located where the GUIEXT menu used to be (the latter has moved to within the Options menu). The MRU (most-recently-used) arrangement of this window menu makes it trivial to toggle between files without taking your eyes off the text or using the mouse. The most recently view window (i.e. the current one) will always be entry 1 in the list. The second most recently viewed (i.e. the last window viewed before switching to the current one) will always be entry 2 in the list, and so forth. Given that entries 1 through 10 in the list are given the menu mnemonics 1 through 0 respectively, all you need to do to toggle between the current and previous files is hit Alt-W then 2. To go to the third oldest, Alt-W then 3, and so forth. Note that the MRU list is not saved on exit.
<li>We can provide the option of showing all tabs on a single line, with a scroller to view non-visible ones. This has not yet been added but will be at a later point.</li>
+
</li>
<li>The MRU (most-recently-used) arrangement of the window menu makes it trivial to toggle between files without taking your eyes off the text or using the mouse. The most recently view window (i.e. the current one) will always be entry 1 in the list. The second most recently viewed (i.e. the last window viewed before switching to the current one) will always be entry 2 in the list, and so forth. Given that entries 1 through 10 in the list are given the menu mnemonics 1 through 0 respectively, it is therefore clear that to toggle between the current and previous files all you need to do is hit Alt-W then 2. To go to the third oldest, Alt-W then 3, and so forth. Currently, the MRU list is not saved on exit.</li>
+
<li>
</ul>
+
An 'alternate render file' feature was added. This is intended to make things easier when editing macro or include files. While it is possible to use SDL to detect whether a macro/include file is being rendered directly and to pull in supporting code, that approach is not very flexible. The alternate render file feature allows a render to be started on an include file, and instead of the include file being rendered directly (as would have happened previously), the source file that most recently included that file in a render will be rendered instead. For this feature to work, you need to have rendered a file which includes the target file during the current editing session (the association between include files and source files is not persisted when POVWIN exits). Additionally you need to have requested to render a source file which does not have the .POV or .INI extension. When you request the render, a message box will appear asking you what to do. You can choose to render the alternate file this time only, to render the alternate file each time you render this one, or to render this one each time (i.e. disable the alternate file option). In all cases, the choice you give only persists for the current editing session; it is not restored when you re-launch POVWIN. this is by design.
<li>Secondly, there is now an 'alternate render file' feature. This is intended to make things easier when editing macro or include files. While it is possible to use SDL to detect whether a macro/include file is being rendered directly and to pull in supporting code, that approach is not very flexible. The alternate render file feature allows a render to be started on an include file, and instead of the include file being rendered directly (as would have happened previously), the source file that most recently included that file in a render will be rendered instead. For this feature to work, you need to have rendered a file which includes the target file during the current editing session (the association between include files and source files is not persisted when POVWIN exits). Additionally you need to have requested to render a source file which does not have the .POV or .INI extension. When you request the render, a message box will appear asking you what to do. You can choose to render the alternate file this time only, to render the alternate file each time you render this one, or to render this one each time (i.e. disable the alternate file option). In all cases, the choice you give only persists for the current editing session; it is not restored when you re-launch POVWIN. this is by design.</li>
+
<p class="Note"><strong>Note:</strong> The term 'source file' means either a .POV, .INI, .MAC or .MCR file.</p>
 +
</li>
 +
<li>
 +
It is now possible for users to provide their own custom keywords for the SDL keyword completion list and syntax highlighting.
 +
These keywords are read from the file 'ini\user-keywords.txt' (located in the POVWIN documents folder) when POVWIN starts up.
 +
A tool menu entry provides a shortcut to open this for you.
 
</ol>
 
</ol>
<p class="Note"><strong>Note:</strong> The terms 'source file' mean either a .POV, .INI, .MAC or .MCR file.</p>
 
 
====The Editor Feature Set====
 
====The Editor Feature Set====
 
<p>
 
<p>
Here are just a few of the features offered by the editor, as implemented in POV-Ray for
+
Here are just a few of the features offered by the editor, as implemented in POVWIN:
Windows:
 
 
</p>
 
</p>
  
Line 248: Line 240:
  
 
<dt><strong>Keyword Completion.</strong><!--</dt>--->
 
<dt><strong>Keyword Completion.</strong><!--</dt>--->
<dd>Language-specific keywords can be automatically expanded or cycled through by pressing the <em>TAB</em> key while the caret is at the end of a partial keyword.<!--</dd>--->
+
<dd>Language-specific keywords can be automatically expanded or cycled through by pressing the <em>TAB</em> key while the caret is at the end of a partial keyword. Users can add their own keywords by editing a custom definition file.<!--</dd>--->
  
 
<dt><strong>CodeList.</strong><!--</dt>--->
 
<dt><strong>CodeList.</strong><!--</dt>--->
 
<dd>A pop-up list of keywords will appear if you press <em>Ctrl + Space</em> anywhere in the editor window. If the edit caret is over a partial keyword, the list will be scrolled appropriately.<!--</dd>--->
 
<dd>A pop-up list of keywords will appear if you press <em>Ctrl + Space</em> anywhere in the editor window. If the edit caret is over a partial keyword, the list will be scrolled appropriately.<!--</dd>--->
  
<dt><strong>User Choice Regarding End-Of-Line Behaviour.</strong><!--</dt>--->
+
<dt><strong>User Choice Regarding End-Of-Line Behavior.</strong><!--</dt>--->
<dd>Some users prefer the ability to place the edit caret beyond the end of line, while other users dislike this behaviour. You can choose either.<!--</dd>--->
+
<dd>Some users prefer the ability to place the edit caret beyond the end of line, while other users dislike this behavior. You can choose either.<!--</dd>--->
  
 
<dt><strong>Customizable Keyboard Mappings.</strong><!--</dt>--->
 
<dt><strong>Customizable Keyboard Mappings.</strong><!--</dt>--->
Line 281: Line 273:
  
 
<dt><strong>Optional Auto-Reload of Changed Files.</strong><!--</dt>--->
 
<dt><strong>Optional Auto-Reload of Changed Files.</strong><!--</dt>--->
<dd>The editor will optionally automatically reload an editor file that was changed by an external program while POVWIN didn't have the focus. It can also prompt you as to whether or not you want it reloaded (which is the default behaviour).<!--</dd>--->
+
<dd>The editor will optionally automatically reload an editor file that was changed by an external program while POVWIN didn't have the focus. It can also prompt you as to whether or not you want it reloaded (which is the default behavior).<!--</dd>--->
  
 
<dt><strong>Brace Matching</strong><!--</dt>--->
 
<dt><strong>Brace Matching</strong><!--</dt>--->
Line 290: Line 282:
  
 
<dt><strong>Tabify/Untabify</strong><!--</dt>--->
 
<dt><strong>Tabify/Untabify</strong><!--</dt>--->
<dd>You can convert text that was formatted with hard TAB characters into space-expanded form, and vice-versa.!--</dd>--->
+
<dd>You can convert text that was formatted with hard TAB characters into space-expanded form, and vice-versa.<!--</dd>--->
  
 
<dt><strong>Customizable Colors.</strong><!--</dt>--->
 
<dt><strong>Customizable Colors.</strong><!--</dt>--->
Line 305: Line 297:
  
 
<dt><strong>Editor Tab Right-Click Menu</strong><!--</dt>--->
 
<dt><strong>Editor Tab Right-Click Menu</strong><!--</dt>--->
<dd>In addition to the usual &rsquo;Copy filename to clipboard&rsquo; and &rsquo;Open containing folder&rsquo;, there are also menu entries to save the file, close it, close all but it, move the tab left and move the tab right. In addition these new entries have also been added to the window menu. There is no default key combination for moving tabs left or right as the most obvious bindings are already in use. Users can assign whatever they like to it in the editor preferences dialog. Dragging tabs left or right is not supported, and is not likely to be.<!--</dd>--->
+
<dd>In addition to the usual &rsquo;Copy filename to clipboard&rsquo; and &rsquo;Open containing folder&rsquo;, there are also menu entries to save the file, close it, close all but it, move the tab left and move the tab right. In addition these new entries have also been added to the window menu. There is no default key combination for moving tabs left or right as the most obvious bindings are already in use. Users can assign whatever they like to it in the editor preferences dialog.<!--</dd>--->
 
</dl>
 
</dl>
  
Line 330: Line 322:
  
 
====Keyword Expansion and CodeList====
 
====Keyword Expansion and CodeList====
{{#indexentry:Keyword Expansion, CodeList}}
+
{{#indexentry:Keyword Expansion}}
 +
{{#indexentry:CodeList}}
 
<p>
 
<p>
 
This facility is designed to speed up the authoring of POV-Ray scene files by allowing you to
 
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
+
quickly insert any of the standard or user-defined keywords by typing part of the word and pressing TAB (provided
 
you have the 'Overlay Keyword Expansion On Tab Key' option in the <!--<linkto "Editor Menu">Editor Menu</linkto>--->[[Documentation:Windows Section 5.1#Editor Menu|Editor Menu]]
 
you have the 'Overlay Keyword Expansion On Tab Key' option in the <!--<linkto "Editor Menu">Editor Menu</linkto>--->[[Documentation:Windows Section 5.1#Editor Menu|Editor Menu]]
 
turned on).
 
turned on).
Line 353: Line 346:
  
 
<p>
 
<p>
Now, open an editor if you don't already have one open, and position the edit cursor ('caret')
+
Now, open a .POV file in an editor if you don't already have one open, and position the edit cursor ('caret')
 
on a blank line and type the letters '<code>am</code>', then press TAB. The word '<code>ambient</code>'
 
on a blank line and type the letters '<code>am</code>', then press TAB. The word '<code>ambient</code>'
 
should now appear where you had '<code>am</code>'. Now press it again and you will see the word
 
should now appear where you had '<code>am</code>'. Now press it again and you will see the word
Line 447: Line 440:
 
<tr>
 
<tr>
 
   <td>
 
   <td>
     [[Image:WinImgCodelist.gif|center|306px<!--left--->]]
+
     [[Image:win-codelist.png|center|302px<!--left--->]]
 
   </td>
 
   </td>
 
   <td>
 
   <td>
Line 522: Line 515:
 
====Configuring the Internal Editor====
 
====Configuring the Internal Editor====
 
<p>
 
<p>
The built-in editor is extensively customizable. It utilizes syntax highlighting and understands .POV and .INC files as being in POV syntax. You can change the color settings used from the <!--<linkto "Editor Preferences">properties dialog</linkto>--->[[Documentation:Windows Section 5.1#Editor Preferences Dialog|properties dialog]] (Alt + Enter). It also has built-in syntax highlighting for C, C++, Java, Basic, Pascal, SQL, HTML and XML. Users can also add their own keywords for syntax highlighting and auto-completion in the editor. See the file <code>~ini/user-keywords.txt</code>.
+
The built-in editor is extensively customizable. It utilizes syntax highlighting and understands .POV, .INC, .MAC, and .MCR files as being in POV syntax. You can change the color settings used from the <!--<linkto "Editor Preferences">properties dialog</linkto>--->[[Documentation:Windows Section 5.1#Editor Preferences dialog|properties dialog]] (Alt + Enter). It also has built-in syntax highlighting for C, C++, Java, Basic, Pascal, SQL, HTML and XML. Users can also add their own keywords for syntax highlighting and auto-completion in the editor. See the file <code>ini\user-keywords.txt</code> located in the user's POV-Ray documents folder (or use the tool menu shortcut to open it).
 
</p>
 
</p>
  
 
=====Important Editor Notes=====
 
=====Important Editor Notes=====
 
<p>
 
<p>
One important thing to note right away is that the <!--<linkto "Editor Preferences">editor properties dialog</linkto>--->[[Documentation:Windows Section 5.1#Editor Preferences Dialog|editor properties dialog]]
+
One important thing to note right away is that the <!--<linkto "Editor Preferences">editor properties dialog</linkto>--->[[Documentation:Windows Section 5.1#Editor Preferences dialog|editor properties dialog]]
 
only allows you to set things that are implemented within the editor (remember, the editor is  
 
only allows you to set things that are implemented within the editor (remember, the editor is  
 
two components - a DLL called 'povcmax32.dll' (or similar), and another DLL which loads  
 
two components - a DLL called 'povcmax32.dll' (or similar), and another DLL which loads  
Line 564: Line 557:
 
Note that, occasionally, if the error occurs inside a macro, the displayed line/column for
 
Note that, occasionally, if the error occurs inside a macro, the displayed line/column for
 
the error will be wrong (though this is uncommon).
 
the error will be wrong (though this is uncommon).
 +
</p>
 +
=====Default Key Mappings=====
 +
<p>
 +
Listed below is the complete set of default keystrokes and the CodeMax command that each
 +
keystroke maps to. Note that many depend on caret position. If two sets of keystrokes
 +
are listed, either may be used (e.g. 'Copy' is defined as 'Ctrl + C or Ctrl + Insert', which
 +
means that you may use either 'Ctrl + C' or 'Ctrl + Insert' to perform a copy; whichever
 +
suits you. There is no difference between one or the other).
 +
</p>
 +
 +
<p>
 +
Note that if more than one key sequence is assigned to a command, and the command is one of
 +
those listed in the menus (not all commands are listed in the menus), the key sequence shown
 +
as the shortcut key in the menu is generally the shortest one (in terms of its printed
 +
representation).
 +
</p>
 +
 +
<p>
 +
You can change any of the below-mentioned key assignments if the defaults don't suit you.
 +
Additionally, the below table does not list the more than 50 commands for which there is no
 +
default key assignment. Use <em>Alt + Enter</em> on an editor screen, or select
 +
<!--<linkto "Keyboard Configuration">'Codemax Properties'</linkto>--->[[Documentation:Windows Section 5.1#Keyboard|'Codemax Properties']] from the Editor menu to assign these.
 +
</p>
 +
 +
<table width="100%" class="option-list">
 +
<tr valign="top">
 +
<td>BookmarkNext</td> <td nowrap>F2</td> <td>Move to next bookmark</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>BookmarkPrev</td> <td nowrap>Shift + F2</td> <td>Move to previous bookmark</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>BookmarkToggle</td> <td nowrap>Ctrl + F2</td> <td>Place a bookmark</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>CharLeft</td> <td nowrap>Left Arrow</td> <td>Move caret left</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>CharLeftExtend</td> <td nowrap>Shift + Left Arrow</td> <td>Move caret left and highlight</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>CharRight</td> <td nowrap>Right Arrow</td> <td>Move caret right</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>CharRightExtend</td> <td nowrap>Shift + Right Arrow</td> <td>Move caret right and highlight</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>CodeList</td> <td nowrap>Ctrl + Space</td> <td>Show keywords (reference or insertion into file)</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>Copy</td> <td nowrap>Ctrl + C or Ctrl + Insert</td> <td>Copy selection to clipboard</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>Cut</td> <td nowrap>Ctrl + X or Shift + Delete</td> <td>Remove selection to clipboard</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>CutSelection</td> <td nowrap>Ctrl + Alt + W</td> <td>Remove selection (same as Cut)</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>Delete</td> <td nowrap>Delete</td> <td>Delete one character right (can Undo)</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>DeleteBack</td> <td nowrap>Backspace or Shift + Backspace</td> <td>Remove one character left (can Undo)</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>DocumentEnd</td> <td nowrap>Ctrl + End</td> <td>Move to end of file</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>DocumentEndExtend</td> <td nowrap>Ctrl + Shift + End</td> <td>Move to end of file and highlight</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>DocumentStart</td> <td nowrap>Ctrl + Home</td> <td>Move to start of file</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>DocumentStartExtend</td> <td nowrap>Ctrl + Shift + Home</td> <td>Move to start of file and highlight</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>Find</td> <td nowrap>Alt + F3 or Ctrl + F</td> <td>Find, or search</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>FindNext</td> <td nowrap>F3</td> <td>Find next (specified)</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>FindNextWord</td> <td nowrap>Ctrl + F3</td> <td>Find next (selected)</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>FindPrev</td> <td nowrap>Shift + F3</td> <td>Find previous (specified)</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>FindPrevWord</td> <td nowrap>Ctrl + Shift + F3</td> <td>Find previous (selected)</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>FindReplace</td> <td nowrap>Ctrl + Alt + F3 or Ctrl + H</td> <td>Find/Replace dialog</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>GoToLine</td> <td nowrap>Ctrl + G</td> <td>Move to a line number dialog</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>GoToMatchBrace</td> <td nowrap>Ctrl + ]</td> <td>Match brace }, bracket ], or parenthesis )</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>Home</td> <td nowrap>Home</td> <td>Move to start of line text (or line)</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>HomeExtend</td> <td nowrap>Shift + Home</td> <td>Move to start of line and highlight</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>IndentSelection</td> <td nowrap>Tab</td> <td>Indentation (number of spaces set in properties)</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>LineCut</td> <td nowrap>Ctrl + Y</td> <td>Remove current line</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>LineDown</td> <td nowrap>Down Arrow</td> <td>Move to next line</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>LineDownExtend</td> <td nowrap>Shift + Down Arrow</td> <td>Move to next line and highlight</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>LineEnd</td> <td nowrap>End</td> <td>Move to end of line text (or line)</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>LineEndExtend</td> <td nowrap>Shift + End</td> <td>Move to end of line and highlight</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>LineOpenAbove</td> <td nowrap>Ctrl + Shift + N</td> <td>Make new line above current line</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>LineUp</td> <td nowrap>Up Arrow</td> <td>Move to previous line</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>LineUpExtend</td> <td nowrap>Shift + Up Arrow</td> <td>Move to previous line and highlight</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>LowerCaseSelection</td> <td nowrap>Ctrl + U</td> <td>Change highlighted text to lower case</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>PageDown</td> <td nowrap>Page Dn</td> <td>Move down a page</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>PageDownExtend</td> <td nowrap>Shift + Page Dn</td> <td>Move down a page and highlight</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>PageUp</td> <td nowrap>Page Up</td> <td>Move up a page</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>PageUpExtend</td> <td nowrap>Shift + Page Up</td> <td>Move up a page and highlight</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>Paste</td> <td nowrap>Ctrl + V or Shift + Insert</td> <td>Place clipboard contents into file</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>Properties</td> <td nowrap>Alt + Enter</td> <td>CodeMax properties dialog</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>RecordMacro</td> <td nowrap>Ctrl + Shift + R</td> <td>Record/stop a macro</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>Redo</td> <td nowrap>Ctrl + Y</td> <td>Redoes last undone action (i.e. undo an undo)</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>SelectAll</td> <td nowrap>Ctrl + A</td> <td>Highlight entire file</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>SelectLine</td> <td nowrap>Ctrl + Alt + F8</td> <td>Highlight the current line</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>SelectSwapAnchor</td> <td nowrap>Ctrl + Shift + X</td> <td>Switch place of caret with start of highlighting</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>SentenceCut</td> <td nowrap>Ctrl + Alt + K</td> <td>Remove a continuous line to clipboard</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>SentenceLeft</td> <td nowrap>Ctrl + Alt + Left Arrow</td> <td>Move to start of continuous line</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>SentenceRight</td> <td nowrap>Ctrl + Alt + Right Arrow</td> <td>Move to end of continuous line</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>SetRepeatCount</td> <td nowrap>Ctrl + R</td> <td>Number of times to do next command</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>TabifySelection</td> <td nowrap>Ctrl + Shift + T</td> <td>Change highlighted spaces to tabs</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>ToggleOvertype</td> <td nowrap>Insert</td> <td>Toggle between inserting and overwriting</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>ToggleWhitespaceDisplay</td> <td nowrap>Ctrl + Alt + T</td> <td>Show or hide spaces</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>Undo</td> <td nowrap>Ctrl + Z or Alt + Backspace</td> <td>Undo last change</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>UnindentSelection</td> <td nowrap>Shift + Tab</td> <td>Remove indentation of selected line</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>UntabifySelection</td> <td nowrap>Ctrl + Shift + Space</td> <td>Change highlighted tabs to spaces</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>UpperCaseSelection</td> <td nowrap>Ctrl + Shift + U</td> <td>Change highlighted text to upper case</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>WindowScrollDown</td> <td nowrap>Ctrl + Up Arrow</td> <td>Scroll file down, leaving caret</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>WindowScrollLeft</td> <td nowrap>Ctrl + Page Up</td> <td>Scroll file left, leaving caret</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>WindowScrollRight</td> <td nowrap>Ctrl + Page Dn</td> <td>Scroll file right, leaving caret</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>WindowScrollUp</td> <td nowrap>Ctrl + Down Arrow</td> <td>Scroll file up, leaving caret</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>WordDeleteToEnd</td> <td nowrap>Ctrl + Delete</td> <td>Delete a word from caret to end</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>WordDeleteToStart</td> <td nowrap>Ctrl + Backspace</td> <td>Delete a word from caret to start</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>WordLeft</td> <td nowrap>Ctrl + Left Arrow</td> <td>Move to start of current word</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>WordLeftExtend</td> <td nowrap>Ctrl + Shift + Left Arrow</td> <td>Move to start of current word and highlight</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>WordRight</td> <td nowrap>Ctrl + Right Arrow</td> <td>Move to end of current word</td>
 +
</tr>
 +
<tr valign="top">
 +
<td>WordRightExtend</td> <td nowrap>Ctrl + Shift + Right Arrow</td> <td>Move to end of current word and highlight</td>
 +
</tr>
 +
</table>
 +
 +
=====Setting Key Mappings=====
 +
<p>
 +
Most of the keystrokes used by the editor are re-assignable - even those listed in the menus.
 +
(Some users have assumed that commands with shortcuts listed in the menus aren't assignable,
 +
but this isn't the case - if you change the assignment, the new shortcut shows up in the
 +
menu).
 +
</p>
 +
 +
<p>
 +
Each editor command can have up to two different keyboard actions assigned to it, and each
 +
keyboard action may have either one or two keystrokes. Most users will use only one keystroke,
 +
but those who are still familiar and comfortable with the old 'Wordstar' key assignments (e.g.
 +
Ctrl-Q, F for Find) will be pleased to discover that these are still available to them, should
 +
they want to take the time to assign them.
 +
</p>
 +
 +
<p>
 +
If you assign more than one key sequence to a command, and the command is one of those listed
 +
in the menus (not all commands are listed in the menus), the one that is listed in the menu as
 +
the shortcut key is generally the shortest one (in terms of its printed representation).
 +
</p>
 +
 +
<p>
 +
You can access the keystroke assignments via the <!--<linkto "Editor Preferences">CodeMax properties dialog</linkto>--->[[Documentation:Windows Section 5.1#Editor Preferences dialog|CodeMax properties dialog]].
 +
By default, this is mapped to Alt+Enter when an editor is displayed. Alternatively, you can get
 +
at it from the  Editor menu (only visible when an editor is selected) or the editor right-mouse-button
 +
context menu.
 +
</p>
 +
 +
=====Reserved Keys=====
 +
<p>
 +
<strong>Not all commands are assignable !</strong > In general, only the commands that are directly
 +
implemented in the CodeMax editor DLL are able to be set. These commands are ones that relate to
 +
operations on individual edit buffers. They do not include such things as file operations
 +
(load, save, print, etc). These operations are implemented in the POVWIN editor wrapper code
 +
and are not managed or able to be changed by CodeMax. Therefore, it should be clear that you
 +
can neither change the key bindings for operations such as file save, nor use the POVWIN-
 +
assigned keystroke (e.g. Ctrl-S in the case of save) for any other purpose.
 +
</p>
 +
 +
=====Using the Mouse=====
 +
<p>
 +
The editor supports the following mouse actions:
 +
</p>
 +
 +
<table width="100%" class="option-list">
 +
<tr valign="top">
 +
<td nowrap>Left click over text</td> <td>Changes the caret position</td>
 +
</tr>
 +
<tr valign="top">
 +
<td nowrap>Right click over open file</td> <td>Displays the pop-up menu</td>
 +
</tr>
 +
<tr valign="top">
 +
<td nowrap>Left Button down over selection, hold and drag</td> <td>Moves text</td>
 +
</tr>
 +
<tr valign="top">
 +
<td nowrap>Ctrl + Left Button down over selection, hold and drag</td> <td>Copies text</td>
 +
</tr>
 +
<tr valign="top">
 +
<td nowrap>Left click over left margin</td> <td>Selects line</td>
 +
</tr>
 +
<tr valign="top">
 +
<td nowrap>Left click over left margin, hold and drag up or down</td> <td>Selects multiple lines</td>
 +
</tr>
 +
<tr valign="top">
 +
<td nowrap>Alt + Left Button down, hold and drag</td> <td>Select columns of text</td>
 +
</tr>
 +
<tr valign="top">
 +
<td nowrap>Left double click over text</td> <td>Select word under cursor</td>
 +
</tr>
 +
<tr valign="top">
 +
<td nowrap>Spin IntelliMouse (compatible) mouse wheel</td> <td>Scroll the window vertically</td>
 +
</tr>
 +
<tr valign="top">
 +
<td nowrap>Single click mouse wheel</td> <td>Select the word under the cursor</td>
 +
</tr>
 +
<tr valign="top">
 +
<td nowrap>Double click mouse wheel</td> <td>Select the line under the cursor</td>
 +
</tr>
 +
<tr valign="top">
 +
<td nowrap>Click and drag splitter bar</td> <td>Split the window into multiple views<br> or adjust the current splitter position</td>
 +
</tr>
 +
<tr valign="top">
 +
<td nowrap>Double click splitter bar</td> <td>Split the window in half into multiple views<br> or unsplit the window if already split</td>
 +
</tr>
 +
</table>
 +
 +
=====Hints for Match Brace=====
 +
<p>
 +
Several European users have commented that the default key assignment for 'Match Brace'
 +
(Ctrl-]) is not usable on their keyboards. Please note that you can change this to whatever
 +
you please. Another thing to remember about the match brace command is that it only works if it is
 +
executed when the edit caret is on a brace character ('{', '}', '(', ')', '[', ']'). The caret
 +
will then jump to the matching character (e.g. if it's on a '(', it will jump to the matching ')').
 +
</p>
 +
 +
====The Language Setting====
 +
<p>
 +
The language setting is a good example of a setting that applies to the current file only.
 +
This setting determines what sort of syntax highlighting is applied to the file. For example,
 +
a POV or INC file would probably have a language setting of 'POV-Ray'. A Java file (should you
 +
choose to use POVWIN to edit one) would have a language setting of 'Java'.
 +
</p>
 +
 +
<p>
 +
This setting is initially (when you first open a file, or create a new one) set according to
 +
the file extension. .POV, .INC, .MCR and .MAC files are considered POV syntax. A new file (one with the
 +
name 'Untitled') has no language.
 +
</p>
 +
 +
<p>
 +
Once the file is first loaded, you are free to change the language to whatever you like.
 +
<strong>This change affects only the current file and no other file !</strong> The change you have made
 +
will be remembered by POV-Ray. Any file that is still in the MRU list (or the 'Older File'
 +
list - see the <!--<linkto "File Menu">File Menu</linkto>--->[[Documentation:Windows Section 5#File Menu|File Menu]] section for more details) has its language setting stored along with a number of other file-specific attributes.
 +
</p>
 +
 +
<p>
 +
Note that if you open a file manually (using Drag-Drop or the file browse dialog, for example),
 +
the old settings are discarded, even if the file was in the MRU list. This is by design.
 +
</p>
 +
 +
====The Font Setting====
 +
<p>
 +
The Font setting is a good example of a global setting - it affects all open files. Once you
 +
change the font used in the editor, all open files get the new font, as well as any new files
 +
opened after that point.
 
</p>
 
</p>
 
<!--<wikinav>--->
 
<!--<wikinav>--->
Line 571: Line 925:
 
[[Documentation:Windows Section 1#Trademarks|Trademarks]]</td>
 
[[Documentation:Windows Section 1#Trademarks|Trademarks]]</td>
 
<td width=50% bgcolor=#EEEEEF align=right>
 
<td width=50% bgcolor=#EEEEEF align=right>
[[Documentation:Windows Section 2.1#Default Key Mappings|Default Key Mappings]]</td></tr>
+
[[Documentation:Windows Section 2.1#I/O Restrictions|I/O Restrictions]]</td></tr>
 
</table>
 
</table>
 
<!--</wikinav>--->
 
<!--</wikinav>--->

Latest revision as of 11:43, 4 July 2017

This document is protected, so submissions, corrections and discussions should be held on this documents talk page.


Getting Started

This section will help new users get started with POV-Ray for Windows.

The Demo

If you have never seen POV-Ray at work before, start by running the demo (select Render/Run Demo), then click on Start Rendering. You will see POV-Ray for Windows start up a Render Window and generate a sample scene block by block. By default, these blocks are 32x32 pixels in size. Notice that if you close the Render Window, the rendering job is not interrupted. If you have POV-Ray set up to save the image as a file (this is the default setting), that file will be produced whether or not you display the image on screen as you render. To stop rendering, select Render/Stop Rendering (or use the keyboard short-cut ALT-G).

Even if you minimize the rendering window, POV-Ray for Windows will display the progress of the rendering job by showing the percentage completed. If you close the render window and want it back, click the right mouse button over the main POV-Ray window, and select the appropriate menu item, or just click the toolbar button labelled 'Show'.

Starting a Render Job

Starting POV-Ray rendering any scene file is as simple as selecting the file through the menu (Render/Select File and Render) or dragging and dropping it from Windows Explorer. This will work with either a POV file or an INI file (as long as it has an associated POV file). See Understanding File Types. The scene is rendered with the current POV-Ray 3 options (see Command-Line Options). Note that you can tell POV-Ray for Windows to open a file in the editor instead of rendering it if you drag and drop it into the program (this is in fact the default setting now). See the Options Menu for more information.

N.B. One of the most common errors new users make is turning off the display option. The Display option (+d) is ON by default. If you turn this OFF in the INI file or on the command line, POV-Ray will not display the file as you render, no matter how many times you press the Show Render Window button. However this does not mean the rendered file is not written to disk.

Please also note that POV-Ray for Windows will write the output file to a .PNG by default. There is no way to 'save the render window' after rendering is completed. If you turned file output off before starting the render, and change your mind, you will have to start the rendering all over again. We recommend that you just leave file output on all the time.

Dragging and Dropping Files

Dragging and dropping (a.k.a. Drag'N'Drop) from Windows Explorer (a.k.a. 'My Computer') has the advantage that you can select more than one file at a time. You can drag and drop up to 512 POV and/or INI files. POV-Ray for Windows will start processing the first file in the queue and add the rest to the queue. See File Queue dialog in the Render Menu for more details.

Note: If the dropped files destination is set to Editor (the default), the files will be opened in the internal editor instead. In that case, there is a limit of 32 files that may be opened at any one time.

File Associations

When POVWIN is installed using the official installer, a file association is established between .POV files and POVWIN. This means that if you double-click on a file with the .POV extension it will be opened in POVWIN's editor. In addition, right-clicking on a .POV file to open the standard Windows context menu will show two dedicated menu entries: 'Open' and 'Render with POV-Ray'. 'Open' is the same as double-clicking (internally it calls POVWIN with the '/EDIT' option). Choosing 'Render with POV-Ray' will cause the selected file to be rendered by POVWIN (note that it is not opened in the editor - having a file open in the editor is not a requirement for rendering it).

Newer versions of Windows allow users to associate other file types with programs of their choice; e.g. as a 'default program'. As a general rule, if this is done for POVWIN and the file is double-clicked, POVWIN will open it in the editor rather than render it (which would otherwise be the default, for compatibility with versions of POV-Ray for other platforms). If you want to associate a file extension with POVWIN in order to render it rather than edit it, you'll need to change the association to pass the /RENDER command-line option Documenting how to change windows to include this is beyond the scope of this tutorial.

Tutorials

There is a comprehensive beginner's tutorial included in this help file. It relates to the use of POV-Ray in general (i.e. on all platforms, not only Windows), so we recommend that you read the rest of section 1 first before attempting to go any further, as section 1 tells you how to use the interface of POV-Ray for Windows itself. The more ambitious may like to check out the advanced tutorial section.

Understanding File Types

This section points out the various types of text files that POV-Ray for Windows works with.

POV Files

POV-Ray for Windows works with two types of plain text files. The first is the standard POV-Ray scene description file (also known as 'SDL', for Scene Description Language). Although you may give files of this type any legitimate extension, it is more convenient for you if you name them using the .POV extension. In this Help file, scene description files are referred to as POV files.

The second type, the initialization file, normally have .INI extensions and are referred to in this help file as INI files.

INI Files

An INI file is a text file containing settings that instruct POV-Ray how to render a scene. These settings are different from what is in the POV file, which contains instructions to POV-Ray about what is in a scene.

You can store a default set of options in the file called POVRAY.INI in the INI folder under the POV-Ray documents folder. Unless you chose to install the user-specific files elsewhere when you installed, this will be (for example) 'POV-Ray\vX.y\ini\povray.ini' within your 'My Documents' folder. There is a command in the Tools menu that allows you to open this directly (regardless of where you installed).

You can also pass any other INI file to POV-Ray for Windows by selecting it (through Render/Select File and Render) or by dragging it from the Windows File Manager and dropping it onto the POV-Ray window.

One of the options you can set in any INI file is the name of an input file. If you now instruct POVRAY to render the INI file, it will use the above option to determine what POV file to read to generate the actual image. Any other options provided in the INI file will also be applied to the image; hence this way you can customize POV-Ray settings for any individual scene file without having to type them in each time.

For instance, if you have a file called SCENE.POV, you can create a file SCENE.INI to contain settings specific for SCENE.POV. If you include the option 'Input_File_Name=scene.pov' in SCENE.INI, and then ask POV-Ray to render SCENE.INI, POV-Ray will process SCENE.POV with the options specified in SCENE.INI.

Remember, though, that any options set at the POV-Ray for Windows command line when you process an INI file override any corresponding options in the INI file (see Command-line Options and Render Menu). Also, any options you do not set in the INI file will be inherited from any previously-processed INI files (e.g. POVRAY.INI).

You can instruct POV-Ray to generate an INI file containing all the options active at the time of rendering. This way, you can pass a POV file and its associated INI file on to another person and be confident that they will be able to generate the scene exactly the same way you did. See the section titled Using INI Files for more information about INI files.

INI File Sections

Sections are not files in themselves; they are portions of INI files. Sections are a means of grouping multiple sets of POV-Ray options together in a single INI file, by introducing them with a section label. Consider the following INI file, taken from the POV-Ray 3 documentation:

; RES.INI
; This sample INI file is used to set resolution.

+W120 +H100 ; This section has no label.
; Select it with "RES"

[Low]
+W80 +H60 ; This section has a label.
; Select it with "RES[Low]"

[Med]
+W320 +H200 ; This section has a label.
; Select it with "RES[Med]"

[High]
+W640 +H480 ; Labels are not case sensitive.
; "RES[high]" works

[Really High]
+W800 +H600 ; Labels may contain blanks

If you select this INI file, the default resolution setting will be 120 x 100. As soon as you select the [High] section, however, the resolution becomes 640 x 480. See Edit Settings/Render in the Render Menu for instructions on selecting sections. The 'quick resolution' listbox in POVWIN is an example of this type of file. For more information on POV-Ray options and INI files consult the section on POV-Ray Options.

Using the Internal Editor

The POV-Ray internal editor is an advanced programmer's editor, offering syntax highlighting for POV files (as well as C, Java, and a number of other languages), several indent styles, block indent/undent, column selections, OLE drag and drop, amongst other things. Most of the key mappings are configurable, as are the colors and a number of other options.

It consists of two parts - a custom control, and the 'wrapper' code that encapsulates it. It's important that you remember this, as it will explain some of the behavior that it exhibits (for example, not being able to reassign all keystrokes, just most of them). It is not essential for POVWIN's operation to have the editor present - it is quite possible for it to run without it. However, under normal circumstances, the editor is present.

As of version 3.7 there been a few notable changes to the POVWIN IDE.

  1. There is now a Window menu, which is located where the GUIEXT menu used to be (the latter has moved to within the Options menu). The MRU (most-recently-used) arrangement of this window menu makes it trivial to toggle between files without taking your eyes off the text or using the mouse. The most recently view window (i.e. the current one) will always be entry 1 in the list. The second most recently viewed (i.e. the last window viewed before switching to the current one) will always be entry 2 in the list, and so forth. Given that entries 1 through 10 in the list are given the menu mnemonics 1 through 0 respectively, all you need to do to toggle between the current and previous files is hit Alt-W then 2. To go to the third oldest, Alt-W then 3, and so forth. Note that the MRU list is not saved on exit.
  2. An 'alternate render file' feature was added. This is intended to make things easier when editing macro or include files. While it is possible to use SDL to detect whether a macro/include file is being rendered directly and to pull in supporting code, that approach is not very flexible. The alternate render file feature allows a render to be started on an include file, and instead of the include file being rendered directly (as would have happened previously), the source file that most recently included that file in a render will be rendered instead. For this feature to work, you need to have rendered a file which includes the target file during the current editing session (the association between include files and source files is not persisted when POVWIN exits). Additionally you need to have requested to render a source file which does not have the .POV or .INI extension. When you request the render, a message box will appear asking you what to do. You can choose to render the alternate file this time only, to render the alternate file each time you render this one, or to render this one each time (i.e. disable the alternate file option). In all cases, the choice you give only persists for the current editing session; it is not restored when you re-launch POVWIN. this is by design.

    Note: The term 'source file' means either a .POV, .INI, .MAC or .MCR file.

  3. It is now possible for users to provide their own custom keywords for the SDL keyword completion list and syntax highlighting. These keywords are read from the file 'ini\user-keywords.txt' (located in the POVWIN documents folder) when POVWIN starts up. A tool menu entry provides a shortcut to open this for you.

The Editor Feature Set

Here are just a few of the features offered by the editor, as implemented in POVWIN:

Color Syntax Highlighting.
Language-specific keywords, comments, and strings are colored differently to set them apart from plain text.
Keyword Completion.
Language-specific keywords can be automatically expanded or cycled through by pressing the TAB key while the caret is at the end of a partial keyword. Users can add their own keywords by editing a custom definition file.
CodeList.
A pop-up list of keywords will appear if you press Ctrl + Space anywhere in the editor window. If the edit caret is over a partial keyword, the list will be scrolled appropriately.
User Choice Regarding End-Of-Line Behavior.
Some users prefer the ability to place the edit caret beyond the end of line, while other users dislike this behavior. You can choose either.
Customizable Keyboard Mappings.
Keystrokes can be added and removed to emulate popular keyboard mappings. Over 120 individual commands are able to be assigned to the keyboard.
Keystroke Macros.
Users can record a series of keystrokes and assign a keystroke to play back the keystrokes repeatedly. Up to 10 macros may be recorded. These are preserved across editing sessions.
Drag and Drop Text Manipulation.
Highlighted text can be dragged and dropped between any window supporting OLE text Drag and Drop. Text may be copied or moved.
Column Selection and Manipulation.
Columns of text can be selected with the mouse and then manipulated. Empty columns (columns with a width of zero characters) can be selected, causing subsequent typing and deletion to occur over multiple lines at the same time.
Multiple Split Views.
Users can create up to four separate views of the same edit buffer. Each view can be scrolled independently.
Unlimited Undo/Redo.
All edit actions are fully undoable and redoable. A limit can be set on the number of edit actions that may be undone.
Auto Indentation.
Once a language is chosen, as the user enters code, CodeMax will automatically indent lines to following the scoping rules of the language.
Optional Auto-Save.
If turned on, changed files are saved periodically.
Optional Auto-Reload of Changed Files.
The editor will optionally automatically reload an editor file that was changed by an external program while POVWIN didn't have the focus. It can also prompt you as to whether or not you want it reloaded (which is the default behavior).
Brace Matching
Pressing the Ctrl + ] key while the edit caret is on a ’[’, ’(’ or ’{’ will cause the caret to jump to the matching ’]’, ’)’ or ’}’, and vice-versa.
Block Indent/Undent
Pressing the TAB or Shift + Tab keys will indent or unindent a selected block of text.
Tabify/Untabify
You can convert text that was formatted with hard TAB characters into space-expanded form, and vice-versa.
Customizable Colors.
All editor colors (including the background) are customizable. POVWIN also provides two ’quick set’ defaults - white text on a black background and black text on a white background.
Smart Case Preservation in Replace Operations.
During search and replace, you can optionally have the replaced text retain its original case.
Enhanced MRU (Most Recently Used files) List
POVWIN's MRU list not only recalls the filenames of recently opened files, it also remembers the the line, column, and language settings.
Keyword Expansion and CodeList
This feature allows fast insertion of standard POV-Ray keywords either by typing a partial match and hitting TAB, or by using Ctrl + Space to bring up a complete list.
Editor Tab Right-Click Menu
In addition to the usual ’Copy filename to clipboard’ and ’Open containing folder’, there are also menu entries to save the file, close it, close all but it, move the tab left and move the tab right. In addition these new entries have also been added to the window menu. There is no default key combination for moving tabs left or right as the most obvious bindings are already in use. Users can assign whatever they like to it in the editor preferences dialog.

Turning the Internal Editor On or Off

Select the Options|Other Settings|Use Editor menu item. If this is off, POV-Ray for Windows will not attempt to load the editor DLL at startup, and the editors will not be available.

Preventing File Restore

By default, POV-Ray for Windows will attempt to re-load the files you had open in the editor when you last exited the program. If this causes a problem (e.g. maybe one of the files is very large and you don't want it re-loaded), you can add the '/NR' (or '/NORESTORE') option to the POV-Ray for Windows command line. In this case POVWIN will flush the list of files you had opened.

Switching between Editor windows

You can use the Alt+LeftArrow and Alt+RightArrow keys to cycle amongst the editor windows and the message window. Some users are more comfortable with Ctrl-Tab, so this is available as well.

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 or user-defined 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 a .POV file in 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 comparison 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
win-codelist.png

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.

CodeList keyword expansion

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.

Configuring the Internal Editor

The built-in editor is extensively customizable. It utilizes syntax highlighting and understands .POV, .INC, .MAC, and .MCR files as being in POV syntax. You can change the color settings used from the properties dialog (Alt + Enter). It also has built-in syntax highlighting for C, C++, Java, Basic, Pascal, SQL, HTML and XML. Users can also add their own keywords for syntax highlighting and auto-completion in the editor. See the file ini\user-keywords.txt located in the user's POV-Ray documents folder (or use the tool menu shortcut to open it).

Important Editor Notes

One important thing to note right away is that the editor properties dialog only allows you to set things that are implemented within the editor (remember, the editor is two components - a DLL called 'povcmax32.dll' (or similar), and another DLL which loads and 'wraps' it into POV-Ray for Windows). There are some other options implemented within the editor wrapper code in POV-Ray for Windows which are able to be accessed via the Editor menu (only visible when an editor is selected). For example, the keybinding for saving a file (Ctrl-S) is not listed in the editor properties since this function is handled by the wrapper code. You can't change this assignment.

Some people have asked why the don't ask again option in the render save dialog is not persistent across sessions. This is by design and is not likely to change.

The edit window context menu has an option for 'show/hide message window'. This window - when displayed at the bottom of an editor window - is sizable. A quick way to close the message window is just to hit ESCAPE, or drag the divider down to within a few pixels of the bottom border - when you release the mouse, the message window will vanish.

You can also tell POVWIN not to display the message window automatically when starting a render. You do this from the Editor menu, by turning off 'Auto-Show Parse Messages'. This is most useful with the Error File option.

POVWIN will optionally automatically load a file in which a parse error has occurred into the editor (or select it if it's already loaded) and place the cursor on the line and column of the offending code. This is able to be turned on or off using the 'Auto-Load Error File' option in the Editor menu. Also, if this option is on, and the message window was displayed automatically (see above), it will be closed automatically rather than being left open. The text describing the error will be displayed in the status bar at the bottom of the window. Note that, occasionally, if the error occurs inside a macro, the displayed line/column for the error will be wrong (though this is uncommon).

Default Key Mappings

Listed below is the complete set of default keystrokes and the CodeMax command that each keystroke maps to. Note that many depend on caret position. If two sets of keystrokes are listed, either may be used (e.g. 'Copy' is defined as 'Ctrl + C or Ctrl + Insert', which means that you may use either 'Ctrl + C' or 'Ctrl + Insert' to perform a copy; whichever suits you. There is no difference between one or the other).

Note that if more than one key sequence is assigned to a command, and the command is one of those listed in the menus (not all commands are listed in the menus), the key sequence shown as the shortcut key in the menu is generally the shortest one (in terms of its printed representation).

You can change any of the below-mentioned key assignments if the defaults don't suit you. Additionally, the below table does not list the more than 50 commands for which there is no default key assignment. Use Alt + Enter on an editor screen, or select 'Codemax Properties' from the Editor menu to assign these.

BookmarkNext F2 Move to next bookmark
BookmarkPrev Shift + F2 Move to previous bookmark
BookmarkToggle Ctrl + F2 Place a bookmark
CharLeft Left Arrow Move caret left
CharLeftExtend Shift + Left Arrow Move caret left and highlight
CharRight Right Arrow Move caret right
CharRightExtend Shift + Right Arrow Move caret right and highlight
CodeList Ctrl + Space Show keywords (reference or insertion into file)
Copy Ctrl + C or Ctrl + Insert Copy selection to clipboard
Cut Ctrl + X or Shift + Delete Remove selection to clipboard
CutSelection Ctrl + Alt + W Remove selection (same as Cut)
Delete Delete Delete one character right (can Undo)
DeleteBack Backspace or Shift + Backspace Remove one character left (can Undo)
DocumentEnd Ctrl + End Move to end of file
DocumentEndExtend Ctrl + Shift + End Move to end of file and highlight
DocumentStart Ctrl + Home Move to start of file
DocumentStartExtend Ctrl + Shift + Home Move to start of file and highlight
Find Alt + F3 or Ctrl + F Find, or search
FindNext F3 Find next (specified)
FindNextWord Ctrl + F3 Find next (selected)
FindPrev Shift + F3 Find previous (specified)
FindPrevWord Ctrl + Shift + F3 Find previous (selected)
FindReplace Ctrl + Alt + F3 or Ctrl + H Find/Replace dialog
GoToLine Ctrl + G Move to a line number dialog
GoToMatchBrace Ctrl + ] Match brace }, bracket ], or parenthesis )
Home Home Move to start of line text (or line)
HomeExtend Shift + Home Move to start of line and highlight
IndentSelection Tab Indentation (number of spaces set in properties)
LineCut Ctrl + Y Remove current line
LineDown Down Arrow Move to next line
LineDownExtend Shift + Down Arrow Move to next line and highlight
LineEnd End Move to end of line text (or line)
LineEndExtend Shift + End Move to end of line and highlight
LineOpenAbove Ctrl + Shift + N Make new line above current line
LineUp Up Arrow Move to previous line
LineUpExtend Shift + Up Arrow Move to previous line and highlight
LowerCaseSelection Ctrl + U Change highlighted text to lower case
PageDown Page Dn Move down a page
PageDownExtend Shift + Page Dn Move down a page and highlight
PageUp Page Up Move up a page
PageUpExtend Shift + Page Up Move up a page and highlight
Paste Ctrl + V or Shift + Insert Place clipboard contents into file
Properties Alt + Enter CodeMax properties dialog
RecordMacro Ctrl + Shift + R Record/stop a macro
Redo Ctrl + Y Redoes last undone action (i.e. undo an undo)
SelectAll Ctrl + A Highlight entire file
SelectLine Ctrl + Alt + F8 Highlight the current line
SelectSwapAnchor Ctrl + Shift + X Switch place of caret with start of highlighting
SentenceCut Ctrl + Alt + K Remove a continuous line to clipboard
SentenceLeft Ctrl + Alt + Left Arrow Move to start of continuous line
SentenceRight Ctrl + Alt + Right Arrow Move to end of continuous line
SetRepeatCount Ctrl + R Number of times to do next command
TabifySelection Ctrl + Shift + T Change highlighted spaces to tabs
ToggleOvertype Insert Toggle between inserting and overwriting
ToggleWhitespaceDisplay Ctrl + Alt + T Show or hide spaces
Undo Ctrl + Z or Alt + Backspace Undo last change
UnindentSelection Shift + Tab Remove indentation of selected line
UntabifySelection Ctrl + Shift + Space Change highlighted tabs to spaces
UpperCaseSelection Ctrl + Shift + U Change highlighted text to upper case
WindowScrollDown Ctrl + Up Arrow Scroll file down, leaving caret
WindowScrollLeft Ctrl + Page Up Scroll file left, leaving caret
WindowScrollRight Ctrl + Page Dn Scroll file right, leaving caret
WindowScrollUp Ctrl + Down Arrow Scroll file up, leaving caret
WordDeleteToEnd Ctrl + Delete Delete a word from caret to end
WordDeleteToStart Ctrl + Backspace Delete a word from caret to start
WordLeft Ctrl + Left Arrow Move to start of current word
WordLeftExtend Ctrl + Shift + Left Arrow Move to start of current word and highlight
WordRight Ctrl + Right Arrow Move to end of current word
WordRightExtend Ctrl + Shift + Right Arrow Move to end of current word and highlight
Setting Key Mappings

Most of the keystrokes used by the editor are re-assignable - even those listed in the menus. (Some users have assumed that commands with shortcuts listed in the menus aren't assignable, but this isn't the case - if you change the assignment, the new shortcut shows up in the menu).

Each editor command can have up to two different keyboard actions assigned to it, and each keyboard action may have either one or two keystrokes. Most users will use only one keystroke, but those who are still familiar and comfortable with the old 'Wordstar' key assignments (e.g. Ctrl-Q, F for Find) will be pleased to discover that these are still available to them, should they want to take the time to assign them.

If you assign more than one key sequence to a command, and the command is one of those listed in the menus (not all commands are listed in the menus), the one that is listed in the menu as the shortcut key is generally the shortest one (in terms of its printed representation).

You can access the keystroke assignments via the CodeMax properties dialog. By default, this is mapped to Alt+Enter when an editor is displayed. Alternatively, you can get at it from the Editor menu (only visible when an editor is selected) or the editor right-mouse-button context menu.

Reserved Keys

Not all commands are assignable ! In general, only the commands that are directly implemented in the CodeMax editor DLL are able to be set. These commands are ones that relate to operations on individual edit buffers. They do not include such things as file operations (load, save, print, etc). These operations are implemented in the POVWIN editor wrapper code and are not managed or able to be changed by CodeMax. Therefore, it should be clear that you can neither change the key bindings for operations such as file save, nor use the POVWIN- assigned keystroke (e.g. Ctrl-S in the case of save) for any other purpose.

Using the Mouse

The editor supports the following mouse actions:

Left click over text Changes the caret position
Right click over open file Displays the pop-up menu
Left Button down over selection, hold and drag Moves text
Ctrl + Left Button down over selection, hold and drag Copies text
Left click over left margin Selects line
Left click over left margin, hold and drag up or down Selects multiple lines
Alt + Left Button down, hold and drag Select columns of text
Left double click over text Select word under cursor
Spin IntelliMouse (compatible) mouse wheel Scroll the window vertically
Single click mouse wheel Select the word under the cursor
Double click mouse wheel Select the line under the cursor
Click and drag splitter bar Split the window into multiple views
or adjust the current splitter position
Double click splitter bar Split the window in half into multiple views
or unsplit the window if already split
Hints for Match Brace

Several European users have commented that the default key assignment for 'Match Brace' (Ctrl-]) is not usable on their keyboards. Please note that you can change this to whatever you please. Another thing to remember about the match brace command is that it only works if it is executed when the edit caret is on a brace character ('{', '}', '(', ')', '[', ']'). The caret will then jump to the matching character (e.g. if it's on a '(', it will jump to the matching ')').

The Language Setting

The language setting is a good example of a setting that applies to the current file only. This setting determines what sort of syntax highlighting is applied to the file. For example, a POV or INC file would probably have a language setting of 'POV-Ray'. A Java file (should you choose to use POVWIN to edit one) would have a language setting of 'Java'.

This setting is initially (when you first open a file, or create a new one) set according to the file extension. .POV, .INC, .MCR and .MAC files are considered POV syntax. A new file (one with the name 'Untitled') has no language.

Once the file is first loaded, you are free to change the language to whatever you like. This change affects only the current file and no other file ! The change you have made will be remembered by POV-Ray. Any file that is still in the MRU list (or the 'Older File' list - see the File Menu section for more details) has its language setting stored along with a number of other file-specific attributes.

Note that if you open a file manually (using Drag-Drop or the file browse dialog, for example), the old settings are discarded, even if the file was in the MRU list. This is by design.

The Font Setting

The Font setting is a good example of a global setting - it affects all open files. Once you change the font used in the editor, all open files get the new font, as well as any new files opened after that point.


Trademarks I/O Restrictions


This document is protected, so submissions, corrections and discussions should be held on this documents talk page.