|Oracle® Outside In Viewer for ActiveX Developer's Guide
Part Number E12847-05
The Outside In Viewer contains a default user interface to process the user's mouse and keyboard events.
Text that is selected by the user may be accessed by the programmer for use in printing, searching or annotations.
Right mouse clicks can invoke a context-sensitive menu for processing/viewing options.
Default property values may be set by the user via viewer supplied dialog boxes.
The viewer's scroll bars may be programmatically accessed and display options may be set for each of the viewer's display engines.
This chapter includes the following sections:
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.80, "SelectionAnchor," and Section A.2.81, "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.40, "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) - oixctrl1.GetActualCount(oixctrl1.SelectionEnd)) 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 ** oixctrl1.SelectAll End Sub
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.32, "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.
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
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.36, "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 Case SCCID_DIALOGFLAGS: 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:
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.28, "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.
Dialog box flags:
SCCVW_DIALOG_NOHELP: Remove the help button.
SCCVW_DIALOG_NOMORE: Remove the more button.
SCCVW_DIALOG_NOADDOPTIONSTOMENU: Remove the Options submenu.
SCCVW_DIALOG_NOADDDISPLAYTOMENU: Remove the Display Options from the Options submenu.
SCCVW_DIALOG_NOADDDISPLAYTOMENU: Remove the Print Options from the Options submenu.
SCCVW_DIALOG_NOADDCLIPBOARDTOMENU: Remove the Clipboard Options from the Options submenu.
SCCVW_DIALOG_NOADDDOPRINTTOMENU: Remove the Print menu item.
SCCVW_DIALOG_NOADDDOCOPYTOMENU: Remove the Copy menu item
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.79, "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 Else CustomShowDialog 0, 4 End If If DspOptions_Menu.Checked = False Then CustomShowDialog 0, -1 Else 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 EndSub
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.48, "HScrollbar," and Section A.2.109, "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.34, "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 Else HScroll_Ctrl.Visible = False End If End Sub Private Sub oixctrl1_VScrollState(ByVal bEnabled As Long) If bEnabled = 1 Then VScroll_Ctrl.Visible = True Else 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.30, "HScroll," and Section A.3.47, "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
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.31, "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.33, "ImgZoom," and Section A.3.32, "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 oixctrl1.IMGZoom 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
The following property is available to customize the units for page margins.
IntlFlags: TRUE. Use English units for page margins, otherwise use metric unit for page margins.
The following properties control how vector and bitmap images are displayed, printed and scaled in the viewer.
ImgXZoomPercent, ImgYZoomPercent: When the ImgZoom method is called with a zoom type of 0, these properties indicate how much to zoom. For example, a *ZoomPercent of 200 will double the image size each time ImgZoom is invoked.
BmpFitMode: When a bitmap is viewed this parameter determines how it displayed relative to the viewing window.
1: Bitmap is shown actual size.
2: Bitmap will be stretched to fit within the view window maintaining its aspect ratio. Depending on the window's aspect ratio and the bitmap's aspect ratio, extra space can appear in either the horizontal or vertical direction.
3: Fit the bitmap into the window's height. Depending on the width of the window relative to the bitmap, the full width of the image may not fit within the viewer.
4: Fit the bitmap into the window's width. Depending on the height of the window relative to the bitmap, the full height of the image may not fit within the viewer.
BmpPrintAspect: When printing a bitmap, this property directs the printer to do one of the following:
1: Stretch the image to fit within the print margins while still maintaining the bitmap's aspect ratio.
2: Stretch the image to completely fill the area within the print margins. Aspect ratio will not be maintained.
3: Use the size as specified by the image.
BmpPrintBorder: TRUE. Draw a one-pixel border around the image when printing, otherwise no border is drawn.
BmpDither: TRUE. Dither the bitmap on low resolution displays to more accurately represent the image, otherwise, do not dither the image.
BmpDitherAvailable: This read-only property indicates whether the current image can be dithered.
BmpRotation When displaying a bitmap, the following property values determine it's orientation:
0: No rotation
90: Bitmaps are rotated 90 clockwise
180: Bitmaps are rotated 180 clockwise or are upside down.
270: Bitmaps are rotated 270 clockwise.
VecFitMode: Fit the vector drawing into the window disregarding the original image aspect ratio.
VecPrintAspect: When printing vector images the property direct the printer to do one of the following actions:
1: Stretch the image to fit within the print margins while still maintaining the vector image aspect ratio.
2: Stretch the image to completely fill the area within the print margins. Aspect ratio will NOT be maintained.
3: Use the size as specified by the drawing.
VecPrintBorder: TRUE. Draw a one-pixel border around the image when printing, otherwise no border is drawn.
VecPrintBackground: TRUE. If a vector image has a background defined, then it will be printed, otherwise no background will be printed.
VecShowBackground: TRUE. If a vector image has a background defined, then it will be displayed in the viewer, otherwise backgrounds will not be displayed for vector images.
When the Word Processor display engine is loaded, the viewed document will be displayed according to the following properties.
WPDisplayMode: The document will be displayed in one of the following modes. The default value is 2 - Normal.
1: Draft mode. The document will be displayed using a single font as specified in the DisplayFont property (see Section A.2.31, "DisplayFont"). Embedded graphics and borders will not be displayed and all text will be wrapped to the size of the view window.
2: Normal mode. The text will be wrapped to the size of the view window and all supported formatting will be applied.
3: Preview mode. All supported formatted will be applied and the text will be wrapped as it will be printed.
WPFitMode: When displaying the document in preview mode (see Section A.2.111, "WPDisplayMode") this property controls how the preview will be scaled.
1: Original. Show as actual size.
2: Window. Fit preview within the window.
3: Window Width. Fit preview within the width of the window. Not all of the page may be visible in the vertical direction.
WPWrapToWindow: When displaying the document in draft or normal mode (see Section A.2.111, "WPDisplayMode") this property determines whether or not the text is wrapped to the size of the viewer window.
TRUE: Text will be wrapped in draft and normal mode, otherwise text will not be wrapped, but may be viewed by scrolling the window to the right using the horizontal scroll bar.
The archive display engine has these properties.
ArchiveSortOrder: When files are listed in the archive display engine, they will be sorted according to this property value:
1: None. Display files in the order in which they appear in the archive.
2: Name. Sort files by filename.
3: Size. Sort files by file size.
4: Date. Sort file by creation date.
ArchiveSortDescending: TRUE. Reverses the order of ArchiveSortOrder (see Section A.2.8, "ArchiveSortOrder"); otherwise, files are sorted ascending according to ArchiveSortOrder.
The Database display engine displays, prints and copies to the clipboard document information according to the following properties.
DBClipboard: Specifies the format of the clipboard data.
1: Table. For RTF and AMI clipboard formats the data will be placed on the clipboard as a table.
2: Optimized Tabs. Each field will be separated by a TAB character, except when a field is empty.
3: Tabs. Each field will be delimited by a TAB character.
DBFieldNamesToClip: TRUE. Field names will be copied to the clipboard; otherwise, field names are not copied.
DBDraftMode: When displaying database data this property turns formatting on and off.
TRUE: Limited formatting is displayed; otherwise, all supported formatting is displayed
DBShowGridLines: When displaying database data this property turns the background grid on/off.
TRUE: A dotted line grid is displayed; otherwise, grid lines are not displayed.
DBPrintFit: Specifies how the database data will be fitted to the printed page.
1: None. The data will be printed actual size on as many pages as is needed.
2: Page. The data will be scaled to completely fit on one page.
3: Width. The data will be scaled to fill the width of the page.
4: Height. The data will be scaled to fill the height of the page.
DBPrintGridLines: TRUE: Grid lines will be printed; otherwise, grid lines will not be printed.
DBPrintHeadings: TRUE: Field names will be printed along with the data; otherwise, field names are omitted from the printed data.
When displaying spreadsheet documents, the properties in the following list control the clipboard data, the display and print formatting.
SSClipboard: Specifies the format of the clipboard data.
0: Table. For RTF and AMI clipboard formats the data will be placed on the clipboard as a table.
1: Optimized Tabs. Each cell will be separated by a tab character, except when a cell is empty.
2: Tabs. Each cell will be delimited by a tab character.
SSRowColNamesToClip: TRUE: Row and Column headers will be copied to the clipboard; otherwise, headers are not copied.
SSDraftMode: TRUE: Limited formatting is displayed; otherwise. all supported formatting is displayed.
SSShowGridLines: TRUE: A dotted line grid is displayed; otherwise, grid lines are not displayed.
SSPrintFit: Specifies how the spreadsheet will be fitted to the printed page.
0: None. The spreadsheet will be printed actual size on as many pages as is needed.
1: Page. The spreadsheet will be scaled to fit on one page.
2: Width. The spreadsheet will be scaled to fill the width of the page.
3: Height. The spreadsheet will be scaled to fill the height of the page.
4: Scale. The spreadsheet will be scaled according to the SSPrintScalePercent property (see Section A.2.88, "SSPrintScalePercent").
SSPrintGridLines: TRUE: Grid lines will be printed; otherwise, grid lines will not be printed
SSPrintHeadings: TRUE: Row and Column headings will be printed along with the data; otherwise, headings are omitted from the printed data.
SSPrintScalePercent: Specifies the scale factor to be use when the SSPrintFit property (see Section A.2.85, "SSPrintFit") is set to 4. This is a percentage of actual size.
SSPrintScaleXHigh: Specifies how many vertical pages the printed spreadsheet is to fit within. This is used when the SSPrintFit property is set to 5.
SSPrintScaleXWide: Specifies how many horizontal pages the printed spreadsheet is to fit within. This is used only when the SSPrintFit property is set to 5.
SSPrintDirection: Specifies orientation:
0: Print spreadsheet across and then down.
1: Print spreadsheet down and then across.