Documentation:Windows Section 5.3

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

Tools Menu

	The Tools Menu provides you with a simple means of customizing POV-Ray for Windows. You can develop your own commands (up to 32) to show up under this menu. Since the menu is determined by the file PVTOOLS.INI, editing and reloading this INI file changes the Tools Menu.
The Tools Menu

PVTOOLS.INI Syntax

The syntax of entries in PVTOOLS.INI is as follows:

[Menu]
ItemN=Description
 
[Command]
ItemN=command_string
 
[Help]
ItemN=help_line

Where N is a number between 0 and 31, and entries in the [Help] section are optional.

Item0 ... Item31

are the item numbers that define the order in which entries appear in the Tools Menu.

[Menu]

Entries in the [Menu] section are what actually appears in the Tools Menu. The '&' character tells Windows where to put the underline in the menu entry. The underlined letter becomes the abbreviation for the command. For example the letter 'C' in '&Click Me' would become 'Click Me' when displayed in the Tools Menu, and you could access the command by pressing Alt+T and then 'C'. (Alt+T activates the Tools Menu).
You should make sure that all Tools Menu entries have different abbreviations if you intend to access them this way. Of course, you don't have to supply any abbreviation if you don't want to.

Note: By default newer versions of Windows will not display the underline beneath the abbreviation until you press ALT. This means if you use the mouse to open the menu you won't see the underlines.

[Command]

This is the command that POV-Ray will execute for that entry. This can be a Windows EXE, a batch file, or anything else that may be executed by the Win32 ShellExecute() API call. The command consists of the actual command name followed by any parameters you want to supply to the program.
There are two special commands, '$S' and '$E'. $S means 'use the shell association for the filename that follows it', and '$E' means 'open the following file in the internal POVWIN editor'. Let's look at an example -

Item4=$S %1

Since %1 refers to the output file (see below) this means that Item 4 of the tools menu expands to a command to Windows to open the last output file with whatever program is associated with it. For example, if the last output file was 'c:\images\torus4.png' then the above command example would use whatever program is associated with PNG files (i.e. the program that Windows runs if you double-clicked on the TORUS4.PNG file in Windows Explorer) to open it.

Note: If using the $S or $E special commands, do not quote the parameters with '"', even if they will have spaces in them. Both of these commands may only be supplied a single parameter, which is taken to be the entire line following the command.

POV-Ray for Windows has a number of pre-defined parameters that you can substitute into the command line before the program is run. These are defined by a percent sign ('%') followed by a letter or number. For example, '%i' means substitute the POV-Ray for Windows INI file directory in the place of the '%i'.

Let's look at the command:

notepad.exe %ipvtools.txt

If you had installed POV-Ray for Windows into the directory 'c:\povwin3', then our standard INI file directory would be 'c:\povwin3\ini\'. When POV-Ray ran the above command, the '%i' would be replaced with 'c:\povwin3\ini\'. Note that the trailing '\' is provided by POV-Ray. This means that:

notepad.exe %ipvtools.txt

would become:

notepad.exe c:\povwin3\ini\pvtools.txt

Here are all of the predefined substitutions:

%0	The contents of the 'SourceFile' entry of the 'LastRender' section in PVENGINE.INI. This will be the input file provided to POV-Ray for the most recent render. This information is extracted from the rendering engine itself, rather than any input dialog or command-line. It is the file which, after all processing of the command line and INI files was complete, was finally assigned as the input file.
%1	The contents of the 'OutputFile' entry of the 'LastRender' section in PVENGINE.INI. This will be the output file from the last render, if any. This entry could be blank.
%2	The contents of the 'SceneFile' entry of the 'LastRender' section in PVENGINE.INI. This will be the scene file name for the last render, without the .POV extension. You can use this by appending a new extension to it. For example, tga2gif %d\%1 %2.gif could expand to: tga2gif c:\scenes\myscene.tga myscene.gif assuming the input file was myscene.pov and the current directory at that time was c:\scenes.
%4	The contents of the 'IniOutputFile' entry of the 'LastRender' section in PVENGINE.INI. If you had instructed POV-Ray to write an INI file from the last render, this would contain its name.
%D	The contents of the 'CurrentDirectory' entry of the 'LastRender' section in PVENGINE.INI. This is the current working directory that was set on your machine when POV-Ray began rendering the last file, and is what the other output file entries are probably relative to. You may need to provide '%d' with some of these other entries to get the full path.
%H	The POV-Ray for Windows install directory, as specified in the registry or inferred at run- time, e.g. 'c:\Program Files\POV-Ray for Windows v3.7\'. Note the trailing backslash is supplied.
%P	The POV-Ray for Windows user documents directory, as specified in the registry or inferred at run- time, e.g. 'c:\Users\Joe\Documents\POV-Ray\v3.7\'. Note the trailing backslash is supplied. This is the directory where the sample scenes, include files, and INI files are stored.
%I	The POV-Ray for Windows INI directory. e.g. 'c:\Users\Joe\Documents\POV-Ray\v3.7\ini\'.
%N	The preset INI filename, as used in the render options dialog.
%R	The last render file (with full path) as supplied to POV-Ray from the render or choose file dialog. This is not necessarily the same thing as %S or %0.
%S	The source file name as provided to POV-Ray on the last render of the current session. This is not necessarily the same thing as the %0 or %R directive. For example, %R will never provide the path to a file that was rendered via the File Queue without the use of the Command dialog. %S will, however, include any such file.
%T	The full path to PVTOOLS.INI. This is the file which holds the Tools Menu commands.
%%	A literal percent character ('%').

If any of the above seems confusing, there's an easy way to find out what's going on. If you place the statement DEBUG=1 in the General section of PVTOOLS.INI, POV-Ray for Windows will print out the string for each command both before and after it is expanded, instead of running the command that you select in the tool menu. That way you can see exactly what POV-Ray substitutes. The printout will be visible in the messages window.

For example:

[General]
Debug=1

will turn on debugging. while

[General]
Debug=0 

or omitting the statement entirely turns it off.

[Help]

You can have a help line appear in the status bar at the bottom of the window. You don't have to supply this entry if you don't want to.

Example:

[Help]
Item1=Edit master POVRAY.INI in installation directory

This command makes the string 'Edit master POVRAY.INI in installation directory' appear on the status bar when the mouse is over the 1st item in the Tools menu.

Reload Tool Menu

If you want your changes to take immediate effect after you have edited PVTOOLS.INI using a text editor, you have to select the Tools Menu command Reload Tool Menu to instruct POV-Ray for Windows to re-read the INI file and activate the new settings.

Edit PVTOOLS.INI

This standard Tools Menu command lets you modify PVTOOLS.INI using the Notepad editor. The command is part of PVTOOLS.INI itself, which means you may delete it entirely if you don't want it. It is present by default in the standard distribution of POV-Ray for Windows.

Example PVTOOLS.INI

[Menu]
Item0=Edit &master POVRAY.INI
Item1=Edit PVEN&GINE.INI
Item2=Edit &last rendered file
Item3=Edit last &scene file
Item4=&View last rendered file
Item5=Edit resolution &INI file
Item6=Edit &user-defined syntax file
Item7=&Browse sample scenes folder
Item8=Edit &this menu

[Command]
# NOTE! If using the $E or $E, DO NOT quote the parameters with '"'.
# If you are calling a program directly, you will probably need to quote the
# parameter; e.g. notepad.exe "%r"
Item0=$e %pini\povray.ini
Item1=$e %pini\pvengine.ini
Item2=$e %r
Item3=$e %0
Item4=$s %1
Item5=$e %n
Item6=$e %I\user-keywords.txt
Item7=$s %pscenes\
Item8=$e %t

[Help]
Item0=Edit master POVRAY.INI in installation directory
Item1=Edit PVENGINE.INI in installation directory
Item2=Edit the last file that POV-Ray was rendering
Item3=Edit the last scene file that you selected
Item4=View the output of the last render (assumes file output was on)
Item5=Edit secondary INI file as specified in Command-line dialog
Item6=Edit the user-defined syntax highlighting file
Item7=Open the folder containing the sample scenes installed with POV-Ray
Item8=Edit PVTOOLS.INI to alter this menu

[General]
Debug=0

Window Menu

The Window menu contains a number of commands related to editor tab management (in the context of this section, a 'window' refers to a tab in the editor) and additionally a list of tabs showing the name of their contents. At a minimum (if no files are open) this list will contain one entry: the Message tab.

The MRU (most-recently-used) arrangement of the tab list in this menu makes it trivial to toggle between files without taking your eyes off the text or using the mouse. The most recently viewed tab (i.e. the current one) will always be entry 1 in the list. The second most recently viewed (i.e. the last tab 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.

Context Menus

Most POV-Ray windows have shortcut (also known as 'context') menus. You access them by right-clicking over the window in question (e.g. the message, edit, or render window). The menu that appears will have the most commonly-used commands (as available in the main menus) that apply to that particular type of window.

The Message Window context menu

	When the mouse right button is pressed over the Message window, a pop-up menu containing these commands are displayed:
The Message Window context menu

All of these commands and sub-menus except 'Minimize to System Tray' and 'Show Tip' are documented elsewhere; the following list links to that documentation.

• Edit Settings/Render dialog
• Select File and Render dialog
• Start Rendering
• File Queue dialog
• Clear Queue
• Clear Messages
• Re-Display Render Window
• Render Priority

Minimize to System Tray

This command (which is also available as a toolbar button) will hide POV-Ray for Windows and place a small icon in the system tray (the system tray usually contains a clock and is often at the right hand side of the task bar at the bottom of the screen).

You can use the right-mouse button on this icon to get a context menu. Double-clicking on it restores POVWIN from the tray.

Show Tip

If you select Show Tip, POV-Ray for Windows displays a single tip (see Show Tips of the Day).

The Render Window context menu

The Render Window context menu

See the Render Window sub-menu for documentation on the commands in this menu.

The Editor Window context menu

The Editor Window context menu

The actual content of the line shown as 'Open "filename"' will vary according to what was on the line under the cursor when the right mouse button was clicked. All of the commands except 'Show Messages', 'Context Help', and 'Open "filename"' are documented elsewhere; the following list links to that documentation.

• Cut
• Copy
• Paste
• Undo
• Redo
• Bookmark sub-menu
• File
• Search
• Selection sub-menu
• Close Current File
• Properties

Show or Hide Messages

Manually cause the small message window to be displayed (or hidden if it is showing, in which case this menu entry will read 'Hide Message Window' instead of 'Show Message Window'). Note that you can also use the Escape key to hide the message window.

See Auto-Show Parse Messages for more information.

Context Help

This command (which can also be activated with the F1 key) will cause the editor to look for the closest word to the edit caret and attempt to look it up in the help file. If more than one match is found, you will be given a choice as to which one. If no match is found, the help file will open with the index at the closest match it could find.

Open Filename

Whenever you open the context menu, the editor first looks underneath the edit caret to see if there is a line that looks like a POV-Ray scene file '#include' directive. If one is found, the name of the specified file is placed into the menu in place of "filename". If one is not found, then it may show Copy ... to Command-Line (see below).

If you then select this command, the editor will attempt to find and open the file in a new edit window. The standard include paths (as defined in PVENGINE.INI) will be searched if the file is not found relative to the current directory.

Copy ... to Command-Line

If, when the editor searches for an include file name on the current line (see above), it does not find one, it will then look for something that looks like a 'command line'. By 'command line' we mean a line that could be used in the toolbar command-line field as options. The editor uses several simple rules to decide if something is likely to be a command-line:

Firstly, the line must contain a '//' somewhere. Then, either -

1. The first non-whitespace character after the '//' is either a '+' or a '-', and the next character after that is alphabetical, or
2. The first non-whitespace after the '//' contains 'Cmd:' (case-insensitive).

If the line fits this description then the text after the '//' (with the 'Cmd:' removed if it were present) is considered the command-line (minus leading and trailing whitespace). There is one slight variation to the detection rules, though: if the line also contains a quoted string that looks like it could be a filename and you right-click before the end of that string, the context menu will present the 'Open File in Editor' option instead of the 'Copy Command' option. To get the 'Copy Command' option, simply make sure you right-click somewhere to the right of the filename.

The "Copy to command-line" feature

In this case the menu will have a command to copy the found command to the toolbar command-line, such as the one shown on the left. If this command is chosen, the text in the toolbar command-line will be replaced with the text extracted from the line, and focus will be changed to the toolbar command-line field.

The purpose of this facility is to allow users to keep a set of commonly-used command-line options at the top of the scene file, and use this facility to quickly copy one of them to the command-line for a render.

Example command-lines which could be embedded into a scene file -

// +w480 +h200 +a0.1
// +w960 +h400 +a0.1

The following would also be legal (and equivalent to the above example) -

// Cmd: Width=480 Height=200 Antialias_Threshold=0.1 AntiAlias=On
// Cmd: Width=960 Height=400 Antialias_Threshold=0.1 AntiAlias=On

See also Toolbar Command Line.

Include System Information

Bug Reports

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