| Oracle® Outside In Viewer Developer's Guide Release 8.4.0 Part Number E12845-03 |
|
|
View PDF |
| Oracle® Outside In Viewer Developer's Guide Release 8.4.0 Part Number E12845-03 |
|
|
View PDF |
The process of accessing the Viewer, creating the view window and sending/receiving messages is platform-dependent. However, once you have successfully created a view window, the message and structures for viewing files and manipulating the view window are fully portable.
This chapter includes the following sections:
Files are viewed by sending the SCCVW_VIEWFILE message. This message allows the caller to specify the file to be viewed in a number of ways based on the operating system being used. For instance, under Windows, the developer can specify a path name in Unicode, ANSI or OEM character sets. The message also allows the developer to specify a number of other parameters, including a name to use in display situations (this is helpful if the file is a temporary file and the real file name is known), a flag indicating the file should be deleted when it is closed (again this can be helpful with temporary files), and a parameter that forces the file to be viewed as a text or hex file.
At any time after an SCCVW_VIEWFILE call, the developer may call SCCVW_GETFILEINFO. This message returns information on the file being viewed and a text string indicating the file's format (for example, WordPerfect 4.2 or Excel 5.0). This message is often called in response to the SCCVW_FILECHANGE callback message.
In certain situations the viewer may request that another file be viewed by sending an SCCVW_VIEWTHISFILE message to the developer. The developer may ignore this message, in which case nothing will happen, or the developer may create another view window and pass on the request through the SCCVW_VIEWFILE message. There are currently two cases where this happens. The first is when the user double clicks on an entry in a view of an archive file. The archive display engine decompresses that file into a temporary file and issues a SCCVW_VIEWTHISFILE message to the developer. The second case is when the user double clicks on a non-OLE graphic that is embedded or linked to a file. Again the graphic is extracted to a temporary file and an SCCVW_VIEWTHISFILE is sent. These cases represent significant functionality to the user and it is recommended that all OEMs support the SCCVW_VIEWTHISFILE message.
SCCVW_VIEWFILE: View a file
SCCVW_FILECHANGE: Notifies developer that the file being viewed has changed
SCCVW_GETFILEINFO: Gets information about the currently viewed file
SCCVW_VIEWTHISFILE: Notifies developer that another file should be viewed
The full printing functionality of the view window can be reached by sending a single SCCVW_PRINT message. This message is totally automatic, handling all dialogs and other user interactions needed to print on any given platform. The viewer follows each operating system's guidelines for how the print UI should work.
If more control over the printing process is required, the SCCVW_PRINTEX message may be used. This message allows the developer to override any of the view window's print options and specify extra platform-specific print options while still having the view window do most of the work. For instance, under Windows, the developer may pass his or her own printer DC or specify an alternate AbortProc to use.
SCCVW_PRINT: Prints the file currently being viewed
SCCVW_PRINTEX: Prints the file under developer control
SCCVW_PRINTSETUP: Invokes platform dependent print setup dialog
The Viewer activates copy/paste functionality for each supported platform via the SCCVW_COPYTOCLIP message. When the developer calls this message, the view window generates one or more renditions of the area selected in the view and transfers them to the operating system using appropriate system calls. The option SCCID_TOCLIPBOARD allows the developer to tailor what is sent to the operating system.
At any time, the developer may call SCCVW_GETCLIPINFO to see if anything is selected in the view window. The developer will receive an SCCVW_SELCHANGE message when the selection status has changed. Used in conjunction, these two messages can be used to enable or disable a Copy button or menu item.
SCCVW_COPYTOCLIP: Copies current selection to clipboard
SCCVW_SELCHANGE: Notifies developer that the selection state has changed
SCCVW_GETCLIPINFO: Gets the current state of the selection
The Viewer provides a large array of options that give the developer and the user great control over how files look in the view window, how files get printed, how files are copied to the clipboard and a number of other aspects of the technology. The developer has two avenues available when providing these options to the user.
The developer can code his or her own dialogs and menus and call the SCCVW_SETOPTION and SCCVW_GETOPTION messages directly.
The developer can use the menus and dialogs that are part of the Viewer. Menus and dialogs are only available on certain platforms. See the implementation details for your platform for more information.
These courses are not mutually exclusive and developers may mix the viewer technologies menu and dialogs with their own to get just the level of functionality he or she desires.
Options can be set with the SCCVW_SETOPTION message and retrieved with the SCCVW_GETOPTION message. Both of these messages can set either the current value of an option or the default value of an option. The current value is the value that is active in the view window. Setting the current value of an option has an immediate effect on the view window. The default value is the value that a new view window will begin with, setting this value will have no effect on the current view window.
There are cases where the developer may wish to monitor changes to an option for display or user-interaction purposes. The SCCVW_OPTIONCHANGE message is sent whenever an option is changed.
There are three dialogs that the Viewer makes available to the developer. These dialogs are the display options dialog, the print options dialog and the clipboard options dialog. These dialogs are accessed through the SCCVW_DODIALOG message, and are totally automatic. All the developer has to do is call SCCVW_DODIALOG with the correct dialog ID and the rest of the interaction is handled by the Viewer.
The IDs used in SCCVW_DODIALOG are as follows:
SCCID_DISPLAYOPTIONSDIALOG: display options
SCCID_PRINTOPTIONSDIALOG: print options
SCCID_CLIPBOARDOPTIONSDIALOG: clipboard options
Whenever one of the Viewer's dialogs is invoked, the developer may receive SCCVW_DOHELP messages along with an SCCID indicating which dialog is displayed. The developer may then invoke help information for that dialog. There is no default action for this message, so the developer should either handle the message or set the SCCVW_DIALOG_NOHELP bit in the SCCID_DIALOGFLAGS option which removes the Help button from all the dialogs.
Each type of display engine (Document, Bitmap, Archive, etc.) has functions that are unique to that type of file. For instance, zooming, rotation and dithering are functions normally associated with graphic images, but not with spreadsheets. To handle these specialized tasks, each display engine has a menu that is tailored just for it. This menu is made available to the developer through the SCCVW_GETDISPLAYINFO message.
Some operating systems have the concept of a context menu activated by a right mouse click. On these systems, the view window will automatically handle the right click and pop-up the display engines menu plus some other menu items that are OS specific. This feature may be overridden by handling the SCCVW_CONTEXTMENU message.
The interaction between the menu, the application and the Viewer is operating-system specific.
SCCVW_SETOPTION: Sets the current or default value of an option.
SCCVW_GETOPTION: Gets the current or default value of an option.
SCCVW_DODIALOG: Invokes a built-in dialog.
SCCVW_DISPLAYCHANGE: Notifies the developer that the display engine has changed.
SCCVW_GETDISPLAYINFO: Gets information about the current display engine including its menu.
SCCVW_CONTEXTMENU: Notifies the developer that a context menu is going to be invoked and allows the developer to override it.
SCCVW_DOHELP: Notifies the developer that the Help button has been pressed in a dialog.
SCCVW_ENABLEAPP: Notifies the developer that the application should be disabled/enabled. Sent before and after dialogs and printing.
The view window offers basic text searching of documents, spreadsheets and databases. The developer can supply the UI and call SCCVW_SEARCH or let the viewer supply the UI by calling SCCVW_SEARCHDIALOG. In either case, the SCCVW_SEARCHNEXT message may then be called to repeat the search, searching forward or backward.
SCCVW_SEARCH: Search for a text string
SCCVW_SEARCHDIALOG: Bring up a search dialog and search
SCCVW_SEARCHNEXT: Search for the next occurrence of a string
During processing of any document, the developer has the option of receiving SCCVW_RAWTEXTEVENT messages. This message informs the developer that additional text is available. Once text is available, the developer can use SCCVW_GETRAWTEXT to retrieve blocks of raw text for any area of the document. Any text position can be mapped into a viewer position using SCCVW_MAPPOSITION. The developer can highlight text, hide text and/or insert icons and bitmaps at defined viewer positions using SCCVW_ADDANNOTATION. Once these annotations are added, the developer may use SCCVW_GOTOANNOTATION to jump to any given annotation or set of annotations. The developer may also receive SCCVW_ANNOTATIONEVENT messages when the user transitions, clicks, or double clicks on any annotation.
The format of a position in the document is a SCCVWPOS structure. The SCCVW_MAPPOSITION message provides a bidirectional method of translating between an actual character count (ACC) and an SCCVWPOS. The SCCVW_FINDPOSITION message provides the ability to locate a position based on certain input criteria including the current selection positions. SCCVW_SETSELECTION allows developer control of the selection. SCCVW_FINDANNOTATION provides a powerful method of locating an annotation using numerous options. SCCVW_DISPLAYPOSITION can then be used to bring the annotation into view. SCCVW_CLEARANNOTATIONS supports selective clearing of previously defined annotations. SCCVW_HILITESTYLE allows the developer to define a style that can then be referenced when adding highlight annotations.
Generally, this functionality has been used to highlight and move around search hits in indexing applications or to insert hyperlinks into the document.
To receive SCCVW_RAWTEXTEVENT messages, the developer must set the SCCVW_SYSTEM_RAWTEXT flag in the SCCVW_SYSTEMFLAGS option.
The value of this option is reset to 0 for every new view window, so it must be set every time a new window is created.
SCCVW_RAWTEXTEVENT: Notifies the developer that more text is available.
SCCVW_GETRAWTEXT: Returns raw text blocks.
SCCVW_ADDANNOTATION: Adds an annotation into the view.
SCCVW_CLEARANNOTATIONS: Clears some or all annotations.
SCCVW_GOTOANNOTATION: Go to a certain annotation.
SCCVW_ANNOTATIONEVENT: Notifies the developer that an action has been taken on an annotation.
SCCVW_FINDANNOTATION: Finds an annotation given certain input criteria.
SCCVW_FINDPOSITION: Finds a position given certain input criteria.
SCCVW_HILITESTYLE: Defines an annotation highlight style for later reference when adding annotations.
SCCVW_MAPPOSITION: Maps between an actual character count and SCCVWPOS.
SCCVW_DISPLAYPOSITION: Finds an annotation given certain input criteria.
SCCVW_SETSELECTION: Sets the current selection positions.
The view window has the ability to draw pages to an arbitrary area of an arbitrary output device. The developer must provide two rectangles, the first (output) is the actual area on the display device that should be filled. The second (format) is the area in twips (Windows) (1440 twips = one inch) or pixels (UNIX) that will be used to determine text positioning and wrapping. For instance, a Windows developer may want a thumbnail of a standard 8.5 x 11 inch page. In this case he would provide a small output area, maybe 85 x 110 pixels, but a 8.5 x 11 inch (converted to twips) format area.
Once it is initialized, the SCCVW_DRAWPAGE message can draw any page in the document.
SCCVW_DRAWPAGE: Draws a page to the specified device
SCCVW_INITDRAWPAGE: Initializes the DrawPage process
SCCVW_DEINITDRAWPAGE: De-initializes the DrawPage process
By default, the view window provides scroll bars for moving around the document, but some developers may have special UI considerations that make this behavior undesirable. The view window provides options and messages that allow the developer to override the view window's scrolling behavior. The SCCID_SCROLLFLAGS option allows the developer to selectively remove the horizontal and vertical scroll bars from the view window. The developer may then maintain his own scroll bars or other controls by handling the following notification messages:
SCCVW_SETHSCROLLSTATE: Notifies the developer of a new state for the horizontal scroll bar.
SCCVW_SETVSCROLLSTATE: Notifies the developer of a new state for the vertical scroll bar.
SCCVW_SETHSCROLLPOSITION: Notifies the developer of a new position for the horizontal scroll bar's thumb.
SCCVW_SETVSCROLLPOSITION: Notifies the developer of a new position for the vertical scroll bar's thumb.
SCCVW_SETHSCROLLRANGE: Notifies the developer of a new range for the horizontal scroll bar.
SCCVW_SETVSCROLLRANGEMIN : Notifies the developer of the minimum range for the vertical scroll bar.
SCCVW_SETVSCROLLRANGEMAX : Notifies the developer of the maximum range for the vertical scroll bar.
SCCVW_SETHSCROLLPAGESIZE: Notifies the developer of a new size for the horizontal scroll bar's thumb.
SCCVW_SETVSCROLLPAGESIZE: Notifies the developer of a new size for the vertical scroll bar's thumb.
There are three distinct areas where character sets (international language support) and character encoding (1 Byte, DBCS, 2 Byte) have an important role in the Viewer.
In the strings passed between the developer and the viewer through this API.
In the specification of files by the developer in the SCCVWVIEWFILE40 or SCCVWVIEWFILE80 structure.
In the actual viewing of files containing various character sets and encoding.
All strings sent and received by the view window are defined to be in a particular character set/encoding for any given platform.
For example, using SCCVW_SETOPTION to set the SCCID_PRINTJOBNAME option does not let the developer define the character set or encoding of the string passed. It is pre-defined by the Viewer for the platform on which the software is running.
The sole exception to the rule described in the preceding section appears in the SCCVWVIEWFILE40 or SCCVWVIEWFILE80 structure, where the developer has a number of options in the character set/encoding of the file/path information. This gives the developer more flexibility in what he/she can pass through this critical API. For example, under Windows, the developer might want to pass an OEM, ANSI or Unicode path to the Viewer.
In the current implementation of the Viewer SDK, it is the viewer's responsibility to convert all character sets coming from the filters to an appropriate character set based on the available fonts. The technology includes support for most languages, including those based on DBCS. This creates two basic scenarios concerning character sets and how they are displayed.
Scenario 1:
If the file was created by an application native to the platform on which it is being viewed, the characters are generally piped directly through the system with no modification. This has the advantage of perfect character mapping even in fonts where the glyphs themselves are different. For example a Word for Windows file being viewed by the Windows version of the Viewer should view with all characters displaying correctly, even characters in symbol sets such as Wingdings.
Scenario 2:
If the file was created on a different platform or has a private character set (WordPerfect or DCA/RFT for example) the characters are mapped into the native character set using mapping tables. This produces loss of character integrity in a number of cases. These cases include characters that do not have a corresponding character in the target character set (for example, the WordPerfect set has a large number of symbols that do not appear in ANSI or Macintosh character sets) and fonts where the glyph set is different. The technology uses a robust character/font mapping architecture that attempts to locate a font containing the required character glyph when the original font is not available.
While these two cases cover most of the character set interactions you will see, the number of permutations on this subject is huge and space prohibits us from going into the caveats for every file format in this document. If you have specific questions concerning this subject please contact Oracle Support.
This section provides information about API functions.
This function sets up a callback that the technology will periodically call into to verify that the file is still being processed. The customer can use this with a monitoring process to help identify files that may be hung. Since this function will be called more frequently than other callbacks, it is implemented as a separate function.
Use of the Status Callback Function
An application's status callback function will be called periodically by Oracle Outside In to provide a status message. Currently, the only status message defined is OIT_STATUS_WORKING, which provides a "sign of life" that can be used during unusually long processing operations to verify that Oracle Outside In has not stopped working. If the application decides that it would not like to continue processing the current document, it may use the return value from this function to tell Oracle Outside In to abort.
The status callback function has two return values defined:
OIT_STATUS_CONTINUE: Tells Oracle Outside In to continue processing the current document.
OIT_STATUS_ABORT: Tells Oracle Outside In to stop processing the current document.
The following is an example of a minimal status callback function.
VTDWORD MyStatusCallback( VTHANDLE hUnique, VTDWORD dwID, VTSYSVAL
pCallbackData, VTSYSVAL pAppData)
{
if(dwID == OIT_STATUS_WORKING)
{
if( checkNeedToAbort( pAppData ) )
return (OIT_STATUS_ABORT);
}
return (OIT_STATUS_CONTINUE);
}
Prototype
DWORD VWSetStatCallback(VWSTATCALLBACKFN pCallback, VTHANDLE hUnique, VTSYSVAL pAppData)
Parameters
pCallback: Pointer to a the callback function.
hUnique: Handle to the view window.
pAppData: User-defined data. Oracle Outside In will never use this value other than to provide it to the callback function.
The callback function should be of type VWSTATCALLBACKFN. This function has the following signature:
(VTHANDLE hUnique, VTDWORD dwID, VTSYSVAL pCallbackData, VTSYSVAL pAppData)
hUnique: Handle for an hExport.
dwID: Currently only OIT_STATUS_WORKING
pCallbackData; Currently will always be NULL
pAppData; User-defined data provided to VWSetStatCallback
Return Values
SCCERR_OK: If successful. Otherwise, one of the error values in sccerr.h is returned.
|
 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|