3 Viewing Documents
This chapter includes the following sections:
3.1 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
3.1.1 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.
3.1.2 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
3.2 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.
3.3 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