Contents
Contents of Program Text Viewer PTVIEW Help File

Running

Overview

Topics:

C/C++ preprocessing

Printing

Regular expression searching

Tab size converting

Speed bars

Menu items

PTVIEW version 1.1 is a FREEWARE. Therefore, it is free of charge. It can be distributed freely for non-commerical purposes. However, I still retain the rights to the source and the binary of the program. Please note that PTVIEW is distributed AS-IS. It doesn't come with any support or warranty. I am not responsible for any damage caused due to the use of the program.


Menu Items
The Menu Items

File

Edit

Search

Processing

View

Window

Help

The File menu:

Open: Open a file to the current view window. Use Window | New Window to open a new view window.

Reopen: Re-open the current file on.

Save: Save the current file.

Save As: Save the current file as some other name.

Close: Close the current file.

Close All: Close all files of the focused view window.

Open INI File: Open and use a user defined INI file. Usually, they are saved in the directory where PTVIEW is located, with the extension ptv.

Print: Print the current file using the current view settings.

Print Setup: Setup the printer.

Page Setup: Setup print page layout.

Exit: Exit PTVIEW.

The Edit menu:

Copy: Copy the select text segment to the clipboard.

Duplicate: Duplicate the current file to other view window. Use Window | New Window to open a new view window.

Select All: Select the whole file.

The Search menu:

Search: Put the input focus to the search string edit box on the Search Bar. See Regular expression searching for more information on searching.

Search From Top: Start the search from the top of current the file.

Search Forward: Start the search from the next of the current line.

Search Backward: Start the search from the previous of the current line, searching backward.

Go To: Put the input focus to the line number edit box on the Search Bar.

Go To Line 1: Go to the first line. That is to set the first line to be the current line.

Go To Line N: Go to the last line.

Go To Block Start: Go to the first line of the highlighted block nesting.

Go To Block End: Go to the last line of the highlighted block nesting.

The Processing menu:

Preprocess: Perform preprocessing. The most appealing features of PTVIEW requires preprocessing.

Browse Symbols: Popup the list of macro symbols, showing their definitions.

Free Symbol List: It frees up the memory allocated for the symbol table after preprocessing. If you want PTVIEW to free the symbol table automatically after preprocessing, put the line:

AutoDeleteSymbolList=T

in the [GENERAL] section of the INI file.

Set Directory: Set the working directory (the include directory). Also see preprocess settings dialog.

Preprocess Settings: Popup the preprocess settings dialog.

Convert: Convert tab characters using the new tab size specified, while keeping the look of the text file. Use the menu item Processing | Tabs Settings to set the tab sizes.

Convert To Spaces: Convert tab characters to spaces, while keeping the look of the text file.

Tab Settings: Popup a dialog so that you can specify the current tab size, and the new tab size (for tab characters conversion).

The View menu:

Files: Popup the list of files opened for the focused view window. Choose the desired one to be the current file.

Tool: Toggle the Tool Bar.

File List: Toggle the File List Bar.

Line Numberings: Toggle the line numbering bar, the vertical bar which shows the line numberings.

Block Nestings: Toggle the block nesting bar, the vertical bar which shows the C/C++ block nesting outlines. Note that preprocessing is necessary for PTVIEW to outline the block nestings.

Search: Toggle the Search Bar.

Highlight Comments: Toggle highlighting of C/C++ comments.

Show Tabs: Toggle showing the tab characters as rectangles.

Show Complete: Toggle showing conditionally-compiled away text lines. See preprocessing for more on conditional compilation.

Text Font: Popup a dialog for selecting font to use in all view windows (and printing).

Text Colors: Popup a dialog for selecting various text colors.

The Window menu:

New Window: Open a new view window. With an extra view window, you can duplicate an opened file from another view window. (Use the menu item Edit | Duplicate.)

Cascade: Cascade the view windows.

Tile Horizontal: Horizontally tile the view windows.

Tile Vertically: Vertically tile the view windows.

Arrange Icons: Arrange the view window icons.

Close All: Close all of the view windows.

The Help menu:

Contents: Bring up this help file, showing the contents of the help file.

Overview: Bring up this help file, showing the section which gives you an overview of PTVIEW.

Regular Expression: Bring up this help file, showing the section which talks about regular expression.

About: Popup the about dialog, telling you some information about the current state of PTVIEW.

To speedup selecting menu items, three speed bars are created: Tool Bar, Search Bar, and File List Bar.

The following is how the File List Bar looks like:


Click on this button to open new file for the view window.


This "on" button tells the name of the current file on the view window.

You may drag this button and drop it on any other view window (MDI window) to duplicate the file on that other view window.


This "off" button tells the name of another opened, invisible file on the view window.

Click on the button to select that file for viewing.


These empty "off" buttons are unused space for files.

Note that the number of opened files is not restricted to the number of file buttons on the File List Bar.


Use this scroll bar to shift the file list so as to see the hidden opened file names.


Click on this button to popup the list of opened file for selection.


Click on this button to cause the file-list bar to disappear.


The text file shown on the focused view window is the current file.


Running PTVIEW

Components:

PTVIEW.exe - The program executable itself.

PTVDEF.dll - A supporting DLL that deals with compiler system specific settings.

BWCC.dll - Another supporting DLL.

PTVIEW.hlp - This help file.

For simplicity, put all these files in the same directory; then, you should start PTVIEW from within that directory. If you are sure that there is already a copy of BWCC.dll in your Windows system directory, you can safely delete the copy that comes with the program.

Command Line:

PTVIEW [%<file1>] [<file2>]

- <file1> is an INI file. It also specifies the INI directory --- the directory of the program by default --- in which PTVIEW believes all INI files should be. If <file1> is a directory (ended with '\'), then it only specifies the INI directory.

- <file2> is a text file to view.

PTVIEW is developed with Windows 3.1 in mind. Therefore, it is a 16-bit Windows application. I have tried it on Windows 95 and Windows NT; it seems to work fine on both platforms.


Overview
Overview of Program Text Viewer PTVIEW

PTVIEW version 1.1 is a small Windows 3.1 utility which aids viewing dazzling C/C++ program text files, which may possibly be clustered up by conditionally compiled code segments. It can hide/highlight the code segments which will not be compiled; it can outline statement blocks mangled among these segments; and it can even print them out to printer.

PTVIEW is designed with several pretty nice features:

- C/C++ preprocessing

- Printing

- Regular expression searching

- Tab size converting

The following is a snap-shot of the application's screen:


The green numbers are normal line numbers.


The number with a rectangle drawn around it is the current line number. It tells you which line is the current line.

You can click on any other line numbers to set it to be the current one.


The red numbers are lines numbers of the highlighted (current) block text lines.


The blue lines outline the C/C++ block nestings.

Click on any one of such lines to highlight the outlined block.

The highlighted (current) block nesting is outlined in red.

Note that preprocessing is necessary for PTVIEW to show the block nestings.


The dark blue text lines are normal --- not conditionally compiled away --- text line.

You can double click, while holding down the Ctrl key, on any macro symbol to find out the definition of that symbol at that line.

Note that preprocessing is necessary for PTVIEW to distinguish between different text lines, and to know the definitions of macros.


The gray text lines are conditionally compiled away text lines.

You can hide/show those lines with the menu item View | Show Complete, or checking/unchecking the Show Complete check box on the Tool Bar.


The dark green text lines/characters are C/C++ comments.

Note that PTVIEW highlights comments correctly only if they are not nested.


The dark red text lines are the lines of the highlighted (current) block.


There are three kinds of speed bars: Tool Bar, Search Bar, and File List Bar.


Searching with Regular Expression

One feature of PTVIEW is searching with regular expression. If you are already familiar with regular expression, you will have no problem performing search with PTVIEW. Otherwise, you either learn the syntax of regular expression and be happy with it, or you disable it altogether.

To perform searching, the Search Bar must be visible. If it is not currently visible, by selecting the menu item Search | Search the Search Bar is automatically made visible, and the cursor is put in the edit box where you enter search strings. Remember that a search string can be a regular expression if the RE check box on the Search Bar is checked. Once you get used to regular expressions, you will find them very helpful.

To start the search, you can just press Enter after entering the search string. This causes the search to start from the next of the current line. Alternatively, you can use the menu item Search | Search Forward to attain the same effect. If you use the menu item Search | Search From Top, you start the search from the top of the text file. If you use the menu item Search | Search Backward, you start the search from the previous of the current line, searching backward. The search pattern strings are memorized. You can walk through the list of memorized search strings using the up/down arrow keys. Please notice that the searching algorithm implemented only tries to spot whether a particular line contains the search pattern or not. The number of occurrences of the pattern within a line doesn't matter.

Another similar feature is going to a particular line. (Menu item Search | Go To). You enter the line number to go to in the leftmost edit box of the Search Bar. Then by pressing Enter, the current line will be set to the line you specified. (Actually, the current line jumps as you enter; however, PTVIEW memorizes the line number if you press Enter. You can use the up/down arrow keys to walk through the list of memorized line numbers.) You may also use the menu items Search | Go To Line 1 and Search | Go To Line N to go to the top and bottom of the text file respectively.

The following is how the Search Bar looks like:

The regular expression syntax, which is very similar to that used by the UNIX VI editor, used by PTVIEW is described as follows:

A regular expression is composed of characters. Some are just regular characters with regular meanings; like 'a', 'A', 'b', 'B', '1', '2', ... While some have special meanings:

. represents any character.

^ represents the beginning of a line.

$ represents the end of a line.

\< represents the begin of a word.

\> represents the end of a word.

[char-list] represents any one of the characters from char-list; if char-list is prefixed by '^', the reverse is true. It is possible to represent a list of consecutive characters by using '-'. For example, A-Z represents the list of characters from 'A' to 'Z' inclusively.

\( and \) delimit a subexpression.

\t and \b are the familiar C/C++ control characters which I added to the syntax.

After a character (or one of the above special "characters"), a repeat count can be specified:

* means 0 or more times.

\+ means 1 or more times.

\? means 0 or 1 times.

\{n\} means exactly n times.

\{n,m\} means n to m times. m can be omitted; in this case, m is assumed to be infinite.

The escape character is the usual '\'. Therefore, \. represents the character '.' (the dot), because the special meaning of '.' is escaped away.


Click on this button to cause the search bar to disappear.


Enter the line number you want to go to here.

Pressing Enter will take you there.

Note that a few tens of the previous line numbers you entered are remembered. You can use the up/down arrow keys to walk through the list.

This is also where the current line number is displayed.


Check this box if you want your search be case-sensitive.


Check this box if you want the search string you entered be treated as a regular expression.


Enter the search string (a pattern) you want to search for in this box.

Pressing Enter will start the search from the next of the current line.

Note that a few tens of the previously entered search string are remembered. You can use the up/down arrow keys to walk through the list.


Start searching for the pattern you specified from the top of the text file.


Start searching for the pattern you specified from the next of the current line, searching forward.


Start searching for the pattern you specified from the previous of the current line, searching backward.


A string of characters composed of digits and/or alphabets (including '_') only is considered to be a word.


Setting and Converting Tab Size

As a programmer, I believe that there were times you felt almost mad because the code you were reading was not properly aligned. The problem is usually that the original author of the file used some tab size, and you view it using another. In this situation, you may wish that you could quickly test out the different tab sizes to determine which one was used. Furthermore, you may even want to get rid of those confusing tab characters once and for all. (Or convert the tab size using your favorite one, if you yourself are used to using tab characters.) PTVIEW allows you to do exactly this. All you want to do can be controlled with the Tool Bar. (Actually, many functionalities of the Tool Bar are releated to preprocessing.) Or if you are used to using the menu, check out the Processing menu.

The following is how the Tool Bar looks like:


Check this box to make the line numberings visible.


Check this box to make the block nesting outlines visible.


Check this box to make tab characters represented by yellow rectangles.


Check this box to make conditionally compiled away text lines visible.

See preprocessing for more on this.


Click on this button to perform preprocessing.

Preprocessing will enable you to visually distinguish conditionally compiled away text lines from the others.


Click on this button to popup the preprocess settings dialog.


Click on this button to popup the list of macro symbols.


Use this scroll bar to adjust the desired tab size.


Click on this button to perform conversion of tab characters from the current size to the new size, specified on the right side, while keeping the look of the text file.

If the check box on the right side is unchecked, the conversion will be to remove tab characters.


Click on this button to cause the tool bar to disappear.


Printing

The following dialog box, which sets the logical print page layout on a physical page, should show the printing features of PTVIEW:

Note that the above dialog box is activated with the menu item File | Page Setup.


Checking this radio button means that you want to print a single logical page  per physical page.


Checking this radio button means that you want to print 2 logical pages per physical page.

If the physical page orientation is Portrait, i.e. page height is bigger than page width, one logical page will be on top of the other. Otherwise one logical page will be on the left side, and the other on the right.


Checking this radio button means that you want to print 4 logical pages per physical page.


Checking this radio button means that you want to print however many characters per line the select font allows. In other words, no scaling will be performed.


Checking this radio button means that you want to have some control over the number of characters printed per line.

You specify the number of characters per line by filling the two edit boxes beneath; however, the accuracy depends on the resolution of your printer.


Enter the minimum number of characters per line in this edit box.

Note that the value you entered here is significant only if the above radio button is checked.


Enter the maximum number of characters per line in this edit box.

Note that the value you entered here is significant only if the above radio button is checked.


Checking this check box means that you want to be notified of the effective print layout before printing.


Checking this check box means that your printer is not capable of reasonably representing color, and you want the printout in pure black and white. Note that the background are never painted for black and white printing.


Checking this check box means that you want the hidden lines, if they are to be shown, be "crossed" out. Note that this options override any background color for hidden lines.


Enter the length (in hundredth of an inch) of the gap between two logical pages laid out horizontally here.


Enter the length (in hundredth of an inch) of the gap between two logical pages laid out vertically here.


Enter the physical page margin (in hundredth of an inch) here.


C/C++ Preprocessing

PTVIEW is capable of performing some simple C/C++ preprocessing:

1. It finds out and highlights conditionally compiled away code segments (those lines which will be ignored by the compiler). (See screen snap-shot.) After PTVIEW identified the conditionally compiled away code segments, you can choose to highlight them, or hide them altogether using the menu item View | Show Complete. Note that PTVIEW would have trouble evaluating macro with parameters, --- defined works; sizeof doesn't --- or macro expressions which contains strings, or floating point numbers. (By the way, all numbers are treated as long integers.) As a side effect, you can find out the definition, and evaluated value if possible, of any macro symbol in your program text. You do this by double-clicking the symbol while holding the Ctrl key down. The definition, and evaluated value if possible, of the symbol at that particular line will be popped up. Additionally, you will be presented with a list of file names, which indicates the path of file inclusions that leads to the definition of the symbol.

2. It finds out and outlines the C/C++ block nestings. (See screen snap-shot.) It gives you a visually easier way to identify code text lines that belongs to a particually block. Note that you can select a block by clicking on any block nesting outline in order to highlight the code text lines belonging to that block.

Note:

1) At any time during preprocessing, you can press ESC key to abort the action.

2) You can speedup the preprocessings by adding the line:

UseProgressCursor=F

in the [GENERAL] section of the INI file.

3) PTVIEW cannot handle nested comments correctly.

4) PTVIEW cannot handle DBCS correctly.

The following is the preprocess setting dialog:


Check this box if you want to display the conditionally compiled away text lines.


Check this box if you want PTVIEW to process also the user include files (e.g. #include "IncFile.h").

The include files will be read from the current/working directory. You set the path of the working directory with the menu item Processing | Set Directory.

There can be additional include directories. You set them with the preprocess settings dialogs, which can be called up with the menu item Processing | Preprocess Settings.

At any time during preprocessing, you can press ESC key to abort the action.


Check this box if you want PTVIEW to process also the system include files (e.g. #include <stdio.h>).

The include files will be read from the current/working directory. You set the path of the working directory with the menu item Processing | Set Directory.

There can be additional include directories. You set them with the preprocess settings dialogs, which can be called up with the menu item Processing | Preprocess Settings.

At any time during preprocessing, you can press ESC key to about the action.


Preprocessing include files is significant only if the include files define macro symbols.

Therefore, in some cases, it makes sense to just preprocess a single additional include file (instead of all the include files specified in the file).

You set that single include file by clicking on the button.

Note that all include files specified in the pre-include file will always be preprocessed.


Check the box if want to set a pre-include file.


The effective include file to pre-include is displayed here.


Enter the additional include directories, separated by semi-colors (;), here.

Note that the primary directory is set with the menu item Processing | Set Directory, which is the working/current directory.


Click this button to set the compiler system you are working with. PTVIEW needs to know the compiler system you are working with so that it can pre-define the compiler specific pre-defined macro symbols for you automatically.

Currently, PTVIEW recognizes Borland C++ version 3.x configuration files only. (You can convert a project file (prj) to a configuration file (cfg) using the utility PRJCFG. For other compiler systems, you have to specify the pre-defined macro symbols manually.

Note that the settings are written to an INI file. The default INI file is "ptview.ini" in your Windows directory. You can specify a custom INI file with the menu item File | Open Ini File.


The effective compiler system's name is shown here.


Enter additional user pre-defined macro symbols here (e.g. DO_DEBUG=1;USE_LIB=0). This line is processed after processing the compiler specific defines.

Note that they should be separated with semi-colons (;).


Enter symbols to undefine here. This line is processed after processing the compiler specific defines and user defines; and is processed before any preprocessing of files.


Accept the changes made to the settings.


Cancel the changes made to the settings.


PTVIEW is designed and implemented by Trevor W.S. Lee.

It is a FREEWARE for personal use. It can be distributed freely for non-commerical purposes. However, the author shall retain the rights to the source and the binary of the program.


Conditionally compiled away text lines refer to those lines that will be ignored by the compiler due to preprocessor conditions set. For example, if WIN32 is defined:

#if defined (WIN32)

// This line will be compiled.

#else

// This line will be ignored.

#endif