Lotus 1-2-3 ADK - 123SAMPL.TXT

This file includes information about:
 - how to compile and run the samples.
 - the structure of the samples.

================================================================================
About the samples

The samples that come with the 1-2-3 ADK are designed to introduce many of the features of the 1-2-3 ADK and the LSX interface provided by 1-2-3.  There are a number of small samples, each demonstrating a particular feature or group of features and a main application, 123HTML, which is designed to show how these features can be brought together to create useful extensions to 1-2-3 functionality.

To compile the samples, simply move to the correct directory and type do_it.  If this doesn't work then consult the file install.txt for further information about how to install and set up the 1-2-3 ADK and the LSX Toolkit.

Each sample comes with a .123 file which is designed to demonstrate this LSX.  These are provided in 1-2-3 '97 format to provide backward compatibility with that version.

================================================================================
123HTML

This sample demonstrates a number of different features of the 123 ADK.  It takes a range of cells that you specify and reads or writes it to disk as an HTML file which you can also, via the LSX, open in your default browser.

The 123HTML LSX implements a single LotusScript Class - C123HTML.  The C123HTML 1-2-3 Worksheet has a custom menu ("HTML") for changing the properties of a single C123HTML Object.

The C123HTML Class demonstrates passing data to and from LotusScript, Event Handling, file I/O, integration with the Win SDK.  It also shows how to transfer cell data between the LSX and 1-2-3 using  the 1-2-3 specific LotusScript GetCellData, SetCellData and FreeCellData functions. These functions allow fast external access to cell data by transferring data directly via 'C' Arrays.

The C123HTML Class has the following methods, properties and events:

Properties:
   Filename:      (Read/Write) The html filename of this object
   Borders:       (Read/Write) Specifies if the generated html table has borders
   ColorTitle:    (Read/Write) Color of the generated html title text.
   ColorBGround:  (Read/Write) Color of the generated html background.
   ColorContents: (Read/Write) Color of the generated html cell data.

   Rows:          (Read Only)  The number of rows in a loaded HTML file
   Cols:          (Read Only)  The number of Columns in a loaded HTML file

Methods:
   New(String) as C123HTML
      Creates a new C123HTML object. The filename of any exported HTML can be
      set when instantiating the new object.

   StartBrowser() as integer
      Loads an exported file into the users' default browser starting the
      browser if necessary.

   DumpHTML(arrayPtr as long) as integer
      Writes the contents of the array pointed to by 'long' out to the file
      named in the FileName Property of the object.
      The long pointer is acquired using the LotusScript GetCellData function.

   LoadHTML(filename as String) as long
      Loads in and translates a C123HTML generated html table in file - returns
      a pointer for use in the 1-2-3 SetCellData Sub.

   FreeHTML(arrayPtr as long) as integer
      Frees the memory allocated to an array by LoadHTML - Must be used when the
      data returned by LoadHTML is no longer required.

   ColorDialog() as string
      Brings up a windows common color dialog box. Returns a hex format RGB
      value (RRGGBB) corresponding to the color the user chose in the dialog.
      Returns the string "NULL" if the user cancelled the dialog.

   HTMLSettingsDialog()
      Brings up a customized windows color dialog with added controls for
      setting all the color and border properties.
      Properties are set within the LSX itself so no input from LotusScript is
      required.
      This method also raises a 'BorderPropChanged" Event to allow LotusScript
      to update the Borders menu item check mark.
 
================================================================================
InfoWin

This sample demonstrates how to get to the 123 window in the Win32 platform.  Having found the window it creates a text window within it and allows the user to add text to this window through LotusScript as well as by typing into the window.

It implements a single class, InfoWinSession, with two methods and a constructor.

methods:
   New() as InfoWinSession
      Creates a InfoWinSession.
      This constructor registers the window class for InfoWins with Windows and
      finds the main 1-2-3 window which it stored in a global variable.

   Open(string)
      This method opens an InfoWin and gives it the specified window title.

   Print(string, string)
      This method finds an open InfoWin with the title contained in the first
      parameter.  If it exists then it prints the second parameter to this
      window, followed by a carriage return.  If the window doesn't exist, then
      the method brings up a windows message box (not a LotusScript one) to say
      so.

================================================================================
PreClose

This example demonstrates some of the event handling features of the 123 ADK.  It intercepts the window close message passed to the parent window when a 123 document window is closed and raises a LotusScript event when this happens.  The class structure allows the programmer to start this event trap and to stop it afterwards.

It implements a single class, CloseWatcher, which has two methods, a constructor and an event.

methods:
   New() as CloseWatcher
      This constructor simply returns an object.  No processing is done.

   Start()
      This starts the event trap by subclassing the MDIClient window of the
      current 1-2-3 instance.  This is the window that is the parent of all of
      the document windows.  When a window is closed the MDIClient is sent a
      message to say so.  The window procedure implemented in the file
      window.cpp intercepts this message and raises the LotusScript event with
      the window title (which is the filename of the document that was closed).

   Stop()
      This method removes the subclassing and stops trapping the close events.

events:
   WinClosed(CloseWatcher, string)
      This event is raised when the class detects that a window has been closed.  
      The parameter passed is the window title of the window that was closed.

================================================================================
EditBox

This sample shows how you can use the dll wizard and resource wizard in Visual Studio to add external resources quickly to your 123 LSXs.  It uses the MFC to make the development process even faster.  The sample allows the user to change the contents of a cell (the included 123 file changes the current cell) using an MFC dialog box.

The main source code for the LSX portion is in the \lsx\src\lsxmfc directory and the source for the MFC portion is in the \lsx\src\lsxmfc\mfclsx directory.  They can be developed separately and interfaced through certain files which makes it significantly easier to re-use MFC or LSX code that you've developed elsewhere.

The sample implements one class, EditBox, with one method and a constructor.

methods:
   New() as EditBox
      This constructor simply initializes the LSX portion of the DLL - the MFC
      looks after itself.

   CellEdit(range)
      This method takes a range object and then, using a MFC created dialog
      class, brings up a dialog box containing the contents of the top left-cell
      of the range.  If the user clicks OK, the contents of this cell are set to
      be the contents of the dialog box at that time.
      This method gets and sets the values of the cell using the ObjSetProp and
      ObjGetProp methods of the LSX123Base class.

An important feature to note about using the dynamically linked MFC with your LSX is that the macro AFX_MANAGE_STATE must be included before any calls to the MFC in your code (including constructors).  Not calling this macro can make your program unstable.

================================================================================
Colors

This sample demonstrates the different ways that you can get to the LotusScript classes in your 123 LSX.  It uses the MFC to implement the standard color dialog for Win32 and allows the user to change the background color of a 123 range.  It changes the background color in three different ways.  The first is to change the color by passing the method a long (representing the rgb value of the current color) and the method returns a long representing the user's choice so that the color can be changed in LotusScript.  The second method takes a 123 LotusScript Range object and changes the background color by drilling down through the object structure of the 123 object.  This means that the color is changed by the LSX directly and the change appears in 123 before the LSX has finished running.  The third method also takes a Range object but changes the current color using the 123 flat properties described in CMDID.TXT.  These properties are more closely related to the way that information is stored internally by 123 and this means that the access, which takes less steps, is a lot quicker.

This LSX also uses the MFC but with source code only (i.e. without the ClassWizard).  To create a similar LSX using the MFC, include the file MFC.H in the same places (.cpp files and .h files) and add the MFCAPP.* files to the build (these files initialize the MFC).  Also look at the make files for this sample - there are two flags set to specify the library that the code links with.  This should be enough to let the sample compile from the command line using do_it.  To create a MFC project in Visual Studio (one is provided): first create a MFC DLL using the Wizard; then add the LSX files to the project; make sure that the project is setup to use the DLL dynamically linked and to prevent the warning from the redefinition of the _AFXDLL definition add VCLSX to the list of defines in the project settings.

The LSX implements one class, ColorBox, which has three methods and one constructor.

methods:
   New() as ColorBox
     This is a default constructor which simply creates and registers an object.

   EditByObj(range)
      This method takes the range and gets/sets the background color via the
      LotusScript object structure.

   EditByTrait(range)
      This method changes the background color via a flat property as described
      in the file cmdid.txt.

   EditByVal(long) as long
      This method takes a long in the form 0x00rrggbb and returns another long
      in the same format.  These longs represent the before and after colors of
      the cell backgrounds.  The changes to the cell properties are performed
      through LotusScript.  This is the method used in the main application
      sample.
