2-19-91
The Whitewater Group

                     ***************
                     Notes for Actor
                     ***************

This file contains changes to the documentation and
additional information since the Actor manual went to press.
It also contains enhancements made to Actor in recent 
versions.  The latest version of this file is always
available on The Whitewater Group Bulletin Board System 
(BBS).

New Actor Product Configurations
--------------------------------

Beginning with version 3.1, Actor is available in either of
two product options:  Actor Professional and Actor.

* Actor Professional contains all the features documented in
  the User's Manual and in this file.  In addition, Actor
  Professional includes two products that were previously
  available only as add-on options:  ObjectGraphics, a rich
  Actor class library for building graphics applications, 
  and the Whitewater Resource Toolkit, a comprehensive tool 
  for creating and editing program resources, such as dialog 
  boxes, menus and icons.  Actor Professional best meets the 
  needs of the professional programmer who intends to 
  deliver a stand-alone application to an end-user.

* Actor contains all the features documented in the User's 
  Manual and in this file, with one exception: it does not 
  allow you to seal off an application for delivery to end-
  users.  Actor best meets the needs of the beginning Actor 
  developer who is evaluating, learning, designing or 
  prototyping with Actor, but who is unsure if he or she 
  intends to deliver applications to end-users.

If you purchased Actor and you want to upgrade to Actor 
Professional, contact your software dealer or The Whitewater
Group.

Notes on Installation and Configuration
---------------------------------------

1. Switching out of static swapping mode.

This information further describes setting up Actor in
swapping or non-swapping mode, as introduced in Section 2.4,
p. 14 of the Actor User's Manual.

In order to turn off static swapping mode, the manual
instructs you to raise the static setting of your image to
160K (from a default of 60K), either in the Snapshot As
dialog or the WIN.INI file.  (Static swapping lets you run--
or develop--a large program in a small amount of memory,
with a slight degradation in performance for reading and
writing code to disk.)  Static swapping is probably not
necessary when running under protected mode in Windows 3.0
and later versions.

However, to turn static swapping off completely, you must
also send the system message, staticSwapOff();.  This can be
typed interactively in the Actor Workspace.  Make sure that
you have already raised your static setting to 160K or more.
Once you take a snapshot, your image will be saved in non-
swapping mode.  To turn swapping back on, type
staticSwapOn(); in the Workspace, and then you can lower the
static memory setting.

2. Maximum memory settings.

The highest value you can set for static memory is 1023K.
The highest value for dynamic memory is 959K.  Protected
mode is required for settings this high.

3. Disk space.

It is important that you keep enough disk space free while
developing in Actor.  If you don't have enough, you will not
be able to take a snapshot of your image.  In this case, you
will have to free some disk space and rebuild your image.
If you are in static-swapping mode, keep at least 3M free.
In non-static-swapping mode, keep at least 1M free.


Known Bugs
----------

1. Text output in a sealed off application.

If your sealed off application uses print, printLine or
printNewLine to print text to the set of windows listed in
the OutPorts global variable, you'll have to initialize
Outports in the init method of your application class.

The last section of Page 547 of the Actor User's Manual 
presents a generic init method as a guide for your 
application class's init method.  Instead use this init 
method:

  Def init(self, commandStr)
  { OutPorts := new(Set, 4);
    init(self:ancestor, commandStr);
    mainWindow := newMain(UserWindow, menuName, caption, 
      nil);
    show(mainWindow, CmdShow);
  }

If your application does not add any windows to the OutPorts
set, you may set OutPorts to nil in the application class's
init method.

2. Using File:checkError in a sealed off application.  

If your program explicitly invokes File:checkError, Actor's
error-checking mechanism requires access to the Constants
dictionary.  However, this dictionary is normally removed as
part of the sealing off process, since constants are
intended for use only during compilation.  To prevent
Constants from being removed, change the removeCompiler
class method of class Application by deleting the mention of
the variable name Constants.

If you prefer not to modify ApplicationClass:removeCompiler
directly, copy it to your own application class and modify 
the copy.

3. Accelerators and child windows.

If the parent window of a control object, such as an edit 
control or list box, is itself a child window, accelerators 
(keyboard shortcuts) will not properly work for the control.  
In fact, typing the accelerator when the control has the 
input focus results in a fatal error.  In addition, any key 
that is supposed to work in the control, such as an arrow 
key in an edit control, but is defined as an accelerator 
will not work.

To avoid these problems, make a descendant class of the
control class you want to use and define this method 
in the descendant class:

  Def translateMsg(self, lpMsg)
  { Call TranslateMessage(lpMsg);
    Call DispatchMessage(lpMsg);
    ^0;
  }

As defined the method causes all accelerators typed in the
control to be ignored.

4. Limitations of interrupt support.

Only the following interrupts are supported by the 
Struct:intCall method:  3, 21H, 5CH, and 67H.  (In decimal 
they are 3, 33, 92, and 103.)  To use an interrupt other 
than the four supported, you must write a user-defined 
primitive.  The file INT21.ASM (in the RES directory) is a 
template for this purpose.

5. Using accelerator and cursor keys while a debug window is 
open.

If you bring up a Browser or other tool while a Debugger is 
open, accelerator and cursor keys will not work.  You should 
close the Debugger before opening other windows.

6. Defining radio buttons in a dynamic dialog.

A radio button should not be the first control added to a 
dynamic dialog.  If necessary, change the order of the 
creation of controls.

7. Using accelerator and cursor keys in an Edit control 
object.

Accelerators and cursor keys will not work automatically in 
an Edit control object as stated in the manual.  To trap 
accelerators and cursor keys in an Edit control object you 
must include code in the command method of the parent window 
of the control.  The wp parameter of the command method will 
give the virtual key code of the accelerator.  Note that 
accelerators and cursor keys in edit controls work fine in 
dialog boxes.

Alternatively, if you need to create a window which contains 
an editing area, you should use the EditWindow class 
instead, since this class is easier to use and handles 
accelerators and cursor keys automatically.  You can use the 
newChild method to create the EditWindow as a child window
inside a larger window.

An example of how to use the EditWindow class is included in 
the sample application TestWindow.  To load this application 
load the file TESTWIND.LOD.  You can load and create a new 
TestWindow by typing the following in the Actor Workspace:

  load("testwind.lod");
  load();
  TW:=defaultNew(TestWindow, "Test");
  show(TW,1);


Changes to the User's Manual
----------------------------

Please make the following corrections to your Actor User's 
Manual.  (Some of these mistakes were corrected in 
subsequent printings, so you may not find them in your 
copy.)

1. On page 18, in the third bullet item, WIN2DIB.EXE
should be replaced with CONVBMP.EXE.  See Additional
Features below.

2. Figure 18-1 on Page 406 shows the window class tree.  
Three sub-classes are missing from that tree.  The BrowEdit 
class in the tree should have a descendant class DBBrowEdit, 
which further has the descendant DebugEdit.  The FileWindow 
class in the tree should have a descendant class 
PrintFileWindow.  These classes are included in the complete 
class tree, which is located inside the back cover of Volume 
1 of the manual.

3. Contrary to the claim on Page 475, ENTER does NOT cause
an LBN_DBLCLK to be sent to the parent in a command message.

4. The fourth paragraph on Page 494 contains inaccurate
information about the runModal message.  The last two 
sentences in that paragraph should read "The runModal 
message returns the constant value IDCANCEL if the user 
selects the Cancel button; in most cases, IDOK is returned.  
Thus, before checking the value of any fields, you should 
verify that runModal returned IDOK."  Then, the conditional 
line of code at the top of Page 495 should read:

  if runModal(Dialog2, nil, ThePort) = IDOK then

5. In Windows 2.0, Actor could be configured to catch a non-
maskable interrupt (NMI) by setting NMIBreak=1 in file 
WIN.INI.  Because of changes to Windows 3.0, however, this 
technique no longer works and Section 31.4 on pages 641-642 
is no longer valid.

6. The Low-level Debugger documented in Section 31.5 on 
pages 642-644 was disabled in Actor 3.0.

7. To use the user-defined primitive feature described in
Chapter 35, you must load the file USERPRIM.CLS.  It is only
partially loaded in the Actor image, ACTOR.IMA.

8. Methods for the ListBox class are defined on pages 830-
831.  One method was inadvertently omitted from the list:

  deleteString(self, idx)
    Removes the indexed item from the list box.

9. Several of the Windows functions listed on pages 1097-
1098 are not supported in Actor and should not have been 
listed in the manual.  These are:  lstrcat, lstrcmp, 
lstrcpy, and lstrlen.


New Undocumented Features
-------------------------

1. Database support.

Actor has two new ACT files to facilitate access to two 
databases:  Btrieve and dbVista.  Each of the ACT files--
BTRIEVE.ACT and DBVISTA.ACT--does the following:

* Creates a library as a global variable.

* Sets the library's name to the corresponding database's 
  DLL name.

* Informs the library of the database's function names.  For 
  each function, identifies the byte size of its return 
  value, and also the byte size of each of its parameters.

* Loads the new library into Actor.  The loaded library 
  provides access to the database's function calls.  

Each of the ACT files begins with a comment that provides 
more specific information.

The comments should refer to the "Actor User's Manual" 
instead of the "Actor Language Manual".  There is no "Actor 
Language Manual".

2. The Microsoft resource compiler and update utility.

The Actor User's Manual makes many references to Microsoft's
resource compiler, RC.EXE, and its resource conversion
utility, WIN2DIB.EXE.  Actually, WIN2DIB.EXE has been
replaced with CONVBMP.EXE.  The Windows 3.0 versions of
RC.EXE and CONVBMP.EXE are included with Actor and should
be in your RES directory.

3. Loading sample programs.

Actor includes source code files for complete versions of
the Chart (Chapters 6 and 7) and Account Browser (Chapter 8)
programs.  See the end of Chapters 7 and 8 for instructions
on loading these programs.  You may be interested in seeing
these programs before working through the corresponding
exercises.

To use the sample programs included on disk you must load
the appropriate LOD file and then issue some start up
commands to create a window and start the application.  In
some cases, you will also need to add Windows resources into
ACTOR.EXE in order to run the sample programs in the Actor
environment.  This is described in Chapter 26.

Once you have loaded the Chart code and added the resources,
create a new ChartWindow by typing the following code into
the Actor Workspace:

  CW := defaultNew(ChartWindow, "Chart");
  show(CW, 1);

To seal off the Chart application, you must create a
CHART.EXE file and seal off the ChartApp class from within
the Actor environment.

Once you have loaded the Account Browser code and added the
resources, create an AcctWindow by typing:

  AW := defaultNew(AcctWindow, "Accounts");
  show(AW, 1);

To seal off, create an ACCTWIND.EXE file and seal off the
AcctApp class.

4. Using Actor for MDI applications.

Section 17.5 of the Actor User's Manual mentions the new
Windows feature, Multiple Document Interface (MDI).  Actor
includes an example program that is an MDI version of the
Actor File Editor.  To load it, type the following in the
Actor Workspace:

  load("MDI.LOD:);
  load();
  F1 := new(FileApp);
  init(F1, nil);

5. Modifying the high-level message loop.

This is an advanced topic.

Actor includes an optional "high-level" Windows/Actor
message loop.  The regular message loop was previously
hidden in the Actor kernel (EXE), where it worked very
efficiently.  However, it was not modifiable.  The high-
level loop is implemented in the method
Application:messageLoop.  As shipped, Actor uses the high-
level loop.  When sealing off an application, you must
specify that you want to use the high-level loop.  Otherwise
it will use the low-level loop in the kernel.  You should
use the high-level loop if your application:

* Creates modeless dialogs that use a private window class.

* Uses MDI accelerators (requires modification of the loop).

* Needs to customize the loop for any reason.

To use the high-level loop in your sealed-off application,
make sure your application class's init method sends
messageLoop(self); and returns the value returned from this
message.  See the ActorApp.init method for an example.

6. New default window procedures.

This is an advanced topic.

Windows 3.0 introduces three new default window procedures
besides the standard one, DefWindowProc.  Default window
procedures are called when the application does not process
various Windows messages (by defining WM methods).  The new
procedures are DefDlgProc, DefFrameProc and DefMDIChildProc.
Under some circumstances, it is appropriate to call one of
these three.  When processing regular dialogs, no procedure
should be called.

Actor handles the default window procedures properly.  If a
window needs to do something other than call DefWindowProc,
the window's class should define a defWndProc method to
respond appropriately.  For example, Dialog:defWndProc
simply returns zero.  The MDI class (loaded in the sample
program in item 4, above) defines an alternative
defWndProc.  As a default, Actor will call DefWindowProc,
as it always has.

Notes for Users Upgrading from Versions 3.0 or Earlier
------------------------------------------------------

1. This version of Actor includes changed copies of 
ACTOR.EXE and ACTOR.IMA.  This means that IMA files from 
earlier versions of Actor will NOT work.  These IMA
files must be rebuilt by using the current ACTOR.IMA
and loading your class files (CLS files).

2. File \ACT\TESTLIB.ZOO has a new makefile, TESTLIB, which
is now the command file for MAKE.EXE.  Generally, TESTLIB
uses the new Windows C run-time libraries and the new import 
library LIBW.LIB.  Specifically:

* LINK4.EXE is no longer used.  The segmented-executable 
  linker from C 5.1 or 6.0 is used instead.

* The library SWINLIBC.LIB has been replaced by SDLLCAW.LIB.

* The model-dependent libraries SLIBW.LIB, MLIBW.LIB, 
  CLIBW.LIB, and LLIBW.LIB have all been replaced by the 
  model-independent library LIBW.LIB.  File LIBW.LIB runs 
  with any program, including dynamic link libraries (DLLs).

3. The following methods were modified in version 3.01 to 
fix known fatal bugs:  File:read, String:find, and 
Struct:byteAt.

4. Also fixed is a fatal bug which caused dialog objects 
occasionally to have nil handle instance variables.

5. Three Windows function names were incorrect in Actor 3.0.
These function names are now correct.  The incorrect name 
GetRGNBox has been corrected to GetRgnBox; GlobalDOSAlloc 
has been corrected to GlobalDosAlloc; and GlobalDOSFree has 
been corrected to GlobalDosFree.  The manual is correct.

6. The parameters required for the Windows functions
GetKeyboardState and SetKeyboardState were incorrect in
version 3.0.  The manual is correct.

7. The following new methods and primitives were added to 
Actor:

ComboBox:deleteString(self, idx)
  Removes the indexed item from the listbox.

ComboBox:WM_COMMAND(self, wp, lp)
  Executes the default window proc for WM_COMMAND messages.

DlgItem:newAutoRadio(self, txt, ret, offset, extent, sty)
  Creates a new auto-style radio button.

EditWindow:WM_KEYDOWN(self, wp, lp)
  Allows arrow keys and the TAB key to work without using
  accelerators.

File:readByte(self):Byte
  Reads a byte from the current file position and returns
  that byte as an Int.  Might generate these errors: 5, 6.

File:readLong(self):Long
  Reads a Long (4 bytes) from the current file position and
  returns it.  Might generate these errors: 5, 6.

File:readWord(self):Word
  Reads a word (2 bytes) from the current file position and
  returns that word as an Int or Long (if necessary).  Might
  generate these errors: 5, 6.

File:writeByte(self, byte):Byte
  Writes the specified byte to the receiver file (Char, Int,
  or Long objects are acceptable).  Might generate these
  errors:  -1, 5, 6.

File:writeLong(self, aLong):Long
  Writes the specified Long (4 bytes) to the receiver file
  (Char, Int, or Long objects are acceptable).  Might
  generate these errors: -1, 5, 6.

File:writeWord(self, word):Word
  Writes the specified word (2 bytes) to the receiver file
  (Char, Int, or Long objects are acceptable).  Might
  generate these errors: -1, 5, 6.

Long:floatAsReal(self):Real
  Returns a Real number which is the single precision
  floating point data in self converted to double precision.

Long:inPortB(self):Long
  Returns as a Long the byte at the input port specified by 
  the least significant word of self.  The most significant
  word of self is ignored when determining the port address.

Long:outPortB(self, word):Long
  Outputs the byte supplied as an argument to the port
  specified by the least significant word of self.  The
  most significant word of self is ignored when determining
  the port address.  The least significant byte of the
  argument is used.

Real:asFloat(self):Long
  The receiver is converted to single precision.  The single
  precision number result is 4 bytes long and is returned
  in a Long.

Rect:corner(self)
  Returns the lower-right corner of self as a Point.

Struct:ccall(self, arg1_argN):return_value
  Sends a procedure call to a Windows dynamic link library
  with arg1...argN as arguments.  The receiver must be a 
  Proc object.  The dynamic link library procedure must use 
  C calling conventions.  Thus, ccall is similar to 
  Struct:pcall, except that it uses the C calling 
  conventions instead of the Pascal conventions.

8. The File:bRead method returns the number of bytes read 
into a buffer from a file, and the File:bWrite method 
returns the number of bytes written into a buffer from a 
file.  If the buffer is a Long, the actual buffer is 
considered to be the memory at that address instead of a 
destination buffer.

9. Dynamic menus now support separators.  To add a 
separator to a menu, pass nil as the argument in an 
addItem message.

10. The TextFile:readLine method has been corrected to 
properly handle delimiters broken across a file buffer 
boundary.

11. Negative step intervals were fixed so they now work.

12. Actor no longer uses EMS memory internally.  The EMS=
option in the WIN.INI file is no longer supported.  This
was last documented in Actor 2.0.

13. Arrow key and TAB accelerators were removed from
ACTOR.RC.  These accelerators are now defined in the
EditWindow:WM_KEYDOWN method, making them available to 
your application.

14. Actor now supports callback functions with no arguments.


Notes for Users Upgrading from Versions 2.01 or Earlier
-------------------------------------------------------

1. Running Actor 2.0 code unmodified

To run your Actor 2.0 code under a current Actor image, load
the file COMPAT.ACT before loading your code.  This file
accommodates the code invalidated by changes in Actor,
including changes to the CStruct class, the name change of
NilClass to NilObject and the replacement of the
setImageName method for setName.

2. Updating FileDialog resources in sealed off applications

The FILE_BOX resource used by the FileDialog class was
modified in Actor 3.0 to use the new Windows 3.0 ComboBox 
control.  Any resource script based on earlier versions of 
USERAPP.RC will have the old resource for the FILE_BOX that 
does not contain a ComboBox control.  If you seal off an 
application and create the EXE file using the old resource 
definition, the FileDialog will come up but some fields will 
be empty and it will not work properly.  To correct the 
problem, update the FILE_BOX resource in your resource 
script file by copying the new definition from the current 
version of USERAPP.RC and deleting the old one.  Then use 
the resource compiler to compile the resource and it should 
work fine.


Notes for Users of Other Whitewater Products
--------------------------------------------

1. Compatibility with Language Extensions I.

Make sure you have version 2.0 or later of this set of 
additional Actor features now included with every Actor 
product.  Upgrades are available from The Whitewater Group.

2. Compatibility with WinTrieve.

Make sure you have version 3.0 or later of this Windows
indexed file manager.  It works with the current Actor and
version 3.0 of Windows.  It also works with Microsoft C.
Upgrades to WinTrieve are available from The Whitewater 
Group.


*****
Thank you for purchasing Actor.

The Whitewater Group
