Skip Headers
Oracle® Outside In Viewer for ActiveX Developer's Guide
Release 8.3.7

Part Number E12847-02
Go to Documentation Home
Go to Table of Contents
Go to Index
Go to Feedback page
Contact Us

Go to previous page
Go to next page
View PDF

4 User Interface Options

The Outside In Viewer contains a default user interface to process the user's mouse and keyboard events.

4.1 Text Selection

After a document has been loaded into the viewer, the user may scroll through the document in a manner similar to many of the word processing packages available. This also includes the ability to select text. Whenever a user changes the currently selected text or selects text for the first time, a SelChange event (see Section A.4.25, "SelChange") will be generated. The programmer can identify the text that is selected by looking at the SelectionAnchor and SelectionEnd properties(see Section A.2.78, "SelectionAnchor," and Section A.2.79, "SelectionEnd") .

Text can be programmatically selected by setting the SelectionAnchor or SelectionEnd properties to a valid OixPos object or by calling the SelectAll method (see Section A.3.39, "SelectAll") to cause all text in the viewer to be selected. For a discussion on how to set an OixPos object/variable, see Section 5.2, "Positions."

The following code shows how to use this API.

Private Sub oixctrl1_SelChange()
   Dim NumberofCharsSelected As Long

   Rem ** Each time the selection is changed, update a text field 
   Rem    indicating the number of characters which are
   Rem    "selected" **

   NumberofCharsSelected = 
   Abs(oixctrl1.GetActualCount(oixctrl1.SelectionAnchor) -
   Selection_Ctrl.Caption = NumberofCharsSelected
End Sub

Private Sub SelectAll_Ctrl_Click()
   Rem ** When the button is pressed, select all of the text
   Rem    within the control. This will generate a SelChange 
   Rem    event which in turn will update the selection count 
   Rem    text field **

End Sub

4.2 Menus

When the user right clicks on the viewer window, the application will receive a ContextMenu event (see Section A.4.3, "ContextMenu"). The application then has the opportunity to present the user with a pop-up menu selection. If the application does not handle this event and the DoContextMenu property (see Section A.2.31, "DoContextMenu") is set to TRUE, the default viewer context menu will be displayed, otherwise, the right click is ignored. In either case, the ContextMenu event will be generated.

The following are screen images of the viewer's default context menus.

Figure 4-1 Default Context Zoom Menu

Screen image of default Zoom menu

Figure 4-2 Default Context Size Menu

Screen image of default Size menu

Figure 4-3 Default Context Rotation Menu

Screen image of default Rotation menu

Figure 4-4 Default Context Options Menu

Screen image of default Options menu

The following example shows how to respond to the ContextMenu event (see Section A.4.3, "ContextMenu") to display a custom menu (also shown).

Private Sub ContextMenu_Ctrl_Click()
   Rem ** Checkbox to enable/disable control's default 
   Rem    context menus is pressed.

   oixctrl1.DoContextMenu = ContextMenu_Ctrl.Value
End Sub

Private Sub oixctrl1_ContextMenu(ByVal lXPos As Long, ByVal 
   lYPos As Long)

   Rem ** User has pressed the right mouse button. Therefore 
   Rem    we will display our context menu **

   oixctrl1.DoContextMenu = False   ' Turn off control's 
                                    ' default context menu

ContextMenu_Ctrl.Value = 0
   PopupMenu Form1.ContextMenu_Menu ' Pop up our context 
                                    ' menu. Menu selections
                                    ' come back as events
End Sub
Private Sub OpenFile_Menu_Click()
   Rem ** Popup menu Open File is selected **

   OpenFile_Click ' Simulate a press of the Open File button
End Sub

Private Sub percent50_menu_Click()
   Rem ** Popup submenu 50% is selected **

   oixctrl1.FontScalingFactor = 50
   oixctrl1.WPDisplayMode = 1 ' Fontscaling factor only works in 
                              ' draft mode so we'll change it for 
                              ' the user
End Sub
Private Sub percent100_menu_Click()
   Rem ** Popup submenu 100% is selected **

   oixctrl1.FontScalingFactor = 100
End Sub
Private Sub percent200_menu_Click()
   Rem ** Popup submenu 200% is selected **
   oixctrl1.FontScalingFactor = 200
   oixctrl1.WPDisplayMode = 1 ' Change into 
                          ' draft mode 
                          ' so 
                          ' FontscalingFactor
                          ' is shown
End Sub

4.3 Dialogs

Each of the viewing/printing/clipboard operations supply a default dialog box to allow the user to customize the processing of the document. These are invoked by calling the DisplayOpetions, PrintOptions, and ClipboardOptions methods (see Section A.3.15, "DisplayOptions,", Section A.3.35, "PrintOptions," and Section A.3.9, "ClipboardOptions"). Prior to the display of these dialog boxes, the application will receive an EnableApp event (see Section A.4.6, "EnableApp") with a parameter of FALSE to allow the developer to disable any code that might affect the view window. Changes in the dialog options will be reflected by updates to the corresponding property values once you click OK. Also, for each option changed, an OptionChange event (see Section A.4.19, "OptionChange") will be generated. These events will be generated en-masse after clicking OK followed by an EnableApp event with a parameter of TRUE.

Changes to the property values will remain in effect only as long as the application is running. If these user preferences are to remain persistent, it is up to the application to save and restore the user choices upon application termination and startup.

The following code shows the use of these methods and events.

Private Sub DoPrtOptions_Menu_Click()
   CustomShowDialog 2, 0
End Sub 

Private Sub CustomShowDialog(ByVal iDialog, ByVal iRemoveOption)
   Rem ** Display the dialog based on the parameter
   Select Case iDialog
      Case 1: oixctrl1.DisplayOptions
      Case 2: oixctrl1.PrintOptions
      Case 3: oixctrl1.ClipboardOptions
End Select
End Sub

Private Sub oixctrl1_OptionChange(ByVal lOptionId As Long)
   Rem ** This event handler writes all of the options out to an
   Rem    .ini file as they are changed **

   Select Case lOptionId
          bSuccess = OSWritePrivateProfileString("Options", 
              "DialogFlags", oixctrl1.DialogFlags, "d:\sample.ini")
   ' other case statements omitted for brevity 
   End Select 
End Sub

The following images are the default dialog boxes:

Figure 4-5 Clipboard Options Dialogs

Screen images of the Clipboard Options dialogs

Figure 4-6 Display Options Dialogs

Screen images of the Display Options dialogs

Figure 4-7 Print Options Dialogs

Screen images of the Print Options dialogs

Each of the Display Options, Clipboard Options, Print Options and Font Selection dialogs has a help button to provide the user with additional information regarding the options presented. Each time a help button is pressed, the application will receive a DoHelp event (see Section A.4.5, "DoHelp") indicating which dialog box the user currently has displayed. Because there is no default help file for the viewer, the developer should either display customized help, or remove the help button from the default dialogs to prevent the event from occurring.

Private Sub oixctrl1_DoHelp(ByVal iDialog As Integer)
   Dim l As Long
   l = iDialog
   nRet = OSWinHelp(Form1.hwnd, "sample.hlp", 8, l)
End Sub

The Help and More buttons may be removed from the default dialog boxes by setting the DialogFlags property (see Section A.2.27, "DialogFlags"). This property also controls which menu items appear on the default context menus. The following values may be OR-ed together to change default appearance of the menus and dialog boxes.

Figure 4-8 Display Options Dialog

Screen image of Display Options dialog with description

Dialog box flags:

Menu Flags:

Outside In has been modularized to allow for internationalization and/or customization of the default dialog boxes and string resources. By default, the name of the dialog resource library is SCCLO.DLL. Alternate resource libraries may be specified programmatically at runtime by setting the ResourceLibraryID property (see Section A.2.77, "ResourceLibraryID"). All resource libraries must conform to the naming convention SCCLO??.DLL. The ResourceLibraryID property would be set to access a different set of resources.

Private Sub DspOptions_Menu_Click()
   DspOptions_Menu.Checked = Not DspOptions_Menu.Checked
   ' Check to see if all three checks are off, if so remove 
   ' the entire options menu

   If (Not ClpOptions_Menu.Checked And Not 
           PrtOptions_Menu.Checked And Not 
           DspOptions_Menu.Checked) Then
      CustomShowDialog 0, -4
      CustomShowDialog 0, 4
   End If
      If DspOptions_Menu.Checked = False Then
         CustomShowDialog 0, -1
      CustomShowDialog 0, 1
   End If
End Sub

Private Sub CustomShowDialog(ByVal iDialog, ByVal iRemoveOption)
   Rem ** Display the dialog based on the parameter **
   Select Case iDialog
      Case 1-3: ' shown in previous example
      Case 0: Select Case iRemoveOption
         Case -1:
            oixctrl1.DialogFlags = 
            oixctrl1.DialogFlags Or 16 ' remove display 
                                       ' options from menu

         Case -2:
            oixctrl1.DialogFlags = 
            oixctrl1.DialogFlags Or 32 ' remove print options 
                                       ' from menu
         Case -3:
            oixctrl1.DialogFlags = 
            oixctrl1.DialogFlags Or 64   ' remove clipboard 
                                         ' options from menu
         Case -4:
            oixctrl1.DialogFlags = 
            oixctrl1.DialogFlags Or 8    ' remove entire 
                                         ' options menu
         Case 1:
            oixctrl1.DialogFlags = 
            oixctrl1.DialogFlags And Not 16    ' remove flag
         Case 2:
            oixctrl1.DialogFlags = 
            oixctrl1.DialogFlags And Not 32    ' remove flag
         Case 3:
            oixctrl1.DialogFlags = 
            oixctrl1.DialogFlags And Not 64    ' remove flag
         Case 4:
            oixctrl1.DialogFlags = 
            oixctrl1.DialogFlags And Not 8     ' remove flag
         End Select
   End Select

4.4 Scroll Bars

The Outside In viewer, by default, displays horizontal and vertical scroll bars within the viewing window. These scroll bars allow the user to page through the file as needed. If the developer, however, needs to create and control scroll bars external to the ActiveX component, the default viewer scroll bars may be hidden by setting the HScrollbar and VScrollbar properties (see Section A.2.47, "HScrollbar," and Section A.2.107, "VScrollbar") to FALSE.

As the currently viewed document is read into the viewer, the scrollbar thumb size will change to indicate the amount of viewed text relative to the entire document size. The maximum and minimum values will also change to reflect the actual size of the document (or at least the amount that has been read by the viewer). The developer can coordinate the external scrollbars by reacting to the HScrollPageSize and VScrollPageSize events (see Section A.4.13, "HScrollPageSize," and Section A.4.29, "VScrollPageSize") to set the thumb size and the HScrollRange and VScrollRange events (see Section A.4.15, "HScrollRange," and Section A.4.31, "VScrollRange") to set the scrollbar minimum and maximum values. Because reading the document is a background process, the developer is likely to see many of these events generated before the entire document size is known. The values that are passed to the HScrollRange and VScrollRange event handlers are abstract and relative to the type of file being viewed and consequently the display engine in use. For example, for a bitmap image the maximum values will be the number of pixels in the X/Y directions.

When the document being viewed completely fits within the viewing window, the scrollbars will be disabled and the VScrollState and HScrollState events (see Section A.4.32, "VScrollState," and Section A.4.16, "HScrollState") will be generated to allow the external scrollbars to be disabled or hidden.

Whenever the user scrolls through the document either using the scroll bars or the page up/down keys, HScrollPosition and VScrollPostion events will be generated to allow the external scroll bars to be repositioned. The position values passed to the event handler will be relative to the minimum and maximum values for the scrollbar and will vary in units based on the type of file being viewed.

REM ** Two scrollbars external to the Outside In viewer 
REM    Hscroll_Ctrl and Vscroll_Ctrl are used to demonstrate 
REM    the use of these event handlers. **

Private Sub oixctrl1_HScrollState(ByVal bEnabled As Long)
   If bEnabled = 1 Then
      HScroll_Ctrl.Visible = True
      HScroll_Ctrl.Visible = False
   End If
End Sub

Private Sub oixctrl1_VScrollState(ByVal bEnabled As Long)
   If bEnabled = 1 Then
      VScroll_Ctrl.Visible = True
      VScroll_Ctrl.Visible = False
   End If
End Sub

Private Sub oixctrl1_HScrollPageSize(ByVal lPageSize As Long)
   HScroll_Ctrl.LargeChange = lPageSize
End Sub

Private Sub oixctrl1_VScrollPageSize(ByVal lPageSize As Long)
   VScroll_Ctrl.LargeChange = lPageSize
End Sub

Private Sub oixctrl1_HScrollRange(ByVal lMin As Long, ByVal lMax 
   As Long)
   HScroll_Ctrl.Min = lMin
   HScroll_Ctrl.Max = lMax - HScroll_Ctrl.LargeChange
End Sub

Private Sub oixctrl1_VScrollRange(ByVal lMin As Long, ByVal lMax 
   As Long)
   VScroll_Ctrl.Min = lMin
   VScroll_Ctrl.Max = lMax - VScroll_Ctrl.LargeChange
End Sub

Private Sub oixctrl1_VScrollPosition(ByVal lPosition As Long)
   VScroll_Ctrl.Value = lPosition
   End Sub

Private Sub oixctrl1_HScrollPosition(ByVal lPosition As Long)
   HScroll_Ctrl.Value = lPosition
   End Sub

To facilitate communication from the external scroll bars to the viewer, the methods HScroll and VScroll (see Section A.3.29, "HScroll," and Section A.3.45, "VScroll") may be invoked to scroll the viewed document programmatically. These methods take two parameters: the type of scroll (line up, line down, page up, page down or absolute position) and the position relative to the scroll bar's minimum and maximum values. Note the term 'position' is not related to the OixPos object that is used in searching, annotations, and text selection.

Private Sub HScroll_Ctrl_Change()
   oixctrl1.HScroll SCCSB_POSITION, HScroll_Ctrl.Value 
   'SCCSB_POSITION Const = 7
End Sub

Private Sub VScroll_Ctrl_Change()
   oixctrl1.VScroll SCCSB_POSITION, VScroll_Ctrl.Value
End Sub

4.5 Miscellaneous

The Keydown event (see Section A.4.17, "Keydown") is generated each time the user presses a key on the keyboard while the ActiveX control has focus. Each keystroke is passed as a virtual keycode to the event handler so that developer can define customized actions for specific keys.

Private Sub oixctrl2_Keydown(ByVal lVKey As Long)
   Rem ** If ESC is pressed, make the primary viewer oixctrl1 
   Rem    visible **

   If (lVKey = vbKeyEscape) Then
      oixctrl2.Visible = False
      oixctrl1.Visible = True
   End If
End Sub
End Sub

The IdleBitmap method (see Section A.3.30, "IdleBitmap") overrides the default empty viewer splash screen. The method takes two parameters: the module (DLL) instance returned from Windows API routine LoadModule and the resource ID of the bitmap stored in the module. The following example shows how to accomplish this from within Visual Basic. The sample.rc file is compiled with the standard rc.exe shipped with Visual C++. The resulting sample.res is added to the Visual Basic project using the Project/Add File menu option.

The bitmap will only display when the application is built as an .exe.

-----begin sample.rc-----
#include <windows.h>

1000 BITMAP oi.bmp
-----end sample.rc-----

Private Sub Form_Load()
       ' other initialization done here
   oixctrl1.IdleBitmap App.hInstance, 1000
End Sub

To change the magnification level of a bitmap or vector image, the ImgZoom and ImgShowFullScreen methods (see Section A.3.32, "ImgZoom," and Section A.3.31, "ImgShowFullScreen") may be called. ImgZoom can scale the image to a given percent level, zoom in/out, zoom to the current selection or restore the image to its original state. Each time the image is zoomed in or out, the magnification level will double or half, respectively. The ImgShowFullScreen method causes the viewer to take over the entire screen and display the image. The viewer will continue to display the image full screen until the user presses the ESC key or ImgShowFullScreen is invoked with a parameter of FALSE.

Private Sub oixctrl1_Keydown(ByVal lVKey As Long)

   Rem ** Handle special Ctrl-key combinations to zoom on an 
   Rem    image. **

   If (lVKey And vbCtrlMask) > 0 Then
   Select Case lVKey And Not vbCtrlMask
   Case vbKeyAdd:      oixctrl1.IMGZoom 1           ' Zoom 
                                                    ' In
   Case vbKeySubtract: oixctrl1.IMGZoom 2           ' Zoom 
                                                    ' Out
   Case vbKeyMultiply: oixctrl1.IMGShowFullScreen 1 ' Zoom 
                                                    ' Full
                                                    ' screen
    Case vbKey1:  oixctrl1.IMGXZoomPercent = 100    ' Zoom to 
                                                    ' 100%
                  oixctrl1.IMGYZoomPercent = 100
                  oixctrl1.IMGZoom 0 
    Case vbKey2:  oixctrl1.IMGXZoomPercent = 200   ' Zoom to 
                                                   ' 200%
                  oixctrl1.IMGYZoomPercent = 200
                  oixctrl1.IMGZoom 0
    Case vbKey3:  oixctrl1.IMGXZoomPercent = 300   ' Zoom to 
                                                   ' 300%
                  oixctrl1.IMGYZoomPercent = 300
                  oixctrl1.IMGZoom 0
    Case vbKey4:  oixctrl1.IMGXZoomPercent = 400   ' Zoom to 
                                                   ' 400%
                  oixctrl1.IMGYZoomPercent = 400
   End Select
   End If
End Sub

When an archive file is displayed, the individual files contained within the document may be extracted by calling the ArchiveSave method (see Section A.3.6, "ArchiveSave"). This method can save all of the files in the document or just the selected files. A directory selection dialog box will be displayed for specification of the output location.

Private Sub SaveArchive_Menu_Click()
   oixctrl1.ArchiveSave 1 ' Save selected archive 
                          ' file 0 = save all files
End Sub

4.6 Display Engine Options

The following property is available to customize the units for page margins.

The following properties control how vector and bitmap images are displayed, printed and scaled in the viewer.

When the Word Processor display engine is loaded, the viewed document will be displayed according to the following properties.

The archive display engine has these properties.

The Database display engine displays, prints and copies to the clipboard document information according to the following properties.

When displaying spreadsheet documents, the properties in the following list control the clipboard data, the display and print formatting.