Viewing Documents

The Outside In viewing technology centers around the view window. Documents may be processed for viewing, printing or exchange via the clipboard. The methods, events and properties that control this process are described in this chapter.

This chapter includes the following sections:

• Displaying Documents

• Printing

• Clipboard

Displaying Documents

One of the first requests made to the viewing control is to load a document. The viewer will automatically detect the type of file (based on file content) and will display the document. Documents are loaded by passing the ViewFile method (see ViewFile) a filename (or a flag to display the file selection dialog), and optional display information. When the viewer receives these parameters, the following will occur.

• Any file currently opened and displayed will be closed before the new document is processed.

• If specified, the system file selection dialog box will be displayed to collect the user's choice of document. In this case, the filename which is passed in the second parameter (FileSpec) will be used to initialize the file selection dialog box, otherwise the file will be validated and opened.

• Once the file has been identified and displayed, the FileInfoFileId properties (see FileInfoFileId) will contain information about the document type and the FileInfoName (see FileInfoName), and FileInfoDisplayName (see FileInfoDisplayName) will contain the actual file name and display name passed to the ViewFile method (see ViewFile), respectively.

• The Clear method (see Clear) may be called to reset the viewer to its non-viewing state.

The following example illustrates the use of these methods and properties.

Private Sub Clear_Click()
   Rem ** When the clear button is pressed, clear the file 
   Rem from the viewer **
   
   oixctrl1.Clear
End Sub
   
Private Sub OpenFile_Click()

   Dim Error As Boolean

Rem ** Load the document returned from the Open File dialog box **
   Error = oixctrl1.ViewFile True, ""

Rem ** File information displayed **
   FileInfoFileIdName_Ctrl.Caption = oixctrl1.FileInfoFileIdName
   FileInfoFileID_Ctrl.Caption = oixctrl1.FileInfoFileID
   FileInfoName_Ctrl.Caption = oixctrl1.FileInfoName
   FileInfoDisplayName_Ctrl.Caption = oixctrl1.FileInfoDisplayName
End Sub

Special Considerations

There are a few formats that contain links to other documents. For example, an archive file (.ZIP) contains many files. The programmer may allow the user to open an archive file and subsequently view an embedded file by double clicking the filename as shown by the archive display engine. Similarly, documents with hyperlinks may be processed when the user selects a hyperlink object in the source document. In these situations, a ViewThisFile event (see ViewThisFile) will be generated to allow the programmer to handle the display of the embedded file as the viewer does not directly process these requests. It is up to the programmer to call the ViewFile with the appropriate parameters to display this new document.

The developer should not call the control’s ViewFile method (see ViewFile) from within a ViewThisFile event (see ViewThisFile). This will produce unpredictable results. The programmer can, however, call another control’s ViewFile method within the ViewThisFile event handler.

Notifications

Whenever the viewer is called to change the document being displayed, a FileChange event (see FileChange) will be generated. Two parameters allow the event handler to determine if a file is being opened or closed, and, if a file is being closed, whether or not it was due to a new file being opened. In this case, the user should expect another FileChange event to occur. The name of the file being opened or closed will be stored in the FileInfo* properties.

Outside In uses different display engines to present the document to the user through the viewing window. Each of these display engines can be configured with a default viewing mode, font, and other appearance-related options (for example, grid lines). When a different display engine is about to be loaded, the viewer will generate a DisplayEngineChange event (see DisplayEngineChange). The new display engine information can be found in the DisplayEngineName (see DisplayEngineName) and DisplayEngineType properties (see DisplayEngineType). These events will also be generated when a ViewFile method (see ViewFile) is called with a document that requires a different display engine that is currently loaded.

Private Sub oixctrl1_DisplayEngineChange()
   Rem ** Update information on the screen **
   DspEngineName_Ctrl.Caption = oixctrl1.DisplayEngineName
   DspEngineType_Ctrl.Caption = oixctrl1.DisplayEngineType
End Sub

Private Sub oixctrl1_FileChange(ByVal bOpen As Long, ByVal bOpenFollowing As Long)
   If (bOpen) Then
      Rem ** File information displayed **
      FileInfoFileIdName_Ctrl.Caption = oixctrl1.FileInfoFileIdName
      FileInfoFileID_Ctrl.Caption = oixctrl1.FileInfoFileId
      FileInfoName_Ctrl.Caption = oixctrl1.FileInfoName
      FileInfoDisplayName_Ctrl.Caption = oixctrl1.FileInfoDisplayName
   Else
      FileInfoFileIdName_Ctrl.Caption = ""
      FileInfoFileID_Ctrl.Caption = ""
      FileInfoName_Ctrl.Caption = ""
      FileInfoDisplayName_Ctrl.Caption = ""
   End If
End Sub

Private Sub oixctrl1_ViewThisFile(ByVal FileSpec As Variant, ByVal iSpecType As Integer, iReturn As Integer)
   Rem ** Display file in another Viewer window. Note: this
   Rem    nested file cannot be viewed in the same viewer.
   Rem    Therefore, to simulate this appearance, oixctrl2
   Rem    is the same size and location as oixctrl1 on
   Rem    the form and will be used to display embedded files
   Rem    (e.g. from an archive format). Visibility
   Rem    is swapped to view the embedded file. The Esc key swaps
   Rem    back to the primary viewer. **

   oixctrl2.ViewFile 0, FileSpec, iSpecType
   oixctrl2.Visible = True
   oixctrl1.Visible = False

   Rem ** file is being viewed **
   iReturn = 1
End Sub

Outside In attempts to identify the type of document specified in the ViewFile method (see ViewFile). However, there may be reasons that prevent the viewer from correctly identifying the file. In these cases, the viewer can be configured to display the document using a default-viewing format. This is configured by setting the FallbackFormat property (see FallbackFormat) to an appropriate value.

When viewing spreadsheets, databases or documents in draft mode, the DisplayFont property (see DisplayFont) may be set to a preferred font using a font object data type. Similarly, the viewer can be configured to scale the document fonts from 50% to 300% of the normal size (as specified in the document) with the FontScalingFactor property (see FontScalingFactor). The following code illustrates the use of these properties.

Private Sub Fallback_Ctrl_Click()
If (Fallback_Ctrl.ListIndex > 1) Then
   oixctrl1.FallbackFormat = Fallback_Ctrl.ListIndex - 1
End If
End Sub 

Private Sub DisplayFont_Click()
   Dim NewFont As New StdFont

   Rem ** Show common font selection dialog, collect font info,
   Rem    update button text. **

   CommonDialog1.Flags = cdlCFBoth
   CommonDialog1.ShowFont
   DisplayFont.Caption = "DisplayFont: " + CommonDialog1.FontName

   Rem ** Put font information into StdFont variable and pass it
   Rem    off to oixctrl1. **

   NewFont.Size = CommonDialog1.FontSize
   NewFont.Name = CommonDialog1.FontName

   Set oixctrl1.DisplayFont = NewFont

End Sub

Private Sub FontScalingFactor_Ctrl_Click()
   Rem ** FontScalingfactor_Ctrl is a list box with scaling
   Rem    percentages listed. Each item has an ItemData value 
   Rem    equal to the integer equivalent of the text. **

   oixctrl1.FontScalingFactor = FontScalingFactor_Ctrl.
   ItemData(FontScalingFactor_Ctrl.ListIndex)

End Sub

Printing

The Outside In viewer also provides an API subset to handle print request from the application. The programmer may want to handle some of the details of printing, such as displaying an Abort dialog, specifying an application provided hDC, or may choose to let the viewer default routines handle all print requests.

There are two methods associated with the printing subsystem: PrintSetup (see PrintSetup) and PrintOI (see PrintOI). The PrintSetup routine displays the system printer selection dialog box and allows the user to select the desired printer as well as change its settings. Upon return, the appropriate control properties will be populated with the selected printer information. The PrintOI method prints the currently viewed file. Parameters to the PrintOI routine control whether the Print Dialog box is displayed before printing, which of the printer properties to use for printer selection, and how the abort process is handled. The following code shows an example of using these methods.

Private Sub PrintSetup_Ctrl_Click()
   Rem ** Reset the abort event counter **
   PrinterAbort_Ctrl.Caption = 0

   Rem ** Invoke the system printer dialog box **
   oixctrl1.PrintSetup

   Rem ** Print the currently viewed file:
   Rem    P1   1   Display print setup dialog box(again)
   Rem    P2   128 Generate PrinterAbort Events. Other ORable
   Rem    flags include
   Rem      1 - Use the PrinterDC as stored in the property
   Rem          value instead of the one obtained from the
                default printer
   Rem      2 - If bit 1 is set, get the printer from the
                PrinterName, PrinterPort and PrinterDriver 
   Rem          properties, otherwise, use the PrinterDC and
   Rem          use the PrinterName, PrinterPort and
   Rem          PrinterDriver properties only when displaying
   Rem          the standard Windows abort dialog.
   Rem    P3   0   Display the standard windows abort dialog 
   Rem          with page numbers
   Rem    P4   0   Assume that the StartDoc printer sequence has
   Rem          already been performed.

   oixctrl1.PrintOI 1, 128, 0, 0

End Sub

If specified when calling the PrintOI method, the viewer generates PrinterAbort events (see PrinterAbort) throughout the print process. The event handler receives the device context to the printer, and an error value (for example, SP_OUTOFDISK), if applicable. Before returning from the event handler, the programmer must indicate whether the print process is to continue or should be aborted. An example printer abort event handler is shown in the following code sample.

Private Sub oixctrl1_PrinterAbort(ByVal hDC As Long, ByVal Err As Long, 
   Continue As Long)

   Rem ** Update a on-screen counter to show the number of 
   Rem    times this event was received **
   PrinterAbort_Ctrl.Caption = PrinterAbort_Ctrl.Caption + 1

   Rem ** Cancel the print request on error **
   If (Err) Then
      Continue = False
   Else
      Continue = True
   End If
End Sub

The following properties control how the viewer formats the document for printing.

• PrintCollate: TRUE. Multiple copies of the document are collated, otherwise, copies of each page will be collated together.

• PrintCopies: The number of copies of the viewed document to print.

• PrintStartPage / PrintEndPage: The starting and ending pages to be printed.

• PrinterDC: A system handle to the printer device context.

• PrinterDriver: The printer driver name (for example, PSCRIPT.DRV).

• PrinterName: The name of the printer (for example, HP LaserJet IV).

• PrinterPort: The system port of the printer (for example, LPT1).

• PrintFont: When no font is specified in the file, or when printing spreadsheets, databases or documents in draft form, this property specifies the font to be used.

• PrintMarginLeft, Right, Top, Bottom: These properties specify the four page margins to be used when printing a document.

• WhatToPrint: This property specifies (in viewer terms) what part of the document is to be printed. Valid values include:

  • PRINT_ALLPAGES

  • PRINT_SELECTION

  • PRINT_PAGERANGE (will use PrintStartPage/EndPage values)

  • PRINT_CURSECTION.

• UseDocPageSettings: TRUE. The printing information stored in the original document will be used to configure the print job.

Clipboard

The Outside In viewer provides the ability to exchange document text and graphics with other applications via the system clipboard. The CopyToClip method (see CopyToClip) will place the currently viewed document onto the system clipboard in the format specified by the ToClipboard property (see ToClipboard). Fifteen different data format are supported through this method including: TEXT, RTF, AMI, WINDIB, WINMETAFILE, and others. Before copying data from the viewer to the clipboard, however, the programmer should check the value of the read-only property ClipInfo (see ClipInfo) to determine if the viewer has completely processed the file and is ready to send the data to the clipboard.

For documents that do not specify a font or for spreadsheets, databases, or documents in draft mode, the font for the clipboard data may be specified using the ClipFont property (see ClipFont).

Another way to exchange data is through a mechanism known as “Drag-N-Drop.” By setting the EnableDragNDrop property (see EnableDragNDrop) to TRUE, the user is allowed to drag selected text from the viewing window to a target application. Dragging files from the desktop or explorer to the viewer is not currently supported.

Private Sub Clipboard_Ctrl_Click()
   Rem ** Check the status of the clipboard and document
   Rem    processing. If ok, then
   Rem    place selected text on the clipboard as a windows
   Rem    metafile. **

   If (oixctrl1.ClipInfo > 0) Then
      oixctrl1.ToClipboard = SCCVW_CLIPFORMAT_WINDIB
      oixctrl1.CopyToClip
   End If
End Sub

Private Sub EnableDragNDrop_Ctrl_Click()
   Rem ** If checkbox is "checked", enable drag-n-drop from the 
   Rem    viewer otherwise
   Rem    disable it. **

   If (EnableDragNDrop_Ctrl.Value = 1) Then ' if checked
      oixctrl1.EnableDragNDrop = True
   Else
      oixctrl1.EnableDragNDrop = False
   End If

End Sub