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