WPI (Word Picture Insert) Reference Manual

Overview

WPI inserts 1 to N user-selected picture or graphic files into a Microsoft Word ® table. The human interface is comprised of two basic input interfaces:

• A "main" screen from which pictures and graphics are inserted into Word, and
• A configuration screen that specifies various parameters used by the main screen.

The remainder of this document describes the main screen. Configuration screen documentation is available here.

Throughout this document, it may be helpful to refer to an actual image of WPI's main screen, which is provided below. Note that this is a clickable image. Simply click on any area of the user interface for which immediate help is desired. Otherwise, continue reading the manual.

Basic Usage

To insert pictures/graphics in a Word table, follow these steps:

1. Use the File Sorting options to specify whether a list of files returned via Browse/Favorites buttons is sorted in ascending or descending lexicographical order, or not at all.
2. Use the Browse or Favorites buttons to locate a directory containing the desired pictures and/or graphics. Either button invokes a Windows common open dialog box that is capable of traversing both local and network-based file systems.
3. If necessary, use the "Files of Type" filter in the common open dialog box to specify a wildcard pattern that displays the desired files.
4. Within the common open dialog box, use standard Windows selection techniques to select the filenames of one or more pictures/graphs. When satisfied with your selections, press the dialog box's Open button. All selected filenames will be sorted, if specified in step 1, and then appended to WPI's Selections list.
5. Click the Files=>Word Table button to open a communication channel with an existing instance of Microsoft Word. If Word is not currently running, it is started.

   In either case, WPI sends commands to Word which:

   1. create a new table in the current document,
   2. import each selected picture into that table's next cell,
   3. move the cursor out of the table.

Selecting Pictures/Graphics With Drag and Drop and Windows Explorer

It's possible to select and drag filenames from Windows Explorer and subsequently drop them into WPI's Selections list control. Here's how:

1. Use WPI's File Sorting options to specify whether filenames are sorted in ascending or descending lexicographical order, or not at all.
2. Launch Windows Explorer and navigate to a directory containing the desired pictures/graphics.
3. Using standard Windows selection techniques, select one or more filenames in the Windows Explorer display panes, drag same to the WPI Selections list, and drop (i.e., release the left mouse button).
4. Dropped filenames are sorted, if specified in step 1, and then appended to the Selections list.

Paste Filenames From The Clipboard

If the Windows clipboard contains a list of graphics/picture file paths, they may be appended to the Selections list via one of the following Edit menu commands:

• Paste unsorted -- append clipboard file paths as is.
• Paste sorted ascending -- sort file paths in ascending order and then append.
• Paste sorted descending -- sort in descending order and then append.

For the sake of completeness, WPI also provides the following clipboard operations that move or copy data from the Selections list to the clipboard:

• Copy -- copy selected file paths to the clipboard.
• Cut -- same as Copy, plus the selected file paths are also removed from the Selections list.

Changing WPI's Default Configuration

A number of WPI's features are user-configurable via the configuration screen. To examine and/or change the current configuration, select Edit | Configuration from WPI's menu bar.

File Sorting Options

When multiple filenames are appended to WPI's Selection list via the Browse/Favorites buttons or via Drag and Drop, it's often useful to first sort the filenames in ascending or descending order, especially if the names include time-date stamps that facilitate meaningful lexicographical order. Filenames may be sorted in ascending or descending order, or not at all.

Browse Button

Launches a Windows common open dialog box that selects picture/graphics files. Within this dialog box, any of these file selection techniques are available:

• Doubleclick a single filename to automaticaly move it to WPI's Selections list.
• Click a single filename and then click the Open button to move it to the Selections list.
• Select multiple files using the standard Windows Shift+Click or Ctrl+Click operations. Move multiply selected files to the Selections list by clicking the dialog box's Open button.
• When the common open dialog box has keyboard focus, select all files by pressing Control+A and then clicking the Open button.

Note 1: The initial browse folder (directory) is a configurable parameter, which may be modified by changing the contents of the Working Directory text entry field in WPI's configuration screen. The common open dialog box's primary file filter is also configurable and may be modified by changing the contents of the configuration screen's File Types text entry field.

Note 2: Multiple file selections are sorted in accordance with the setting of the "File Sorting" feature.

Note 3: WPI remembers the last 10 folders visited via the Browse button. These 10 folders may be accessed from the File | Recent Folders menu selection and purged via File | Purge Recent Folders.

Favorites

Launches a Windows common open dialog box that initially browses the Windows Favorites folder. All file selection techniques described for the Browse button apply equally to this dialog box.

So why browse the Windows Favorites folder? As it turns out, Windows Explorer supports a little known feature that facilitates the creation of folder shortcuts within the Favorites folder. Example usage:

1. Start Windows Explorer and navigate to a folder that contains picture/graphics files of interest.
2. Use the Favorites | Add To Favorites menu selection to create a shortcut for the folder noted in step 1. If necessary, assign the shortcut a name that indicates the purpose of this folder. For the purposes of illustration, assume the shortcut name is MyPicDir. Close Windows Explorer.
3. Start WPI and click the Favorites button. Notice that the MyPicDir shortcut created in step 2 is visble in the common open dialog box launched by the Favorites button.
4. Doubleclick MyPicDir. The common open dialog box opens and displays all picture/graphics files stored in the folder referenced in step 1.

As can be seen, this feature provides extremely quick access to any folder accessible as a Favorites shortcut.

Note 1: WPI remembers the last 10 folders visited via the Favorites button. These 10 folders may be accessed from the File | Recent Folders menu selection and purged via File | Purge Recent Folders.

Selections List

Once one or more filenames have been added to this list, send them all to Microsoft Word by clicking the Files=>Word Table button.

When the Selections list has keyboard focus, selected filenames may be deleted from the list (but not from disk) by pressing the Delete or Backspace keys. This list control supports these filename selection techniques:

• Click a single filename to select it. The single click operation unselects all previously selected files.
• Select multiple files using the standard Windows Shift+Click or Ctrl+Click operations.

Finally, all filenames may be delected from the list (but not from disk) by clicking the Clear Selections button.

Files => Word Table Button

Click this button to import all files in the WPI Selections list into a Microsoft Word table. Prior to that, you may wish to configure the destination table's geometry, page orientation (landscape, portrait, or unchanged), and section arrangement.

Table Geometry

This text entry box specifies the initial row and column geometry of the destination Word table. It's not important for the geometry to specify enough table cells to hold all selected graphics files. Instead, when the initial geometry is too small, WPI simply directs Word to create new cells as necessary. This means, in essence, that Word adds a new table row for each operation that would overflow the current table. Consequently, the most important dimension entered in this text box is the number of table columns.

Create New Section

This option causes WPI to take the following actions prior to inserting pictures and/or graphics in the current Word document:

1. Create two new sections (call them "a" and "b") at the document's current cursor location,
2. Break the linkage between the two sections,
3. Move the cursor into section "a".

The net effect of these three commands is that WPI creates a new table in section "a". Additionally, if the settings of the Document Style radio buttons differ from Word's current page orientation (e.g., WPI configured for Landscape and Word configured for Portrait), then the Document Style utilized by WPI will only affect section "a". If a new section is not created and the WPI and Word orientations differ, then WPI's Document Style will modify the orientation of the entire Word document (e.g., all document pages toggled to landscape).

Add Table Grid Lines

Check this option to force Word to add grid lines to the table that WPI creates.

Document Style

The Document Style radio buttons specify the desired MS Word page orientation when WPI creates a new table in the current Word document.

Hints:

• If Document Style is set to other than Unchanged, consider also creating a new section in the current Word document.
• The Edit | Configuration menu selection provides access to a number of important Portrait/Landscape parameters, including:
   
  
  • Paper Height and Width
  • Margins

  NB: The values of these configuration parameters are ignored if:

  • The Document Style is specfied as Unchanged, or
  • Word's cursor resides within an existing table when an insertion operation begins.

Post-Insertion

This set of radio buttons controls cursor placement within the Word document when graphics/picture insertion is complete. Possible options:

• Line Down--move cursor out of table and then down one line.
• Two Lines Down--move cursor out of table and down two lines. This option ensures that at least one blank line is inserted between the previous table and the table created by the next insertion operation. If back-to-back table insertion operations are executed without an intervening blank line, Word concatenates both tables.
• Remain In Table--cursor advances to next table cell. This option is convenient when it's desirable to continue appending pictures to the same table.

Column Width And Row Height

When specified as Automatic, Word sizes table cell dimensions as necessary to make each inserted picture fit.

Conversely, if widths and heights are specified as Exact, WPI computes table cell dimensions appropriate for the currently specified table geometry. WPI's computed dimensions may be adjusted to taste by modifying the values in the Width/Height text entry boxes. Note that in Exact Column Width or Exact Row Height mode, Word scales inserted pictures to fit the dimensions specified in the Width/Height text boxes.

All fractional numeric values (e.g., a Row Height of 3-1/2 inches/row) must be specified using a decimal point character appropriate for the host operating system's current locale. For example, the English decimal point is the period ("."), while Germany uses a comma (","). All example fractional numeric values displayed in this document assume the English locale.

Caption

This feature, which is enabled by clicking the Add Caption checkbox, adds a user-specified caption that Precedes or Follows each inserted graphic/picture. Caption Alignment is user-selectable as either Left, Center, or Right. WPI constructs caption text by concatenating up to three optional strings, in this order:

1. Caption Prefix,
2. Numeric Suffix,
3. Leaf Filename of the inserted graphic/picture.

In most cases, one space is inserted between the prefix and suffix, but see the list of caption features for an important exception. Two spaces are inserted between the leaf filename and any preceding text.

Notes

• A leaf filename's suffix (e.g., ".png", ".jpeg", etc.) is stripped from the caption.
• When Column Width or Row Height are configured in exact mode, the caption text string may cause Word to clip either the inserted picture or caption. To work around this problem, manually resize the graphics or picture(s) within the affected table cell(s).

Caption Features

• If a Numeric Suffix value is specified, WPI increments this value each time a caption is added to a table cell. For example:

  Caption Prefix: "Figure"   Numeric Suffix: "1"   Geometry 2x2
  Generated Captions for a 2x2 table:
  
          Figure 1    Figure 2
          Figure 3    Figure 4
  

• If the last character of the Caption Prefix is a dash ("-"), period ("."), or the decimal point character of the user's current locale (e.g., a comma in Germany), a space is not inserted between the prefix and suffix. For example:

  Caption Prefix: "Figure 1-"   Numeric Suffix: "1"   Geometry 2x2
  Generated Captions for a 2x2 table:
  
          Figure 1-1    Figure 1-2
          Figure 1-3    Figure 1-4
  

• For the purposes of caption formatting, a leaf filename is split into distinct words at these delimiter boundaries:
   
  
  • space (e.g., c:\temp\Avg Growth Chart.png),
  • underscore (e.g., c:\temp\Avg_Growth_Chart.png),
  • mixed case transition (e.g., c:\temp\AvgGrowthChart.png).

  The latter two delimiters must be explicitly enabled via the Underscore and MixedCase checkboxes. Assuming these checkboxes are checked, WPI transforms each of the above leaf filenames into the caption string "Avg Growth Chart".

Creating Descriptive Object-Specific Captions

If a leaf filename adequately labels its content, then WPI's caption formatting facilities make it possible to create on the fly captions that uniquely label each inserted graphics/picture object. For example, consider this scenario:

Caption Prefix:  "Figure 2-"   Numeric Suffix: "1"   Geometry 3x1

Filename Captioning enabled

Selections List: c:\temp\Etch Rate Aug 9.jpeg
                 c:\temp\Etch Rate Aug 10.jpeg
                 c:\temp\Etch Rate Aug 11.jpeg

Generated Captions for a 3x1 table:

        Figure 2-1  Etch Rate Aug 9
        Figure 2-2  Etch Rate Aug 10
        Figure 2-3  Etch Rate Aug 11

Keep this capability in mind when naming graphics/picture files.

Appending Graphics/Pictures To An Existing Table

If, at the start of a picture insertion operation, WPI detects that Word's cursor resides within an existing table, all graphics/pictures are inserted at that point within that table and none of the table's formatting parameters are modified.

This feature works best when Word's cursor is positioned within an empty table cell :-) .

User Interface Usage Hints

• When creating multiple tables, be sure to specify that the cursor is moved Two Lines Down. If back-to-back table insertion operations are executed when the cursor is moved one Line Down, Word simply concatenates all created tables into a single table.
• If Word's cursor resides within a table when an insertion operation begins, the graphics/pictures are inserted into the existing table using that table's properties--none of WPI's formatting parameters, other than captions, are honored.

Recent Folder List

WPI remembers the last 10 folders visited via the Browse or Favorites buttons. These 10 folders may be accessed from the File | Recent Folders menu selection and purged via File | Purge Recent Folders.

Automation Features

WPI is fully scriptable, which means that it need not be driven by a point-and-click graphical user interface. Scripts may be invoked either from the WPI command line or from a WPI main screen menu.

Basic Script Structure

WPI scripts are stored in plain text files and contain no more than one "component" per logical script "line". A script may include any combination of these components:

• A comment,
• A blank line, or
• A valid command.

Note 1: A comment is delimited by '#', which must be the first non-whitespace character of a logical script line. Inline comments (i.e., comments that immediately follow a command) are not supported.

Note 2: A plain text file is usually created with a ".txt" suffix (e.g., myscript.txt). In general, word processors do not create text files unless specifically so directed via an appropriate "Save As" option. If in doubt, use Notepad or a text editor to create WPI scripts.

Note 3: Fractional numeric values must be specified using a decimal point character appropriate for the host operating system's current locale. For example, the English decimal point is the period ("."), while Germany uses a comma (","). All example fractional numeric values shown in this document assume the English locale.

Scripting Syntax

 

Simple Script Example

# Place 4 graphic files in a Word table and then terminate WPI.
# Captions and all other WPI parameters default to current WPI settings.
selection c:\temp\wpipics\analysis01.png
selection c:\temp\wpipics\analysis02.png
selection c:\temp\wpipics\piechart.bmp
selection c:\temp\wpipics\wrapup.jpg
send
exit

Moderately Useful Script Example

# Place and caption 4 graphic files in a Word table and then terminate WPI.
# Caption will be Figure 1-1, Figure 1-2, etc.
caption on
caption prefix Figure 1-
caption suffix 1
selection c:\temp\wpipics\analysis01.png
selection c:\temp\wpipics\analysis02.png
selection c:\temp\wpipics\piechart.bmp
selection c:\temp\wpipics\wrapup.jpg
send
exit

Another Moderately Useful Script Example

# Place and caption 4 graphic files in a Word table and then terminate WPI.
# Captions modified on the fly to match graphic file contents.
caption on
# create captions "Analysis 1", "Analysis 2", etc.
caption prefix Analysis
caption suffix 1
# don't move cursor out of table following insertion
postinsert same table
selection c:\temp\wpipics\analysis01.png
selection c:\temp\wpipics\analysis02.png
send
clear
# create caption "Distribution Pie Chart"
caption prefix Distribution Pie Chart
caption suffix ""
selection c:\temp\wpipics\piechart.bmp
send
clear
# create caption "Wrapup Summary"
caption prefix Wrapup Summary
selection c:\temp\wpipics\wrapup.jpg
# after final graphic inserted, step cursor out of table and down 2 lines
postinsert down 2
send
exit

Script Invocation

Scripts can be invoked from:

• The WPI command line, or
• A dialog box accessible via the File | Run... menu selection.

WPI command line syntax is as follows:

[-s <scriptfile>] [-v]

where:

-s <scriptfile>	specifies the path to a file containing WPI scripting commands
-v	indicates that before a script is executed, WPI should become visible (i.e., draw its main window) and insert small delays between each script command. This switch permits the user to monitor the script's actions in (somewhat) real time. If -v is omitted, WPI remains invisible the entire time the script executes. This command line argument is further discussed in Scripting Hints.

Scripting Hints

• If a script is invoked from the command line and the -v command line switch is not specified (i.e., run the script invisibly) and the script in question does not include a "quit" or "exit" command, then when said script is exhausted, WPI draws its main window and does not subsequently exit until manually dismissed. This behavior may or may not be desirable.
• Some commands interact with each other (i.e., are sensitive to script order). In particular, a geometry change causes WPI to immediately change a non-automatic colwidth/rowheight to reflect the new layout. Consequently, a script should always set the desired geometry before changing colwidth or rowheight. Example:

  Do this	Not this
  geometry 1x3	colwidth 2.25
  colwidth 2.25	rowheight 3
  rowheight 3	geometry 1x3 #colwidth & rowheight were just clobbered

• With respect to a Word document's formatting and configuration changes, script command execution is either immediate or buffered. Immediate Word commands are executed when encountered within a script and include:

  break   goto   kill   line    open    save   send   start
  

  Buffered Word commands are remembered and executed when a send command is encountered within a script.

  An example illustrates how buffered commands might lead to surprises. Note below the two different scripts used to move the cursor down two lines following graphics/picture insertion--one works, the other does not.

  Do This	Not This
  selection pic1	selection pic1
  selection pic2	selection pic2
  postinsert down 2	send
  send	postinsert down 2  <-- never sent to Word
  exit	exit               <-- because WPI exits here

  On the other hand, to immediately move the cursor down two lines in a running instance of Word, use these commands:

  line down
  line down
  

• Be sure to read the user interface usage hints section of this reference manual. Pay particular attention to the discussion of creation of multiple tables.

Scripting Versus WPI Configuration Settings

Changes made via a script (e.g., document style, paper width, etc.) do not affect WPI's configuration settings, which are accessed via the Edit | Configuration menu.