Difference between revisions of "Documentation:Windows Section 2.1"

From POV-Wiki
Jump to navigation Jump to search
m (Protected "Documentation:Windows Section 2.1" [edit=sysop:move=sysop])
m (generic version)
 
(22 intermediate revisions by 4 users not shown)
Line 7: Line 7:
 
<br>
 
<br>
 
<!--</wikitalk>--->
 
<!--</wikitalk>--->
===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 <i>Alt + Enter</i> 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%">
 
<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%">
 
<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 IntelliMouse mouse wheel</td> <td>Select the word under the cursor</td>
 
</tr>
 
<tr valign="top">
 
<td nowrap>Double click IntelliMouse 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>
 
 
===European Users and 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 (they assumed that it was not changeable when, in fact, it is).
 
</p>
 
 
<p>
 
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>
 
 
===Global vs. Local Options===
 
<p>
 
It's important to understand that many of the options that are accessible via the CodeMax
 
properties dialog (Alt + Enter by default), apply to the current file only. Some, however, apply
 
to all files, and some apply to the current file and all new files opened after that point.
 
Confused yet ? ;). We'll explain more.
 
</p>
 
 
<p>
 
In most cases it should be obvious whether an option is global or not. As a quick summary, the
 
options in the 'Misc' tab of the CodeMax properties dialog are all global. The ones in the
 
'Language/Tabs' section are as explained above, except 'Convert tabs to spaces while typing',
 
which is global, and 'Indent style', which is local and sets a new default. Those in the
 
'Color/Font' section are global. Finally, key assignments are obviously global to all editors
 
(see the key assignment section above for caveats)
 
</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 and .INC 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.
 
<b>This change affects only the current file and no other file !</b> 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 attributes (such as tab size).
 
</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 Tab Spacing Setting===
 
<p>
 
The Tab spacing setting is a good example of a setting that applies to only the current file
 
and to any new files opened after that point. Like the language setting, it applies only to
 
the current file. That is, changing the tab spacing for one file does not automatically change
 
it for all the other files that are already open. Like the language setting, a files tab
 
setting is stored with the MRU list, so if you re-open a file from the MRU list, the old
 
setting comes back.
 
</p>
 
 
<p>
 
Unlike the Language setting, however, the new value you apply to the tab value becomes the
 
default for any file opened or created after that point (apart from those in the MRU list). So
 
if you change the tab setting to, say, 3, the setting for the current file changes, but not
 
that of any other open file. Any new file that you create or load from that point, however,
 
will be created with a default tab spacing of 3.
 
</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>
 
 
 
===I/O Restrictions===
 
===I/O Restrictions===
<!--<indexentry primary "I/O Restrictions" "Restrictions, Input/Output" "Security, File I/O" "File I/O, restrictions">--->
+
{{#indexentry:I/O Restrictions}}
 +
{{#indexentry:Restrictions, Input/Output}}
 +
{{#indexentry:Security, File I/O}}
 +
{{#indexentry:File I/O, restrictions}}
 
<p>
 
<p>
I/O Restrictions are a feature introduced in POV-Ray for Windows 3.5. The purpose of this feature
+
I/O Restrictions are a feature introduced in POV-Ray v3.5. The purpose of this feature
 
is to attempt to at least partially protect a machine running POV-Ray from having files
 
is to attempt to at least partially protect a machine running POV-Ray from having files
 
read or written outside of a given set of directories.
 
read or written outside of a given set of directories.
Line 434: Line 35:
 
The I/O Restriction facility hooks the file open and creation functions in the core POV-Ray
 
The I/O Restriction facility hooks the file open and creation functions in the core POV-Ray
 
renderer code, and allows the Windows version to allow or deny any particular file operation.
 
renderer code, and allows the Windows version to allow or deny any particular file operation.
Please note that this only affects file I/O from the <b>core</b> POV-Ray code; that is, the  
+
Please note that this only affects file I/O from the <strong>core</strong> POV-Ray code; that is, the  
code that implements the parser and renderer. It does <i>not</i> affect which files the  
+
code that implements the parser and renderer. It does <em>not</em> affect which files the  
 
Windows interface can read and write. That is to say, it does not prevent you loading a file  
 
Windows interface can read and write. That is to say, it does not prevent you loading a file  
 
into an editor, or saving a file from the editor, or any other feature implemented on the  
 
into an editor, or saving a file from the editor, or any other feature implemented on the  
Line 448: Line 49:
 
it that causes it to malfunction. Therefore, the onus is on the person who chooses to load an  
 
it that causes it to malfunction. Therefore, the onus is on the person who chooses to load an  
 
INI or scene file into POV-Ray to ensure that it does not do anything that it should not do.  
 
INI or scene file into POV-Ray to ensure that it does not do anything that it should not do.  
Please consider I/O Restrictions just a sometimes-helpful backup for manual checks.
+
I/O Restrictions are just a sometimes-helpful backup for manual checks.
 
</p>
 
</p>
  
Line 456: Line 57:
 
</p>
 
</p>
  
===High-Level Configuration===
+
====High-Level Configuration====
<p>
+
<p>Now to the details: how to configure the I/O Restrictions (or get them out of your hair if you want them turned off).
Now to the details: how to configure the I/O Restrictions (or get them out of your hair if
+
Under the Options menu there is a sub-menu called <em>Script I/O Restrictions</em>.</p>
you want them turned off).
 
</p>
 
  
<p>
+
<table class="centered" width="700x" cellpadding="0" cellspacing="10">
[[Image:WinImgMenusRestrictions.gif|-]]
+
<tr>
</p>
+
  <td>
 +
    [[Image:win-iorestrictions.png|center|427px<!--centered--->]]
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td>
 +
    <p class="caption">Script I/O Restrictions sub-menu</p>
 +
  </td>
 +
</tr>
 +
</table>
  
 
<p>
 
<p>
Under the Options menu there is a sub-menu called 'Script I/O Restrictions'. This provides
+
This provides you with high-level control of the restriction subsystem. The top section of the menu provides you with three options (detailed below). You can only choose one of the three. The bottom section provides you with two additional options, either of which can be on or off.</p>
you with high-level control of the restriction subsystem. The top section of the menu
 
provides you with three options (detailed below). You can only choose one of the three.
 
The bottom section provides you with two additional options, either of which can be on
 
or off.
 
</p>
 
  
===Overall Options===
+
====Overall Options====
  
===No Restrictions===
+
====No Restrictions====
 
<p>
 
<p>
 
If this option is chosen, POV scripts can read/write everything (subject to operating
 
If this option is chosen, POV scripts can read/write everything (subject to operating
Line 482: Line 85:
 
</p>
 
</p>
  
===Restrict Write but Allow Read===
+
====Restrict Write but Allow Read====
 
<p>
 
<p>
 
If this option is chosen. POV scripts can read anything, but file creation and file write
 
If this option is chosen. POV scripts can read anything, but file creation and file write
is only allowed in the specified directories (see <!--<linkto "Low-Level Configuration">Low-Level Configuration</linkto>--->[[Documentation:Windows Section 2.1#Low-Level Configuration|Low-Level Configuration]]
+
is only allowed in the implicit and user-specified directories (see <!--<linkto "Low-Level Configuration">Low-Level Configuration</linkto>--->[[Documentation:Windows Section 2.1#Low-Level Configuration|Low-Level Configuration]]
 
for more information on how to specify which directories).
 
for more information on how to specify which directories).
 
</p>
 
</p>
Line 494: Line 97:
 
</p>
 
</p>
  
===Restrict Read/Write===
+
====Restrict Read/Write====
 
<p>
 
<p>
Both read and write by POV scripts is restricted to specified directories. Note that
+
Both read and write by POV scripts is restricted to implicit and user-specified directories. Note that
 
this is the default setting for a clean installation of POV-Ray for Windows.
 
this is the default setting for a clean installation of POV-Ray for Windows.
 
</p>
 
</p>
  
===Restrictions Affect all Core File I/O===
+
====Restrictions Affect all Core File I/O====
 
<p>
 
<p>
 
Note that the above settings do not just affect scripted file I/O; they also affect things  
 
Note that the above settings do not just affect scripted file I/O; they also affect things  
 
like include files, output files, and input .POV files. Basically any file-related input or  
 
like include files, output files, and input .POV files. Basically any file-related input or  
output by the rendering engine. You should take <b>careful note</b> of this statement if you  
+
output by the rendering engine. You should take <strong>careful note</strong> of this statement if you  
 
are in the habit of writing your output files to anywhere other than the same directory as the  
 
are in the habit of writing your output files to anywhere other than the same directory as the  
 
scene file is in (see below).
 
scene file is in (see below).
 
</p>
 
</p>
  
===Additional Options===
+
====Additional Options====
 
<p>
 
<p>
 
In addition to the above, there are two other options:
 
In addition to the above, there are two other options:
 
</p>
 
</p>
  
===Permit Read/Write in Current Directory===
+
====Permit Read/Write in Current Directory====
 
<p>
 
<p>
 
If turned on, the current directory (but not any below it) is automatically added to the  
 
If turned on, the current directory (but not any below it) is automatically added to the  
Line 524: Line 127:
  
 
<p>
 
<p>
Please note that having this option unchecked does <i>not</i> prevent read in the current
+
Please note that having this option unchecked does <em>not</em> prevent read in the current
 
directory if you have turned off read restrictions (as documented above), and nor will it
 
directory if you have turned off read restrictions (as documented above), and nor will it
 
prevent writing if you have turned off I/O Restrictions altogether. Also, turning it on
 
prevent writing if you have turned off I/O Restrictions altogether. Also, turning it on
Line 530: Line 133:
 
</p>
 
</p>
  
===Disable Starting other Programs===
+
====Disable Starting other Programs====
 
<p>
 
<p>
 
If this option is selected (the default), shell-outs will not be permitted. 'Shell Outs'
 
If this option is selected (the default), shell-outs will not be permitted. 'Shell Outs'
 
are a facility where an INI file can specify that a particular program be run either before
 
are a facility where an INI file can specify that a particular program be run either before
or after a frame is rendered. If you want these, you have to explicitly allow them by
+
or after a frame is rendered as well as at other points in the parse/render process.
unchecking this option.
+
If you want these, you have to explicitly allow them by unchecking this option.
 
</p>
 
</p>
  
===Low-Level Configuration===
+
====Low-Level Configuration====
 
<p>
 
<p>
 
This section tells you how to manually specify explicit directories for read/write access,
 
This section tells you how to manually specify explicit directories for read/write access,
Line 545: Line 148:
 
</p>
 
</p>
  
===Overall Concept===
+
====Overall Concept====
 
<p>
 
<p>
The overall concept of the I/O Restrictions, when enabled, is that everything is denied
+
The overall concept of the I/O Restrictions, when enabled, is that everything should be denied
 
unless it is explicitly allowed (with one or two exceptions). So unless you add a directory
 
unless it is explicitly allowed (with one or two exceptions). So unless you add a directory
to the 'allowed' list, unless it is the current directory and the 'Permit Read/Write in Current
+
to the 'allowed' list, unless it is one of the implicitly allowed locations then the directory
Directory' option is checked, then the directory in question is not permitted to be accessed.
+
in question is not permitted to be accessed.
 
</p>
 
</p>
  
 +
====Implicitly Permitted Locations====
 
<p>
 
<p>
The exceptions are as follows:
+
The exceptions to the 'deny everything' rule (referred to above as 'implicit' locations) are as follows:
 
</p>
 
</p>
  
 
<ol>
 
<ol>
<li>The installation directory of POV-Ray for Windows (as given by the registry) is permitted
+
<li>
to be used for read (but not write). This includes all subdirectories of the install directory
+
The document installation directory of POV-Ray for Windows (as given by the registry or otherwise
(except as below). Note that you can alter this setting if you like.
+
determined at run-time) is permitted to be used for read (but not write). This includes all of its
 +
subdirectories (except as below). Note that you can alter this setting if you like.
 +
</li>
 +
<li>
 +
Write is permitted to the 'Insert Menu' sub-directory within the POV-Ray documents install directory.
 +
This is to enable the 'Re-render Insert Menu Bitmaps' feature to function without needing to modify the restrictions.
 +
</li>
 +
<li>
 +
Read is permitted from the Windows 'Fonts' directory. This is to allow TTF files to be read, as
 +
POV-Ray's portable rendering engine has its own TTF parser. (The Fonts directory is also added to
 +
the include path automatically).
 +
</li>
 +
</ol>
  
<li>The INI subdirectory contained within the POV-Ray for Windows install directory, as given
+
====Adding or Changing Allowed Directories====
by the registry, is permanently write-protected (unless the I/O Restriction system is turned
+
<p class="Note"><strong>Note:</strong> The INI subdirectory contained within the document install directory is permanently write-protected
off). Even if you grant permission to write this dir from the below INI file, writes will not
+
(unless the I/O Restriction system is turned off). Even if you grant permission to write this dir from  
succeed. This is to prevent the INI file that contains the I/O Restriction configuration from
+
he below INI file, writes will not succeed. This is to prevent the INI file that contains the I/O Restriction
being modified by a script to grant itself more access next time POVWIN is run.
+
configuration from being modified by a script to grant itself more access next time POVWIN is run.</p>
</ol>
 
  
===Adding or Changing Allowed Directories===
 
 
<p>
 
<p>
 
To add or change allowed directories, you'll need to modify the file <code>&lt;installdir&gt;\ini\pvengine.ini</code>,
 
To add or change allowed directories, you'll need to modify the file <code>&lt;installdir&gt;\ini\pvengine.ini</code>,
where <code>&lt;installdir&gt;</code> is where you installed POV-Ray for Windows. An easy way
+
where <code>&lt;installdir&gt;</code> is where the POV-Ray for Windows user-editable files where installed. An easy way
 
to get at this file is to select it from the tools menu (by default, it is the second item).
 
to get at this file is to select it from the tools menu (by default, it is the second item).
 
</p>
 
</p>
  
 
<p>
 
<p>
Within <code>PVENGINE.INI</code> you ought to see two sections like the following ... (note
+
Within <code>PVENGINE.INI</code> you may see two sections like the following ... (note
that the actual contents of the installed version are slightly different from this example)
+
that the actual contents of the installed version are slightly different from this example).
 
</p>
 
</p>
  
Line 590: Line 204:
  
 
<p>
 
<p>
<code>%INSTALLDIR%</code> resolves to the location that POV was installed. It would be
+
If they are not present, it means that POVWIN is using the defaults, in which case you may add them. For
 +
example, %INSTALLDIR% is implicitly allowed for input and does not need to be added to the INI file (though
 +
there is no harm in doing so).
 +
</p>
 +
<p>
 +
<code>%INSTALLDIR%</code> resolves to the location that the POVWIN user-editable files were installed. It would be
 
legal to say something like -
 
legal to say something like -
 
</p>
 
</p>
 
+
<pre>
<pre>
 
 
%INSTALLDIR%\scenes
 
%INSTALLDIR%\scenes
 
</pre>
 
</pre>
 
 
<p>
 
<p>
for example, to refer to (say) <code>C:\Program Files\POV-Ray For Windows Vn.n\Scenes</code>,
+
for example, to refer to (say) <code>C:\Users\Joe\Documents\POV-Ray\vX.y\scenes</code>.
assuming you installed POVWIN into '<code>C:\Program Files\POV-Ray For Windows Vn.n\</code>'.
 
 
</p>
 
</p>
  
 
<p>
 
<p>
Note that the installdir location does not relate to where the binary is run from - it relates
+
Relative paths are legal as well, and will be resolved only once at load time (but relative
to the information in the registry. Relative paths are legal as well, and will be resolved  
+
to the current directory, not the documents folder). For example, a relative path like the following ...
only once at load time (but relative to the current directory, not the installdir). For example,  
 
a relative path like the following ...
 
 
</p>
 
</p>
  
Line 616: Line 230:
  
 
<p>
 
<p>
would be resolved with relation to the <i>current directory at the time POV-Ray for Windows was
+
would be resolved with relation to the <em>current directory at the time POV-Ray for Windows was
started</i>, so if you started pvengine.exe from the directory <code>c:\myscenes\newscene</code>,
+
started</em>, so if you started pvengine.exe from the directory <code>c:\myscenes\newscene</code>,
 
then the above path would be resolved as <code>c:\myscenes\output</code>. Please note that the
 
then the above path would be resolved as <code>c:\myscenes\output</code>. Please note that the
actual location of the pvengine.exe file is not relevent here - it is the current directory that
+
actual location of the POV-Ray executable file is not relevent here - it is the current directory that
matters (which is not necessarily that of the program).
+
matters (which is not necessarily that of the program installation). You only need to care about this
 +
if you want to use relative paths in the restrictions setup: 99% of users don't, so if it doesn't make
 +
sense, don't worry :-)
 
</p>
 
</p>
  
Line 632: Line 248:
  
 
<p>
 
<p>
An entry in the permitted paths sections gives permission not only for that directory, but <b>all  
+
An entry in the permitted paths sections gives permission not only for that directory, but <strong>all  
the ones below it</b> (note that this is different from the 'permit read/write in current  
+
the ones below it</strong> (note that this is different from the 'permit read/write in current  
 
directory' option mentioned earlier, which only applies to that one directory alone, and not  
 
directory' option mentioned earlier, which only applies to that one directory alone, and not  
 
those below it).
 
those below it).
Line 641: Line 257:
 
A reminder that, as mentioned above, if write protection is turned on at all, the  
 
A reminder that, as mentioned above, if write protection is turned on at all, the  
 
<code>&lt;installdir&gt;\INI directory</code> is always write-protected, and nothing in the  
 
<code>&lt;installdir&gt;\INI directory</code> is always write-protected, and nothing in the  
above permission sections can allow it. This is to prevent a script from modifying  
+
above permission sections should be able to allow it. This is to prevent a script from modifying  
 
pvengine.ini to remove or alter the I/O Restrictions for the next time that POVWIN runs.
 
pvengine.ini to remove or alter the I/O Restrictions for the next time that POVWIN runs.
 
</p>
 
</p>
  
===For Those Who use an Image Output Directory===
+
====For Those Who use an Image Output Directory====
 
<p>
 
<p>
 
Some users have POV-Ray set up such that all images are written into the same output directory.
 
Some users have POV-Ray set up such that all images are written into the same output directory.
 
To make this work with I/O Restrictions active, and assuming the output directory isn't in the
 
To make this work with I/O Restrictions active, and assuming the output directory isn't in the
POV-Ray for Windows installation tree, you will need to add that directory to the permitted
+
POV-Ray for Windows document folder, you will need to add that directory to the permitted
 
output list.
 
output list.
 
</p>
 
</p>
Line 684: Line 300:
 
<table width=100% border=0 cellspacing=0 cellpadding=5>
 
<table width=100% border=0 cellspacing=0 cellpadding=5>
 
<tr><td width=50% bgcolor=#EEEEEF>
 
<tr><td width=50% bgcolor=#EEEEEF>
[[Documentation:Windows Section 2#Important Editor Notes|Important Editor Notes]]</td>
+
[[Documentation:Windows Section 2#The Font Setting|The Font Setting]]</td>
 
<td width=50% bgcolor=#EEEEEF align=right>
 
<td width=50% bgcolor=#EEEEEF align=right>
 
[[Documentation:Windows Section 3#Command-Line Options|Command-Line Options]]</td></tr>
 
[[Documentation:Windows Section 3#Command-Line Options|Command-Line Options]]</td></tr>

Latest revision as of 11:42, 4 July 2017

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


I/O Restrictions

I/O Restrictions are a feature introduced in POV-Ray v3.5. The purpose of this feature is to attempt to at least partially protect a machine running POV-Ray from having files read or written outside of a given set of directories.

The need for this is related to the fact that the POV-Ray scene language has, over the years, become something more akin to a scripting language combined with a scene-description model. It is now possible to write obsfucated POV-Ray code, and to open, create, read and write arbitrary files anywhere on the target system's hard disk (subject to operating system permission).

The basic idea of I/O Restrictions is to attempt to protect the user from a script that may have been downloaded from an untrusted source, and which may attempt to create or modify files that it should not.

The I/O Restriction facility hooks the file open and creation functions in the core POV-Ray renderer code, and allows the Windows version to allow or deny any particular file operation. Please note that this only affects file I/O from the core POV-Ray code; that is, the code that implements the parser and renderer. It does not affect which files the Windows interface can read and write. That is to say, it does not prevent you loading a file into an editor, or saving a file from the editor, or any other feature implemented on the Windows interface that is not part of the core POV-Ray feature set. (The 'core feature set' is those features of POV-Ray that are available on all operating systems and computer platforms for which a version of POV is available).

We do not guarantee that the I/O Restriction facility will actually stop anything from happening. There is always the chance that, like almost all software, it could have a bug in it that causes it to malfunction. Therefore, the onus is on the person who chooses to load an INI or scene file into POV-Ray to ensure that it does not do anything that it should not do. I/O Restrictions are just a sometimes-helpful backup for manual checks.

Please read this section in full so that you understand the caveats and conditions of the facility (such as the fact that some directories are allowed by default).

High-Level Configuration

Now to the details: how to configure the I/O Restrictions (or get them out of your hair if you want them turned off). Under the Options menu there is a sub-menu called Script I/O Restrictions.

win-iorestrictions.png

Script I/O Restrictions sub-menu

This provides you with high-level control of the restriction subsystem. The top section of the menu provides you with three options (detailed below). You can only choose one of the three. The bottom section provides you with two additional options, either of which can be on or off.

Overall Options

No Restrictions

If this option is chosen, POV scripts can read/write everything (subject to operating system permission). The I/O Restriction system is turned off.

Restrict Write but Allow Read

If this option is chosen. POV scripts can read anything, but file creation and file write is only allowed in the implicit and user-specified directories (see Low-Level Configuration for more information on how to specify which directories).

Another way to put it is that I/O Restrictions are turned off for reading files, but not for writing them.

Restrict Read/Write

Both read and write by POV scripts is restricted to implicit and user-specified directories. Note that this is the default setting for a clean installation of POV-Ray for Windows.

Restrictions Affect all Core File I/O

Note that the above settings do not just affect scripted file I/O; they also affect things like include files, output files, and input .POV files. Basically any file-related input or output by the rendering engine. You should take careful note of this statement if you are in the habit of writing your output files to anywhere other than the same directory as the scene file is in (see below).

Additional Options

In addition to the above, there are two other options:

Permit Read/Write in Current Directory

If turned on, the current directory (but not any below it) is automatically added to the allowed list of read/write locations. Since POVWIN sets the current directory to that which contains the source file (.pov or .ini) at the start of a render, this automatically enables the location containing a scene for read/write. For most people, this is a useful feature, so it is on by default for a clean install.

Please note that having this option unchecked does not prevent read in the current directory if you have turned off read restrictions (as documented above), and nor will it prevent writing if you have turned off I/O Restrictions altogether. Also, turning it on will not allow read/write in subdirectories of the current directory - just that dir alone.

Disable Starting other Programs

If this option is selected (the default), shell-outs will not be permitted. 'Shell Outs' are a facility where an INI file can specify that a particular program be run either before or after a frame is rendered as well as at other points in the parse/render process. If you want these, you have to explicitly allow them by unchecking this option.

Low-Level Configuration

This section tells you how to manually specify explicit directories for read/write access, if the standard settings aren't suitable. First we need to cover what is and isn't protected by default.

Overall Concept

The overall concept of the I/O Restrictions, when enabled, is that everything should be denied unless it is explicitly allowed (with one or two exceptions). So unless you add a directory to the 'allowed' list, unless it is one of the implicitly allowed locations then the directory in question is not permitted to be accessed.

Implicitly Permitted Locations

The exceptions to the 'deny everything' rule (referred to above as 'implicit' locations) are as follows:

  1. The document installation directory of POV-Ray for Windows (as given by the registry or otherwise determined at run-time) is permitted to be used for read (but not write). This includes all of its subdirectories (except as below). Note that you can alter this setting if you like.
  2. Write is permitted to the 'Insert Menu' sub-directory within the POV-Ray documents install directory. This is to enable the 'Re-render Insert Menu Bitmaps' feature to function without needing to modify the restrictions.
  3. Read is permitted from the Windows 'Fonts' directory. This is to allow TTF files to be read, as POV-Ray's portable rendering engine has its own TTF parser. (The Fonts directory is also added to the include path automatically).

Adding or Changing Allowed Directories

Note: The INI subdirectory contained within the document install directory is permanently write-protected (unless the I/O Restriction system is turned off). Even if you grant permission to write this dir from he below INI file, writes will not succeed. This is to prevent the INI file that contains the I/O Restriction configuration from being modified by a script to grant itself more access next time POVWIN is run.

To add or change allowed directories, you'll need to modify the file <installdir>\ini\pvengine.ini, where <installdir> is where the POV-Ray for Windows user-editable files where installed. An easy way to get at this file is to select it from the tools menu (by default, it is the second item).

Within PVENGINE.INI you may see two sections like the following ... (note that the actual contents of the installed version are slightly different from this example).

[Permitted Input Paths]
1=%INSTALLDIR%

[Permitted Output Paths]
1=%INSTALLDIR%

If they are not present, it means that POVWIN is using the defaults, in which case you may add them. For example, %INSTALLDIR% is implicitly allowed for input and does not need to be added to the INI file (though there is no harm in doing so).

%INSTALLDIR% resolves to the location that the POVWIN user-editable files were installed. It would be legal to say something like -

%INSTALLDIR%\scenes

for example, to refer to (say) C:\Users\Joe\Documents\POV-Ray\vX.y\scenes.

Relative paths are legal as well, and will be resolved only once at load time (but relative to the current directory, not the documents folder). For example, a relative path like the following ...

[Permitted Output Paths]
1=..\output

would be resolved with relation to the current directory at the time POV-Ray for Windows was started, so if you started pvengine.exe from the directory c:\myscenes\newscene, then the above path would be resolved as c:\myscenes\output. Please note that the actual location of the POV-Ray executable file is not relevent here - it is the current directory that matters (which is not necessarily that of the program installation). You only need to care about this if you want to use relative paths in the restrictions setup: 99% of users don't, so if it doesn't make sense, don't worry :-)

A directory placed in the permitted input paths section only allows read. One placed in the output paths section permits both read and write; write permission is inferred to mean read permission. This means you don't need to duplicate entries (the above example shows such a duplication - it is not harmful, just unnecessary). You can have up to 64 entries (numbered 0..63) in each section.

An entry in the permitted paths sections gives permission not only for that directory, but all the ones below it (note that this is different from the 'permit read/write in current directory' option mentioned earlier, which only applies to that one directory alone, and not those below it).

A reminder that, as mentioned above, if write protection is turned on at all, the <installdir>\INI directory is always write-protected, and nothing in the above permission sections should be able to allow it. This is to prevent a script from modifying pvengine.ini to remove or alter the I/O Restrictions for the next time that POVWIN runs.

For Those Who use an Image Output Directory

Some users have POV-Ray set up such that all images are written into the same output directory. To make this work with I/O Restrictions active, and assuming the output directory isn't in the POV-Ray for Windows document folder, you will need to add that directory to the permitted output list.

For example, if your image output directory is c:\images\, you could have something like this in the INI file -

[Permitted Input Paths]
1=%INSTALLDIR%

[Permitted Output Paths]
1=%INSTALLDIR%
2=c:\images

If you want to grant access to an entire drive (e.g. d:\), just add it like this -

[Permitted Input Paths]
1=%INSTALLDIR%

[Permitted Output Paths]
1=%INSTALLDIR%
2=c:\images
3=d:\


The Font Setting Command-Line Options


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