Documentation:Windows Section 2.1

From POV-Wiki
Revision as of 19:17, 16 June 2012 by WikiSysop (talk | contribs) (Fixing/updating some index entries in windows docs)
Jump to navigation Jump to search

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


Using the Internal Editor

Configuring the Internal Editor

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
European Users and 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 (they assumed that it was not changeable when, in fact, it is).

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 and .INC 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 attributes (such as tab size).

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.

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. 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.

WinImgMenusRestrictions.gif

Script I/O restrictions drop down

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 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 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. 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 the current directory and the 'Permit Read/Write in Current Directory' option is checked, then the directory in question is not permitted to be accessed.

The exceptions are as follows:

  1. The document installation directory of POV-Ray for Windows (as given by the registry) is permitted to be used for read (but not write). This includes all subdirectories of the install directory (except as below). Note that you can alter this setting if you like.
  2. The INI subdirectory contained within the POV-Ray for Windows document install directory, as given by the registry, is permanently write-protected (unless the I/O Restriction system is turned off). Even if you grant permission to write this dir from the 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.

Adding or Changing Allowed Directories

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.

%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\3.7\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:\


Important Editor Notes Command-Line Options


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