Rehabilitate Document Preview !

Since framesets have been available to Domino designers, that is from release 5 onwards, Notes applications attempted to escape from the traditional 3-panes user interface that long-time proposed a left navigation pane, a right-top view pane and a right-bottom document preview. As developers discovered the flexibility offered by framesets, few Notes applications have exhibited original interfaces, many applications have retained a traditional 3-frames arrangement while others even presented a somewhat limited 2-frames disposition.

As framesets have become prevalent while building Notes applications user interfaces or entry points, this post proposes to rehabilitate document preview in applications that rely on framesets.

3 different dispositions keep accompanying Notes classical 3-panes default presentation. You obtain them selecting View - Document Preview - Arrange Preview... context menu as illustrated in figure 1 below. Notice the so-called "Bottom Right" usual layout you're familiar with. While choosing a location end-users are provided three different interfaces. Unfortunately, nowadays frameset built applications rarely offer such a flexible and powerful user-oriented design.

Figure 1: View - Document Preview - Arrange Preview... dialog window.

While I do not mean developers should systematically propose multiple variations in pane arrangements, bringing particular attention and care while building user interfaces is common wisdom in designers community. Observe end-users are offered another option, past document preview activation. Using View - Document Preview - Zoom Preview context menu, documents can be maximised or set back to preview mode. If you feel like emulating document preview and zoom in framesets, please read on!

Despite this long introduction, enabling document preview in framesets is easy, although not really documented. Suffice to name a frame "NotesPreview" and you're done! Truth is framesets secretly resort to "NotesPreview" hardcoded name to implement document preview. Say your application uses a 2-frame arrangement, as shown in figure 2, and you intend to zoom documents using a 3-frame arrangement as in figure 3. Split the right frame in 2 rows, name its bottom empty frame "NotesPreview", set its height to 0 and make sure the upper frame links target "NotesPreview" lower frame. Save your frameset and observe View - Document Preview context menu now contains two new options: Show Preview and Zoom Preview.

I have systematically implemented document preview whenever I could and I've retained my addiction to document preview/zoom combined with the usage of framesets. Don't frustrate your experienced Notes users and start "NotesPreview"ing to their benefit !

Figure 2: 2-Frame arrangement i.e. Right-Left

Figure 3: 3-Frame arrangement so-called "Bottom Right"

Figure 4: Naming a frame "NotesPreview" suffices to implement show preview or zoom preview for documents.

Opening Control Panel applets in modal dialog boxes - Windows/32 only

Executing Windows/32 Control Panel applets from LotusScript is easy. Suffice to code a Shell statement appending the applet name to the control program and the job is done. The following code sample opens up "Display Properties" and "Tweak UI" control panel dialogs.

Dim TaskID As Integer
taskID% = Shell( "control desk.cpl" ) ' Let's open up "Display Properties" window ..
taskID% = Shell( "tweakui.cpl" ) ' .. then "Tweak UI" dialog box afterwards.

Applets shelled this way run independently from Notes applications whereas the ability to execute applets in Notes threads is tied to your client operating system. Nir Sofer's site [1] details how Visual Basic programmers can display Control Panel applets within modal dialog boxes. Nir achieves this performing Windows API calls and using VarPtr() Visual Basic only statement. While VarPtr() is not supported in LotusScript, designers with appropriate Windows/32 C API experience, can implement equivalent functionality. Thus Nir's Visual Basic code ..

Private Declare Function CPlApplet_Main Lib "main.cpl" Alias "CPlApplet" _
( ByVal hwndCPl As Long, ByVal uMsg As Long, ByVal lParam1 As Long,  _
ByVal lParam2 As Long ) As Long
Private Sub MainCplApplet( lParam1 As Long )
If CPlApplet_Main( hWnd, CPL_INIT, 0, 0 ) <> 0 Then
    CPlApplet_Main hWnd, CPL_INQUIRE, lParam1, VarPtr( ci )
    CPlApplet_Main hWnd, CPL_DBLCLK, lParam1, ci.lData
    CPlApplet_Main hWnd, CPL_STOP, 0, ci.lData
    CPlApplet_Main hWnd, CPL_EXIT, 0, 0
End If

.. can be translated into LotusScript as:

Declare Private Function Applet Lib "main.cpl" Alias "CPlApplet" _
( Byval hwndCPl As Long, Byval uMsg As Long, Byval lParam1 As Long,  _
Byval lParam2 As Long ) As Long
Declare Private Function AppletVarPtr Lib "main.cpl" Alias "CPlApplet" _
( Byval hwndCPl As Long, Byval uMsg As Long, Byval lParam1 As Long, _
lParam2 As CPLINFO ) As Long ' NOTE the last argument modification HERE !
If Applet( hwnd, CPL_INIT, 0, 0 ) <> 0 Then
    ' Visual Basic VarPtr() statement does not exist in LotusScript ...
    AppletVarPtr hwnd, CPL_INQUIRE, lParam1, ci
    ' ...  AppletVarPtr declare is emulating VarPtr(ci) statement
    CPlApplet_Main hWnd, CPL_DBLCLK, lParam1, ci.lData
    CPlApplet_Main hWnd, CPL_STOP, 0, ci.lData
    CPlApplet_Main hWnd, CPL_EXIT, 0, 0
End If

Note AppletVarPtr() above function in Windows C API second declare statement, its last argument is defined as a CPLINFO structure. It is sent by reference instead of being sent by value which emulates VarPtr() Visual Basic statement. All control panel applets can be called this way. I decided not to code numerous declares, but used an APPLET_CODE_TEMPLATE string where AppletName and lParam1 arguments are dynamically substituted. This way applets are loaded and executed at runtime as in:

Private Sub AppletLoader( Byval appletName As String, Byval parm1 As String )
    toList( 0 ) = appletName
    toList( 1 ) = parm1
    ' Domino Release 6 ONLY
    Execute Replace( APPLET_TEMPLATE_CODE, fromList, toList )
End Sub

I wrapped up a few applets' calls in a ControlPanel class bundled in OpenDOM open source project that you can download from OpenNTF.org site. You can use it as shown below:

Use "LotusScript.windows.win32"
Dim ui As New ControlPanel
ui.AccessibilityOptions
ui.DisplayProperties
ui.MultimediaProperties
ui.AppletLoader "tweakui", "0"

I hope you'll find ControlPanel class useful and shall be glad to hear about any interesting usage you experiment with it or about any extensions you make to it.

Credit: [1] Executing Control Panel applets