Initial revision

1 files changed, 299 insertions, 0 deletions

diff --git a/mac/README b/mac/README
new file mode 100644
index 0000000..3c8824a
--- /dev/null
+++ b/mac/README
@@ -0,0 +1,299 @@
+Tk 8.0 for Macintosh
+
+by Ray Johnson
+Sun Microsystems Laboratories
+rjohnson@eng.sun.com
+
+SCCS: @(#) README 1.30 97/11/20 22:06:57
+
+1. Introduction
+---------------
+
+This is the README file for the Macintosh version of the Tk
+extension for the Tcl scripting language.  The file consists of
+information specific to the Macintosh version of Tcl and Tk.  For more
+general information please read the README file in the main Tk
+directory.
+
+2. What's new?
+-------------
+
+Native Look & Feel!!!  We now try really hard to support the 
+Macintosh Look & Feel with Tcl/Tk 8.0.  We aren't finished but
+it look pretty good.  Let me know what are the most "un-mac like"
+problems and I'll fix them as quickly as I can.
+
+The button, checkbutton, radiobutton, and scrollbar widgets actually
+use the Mac toolbox controls.  This means that they will track the
+look&feel if you use extension that change the appearance of
+applications (like Aaron.)  We also use "system" colors so the default
+backgrounds etc. will also change colors.  We plan to support this
+feature - so let me know if something doesn't work quite right.
+Unfortunantly, we are not able to change the colors of buttons under
+MacOS 8.  We are working on a solution to this.  
+In the meantime, if you really must have colored buttons, turn off the 
+"System-wide platinum appearance" option in the Appearance Control Panel,
+and you will get the System 7, colorable, buttons back.
+
+We also now support native menus!  By using the new -menu option
+on toplevels you can have a menubar that is cross platform.  You
+can also place Tk menus in the Apple and Help menus!  Check out
+the documentation for more details.  Syd Polk <icepick@eng.sun.com> is
+the author of the new menu code.  Feel free to contact him if you
+have questions or comments about the menu mechanism.
+
+The "tk_messageBox" command on the Macintosh is now much more
+mac-like.  I'll probably still need to adjust this more - but it
+looks a hell of alot better than it did before.
+
+I've also added a command that allows you to get more native window
+styles.  However, we have yet to decide on a cross platform solution
+to the problem of varying window styles.  None the less, I thought
+it would be use full to add the capability in an unsupported means
+to tide you over until a better solution is available.  The command
+is called "unsupported1".  It can be used in the following way:
+
+	toplevel .foo; unsupported1 style .foo zoomDocProc
+
+The above command will create a document window with a zoom box.
+Type "unsupported1 style . ???" to get a list of the supported
+styles.  The command works like "wm overrideredirect" - you must
+make the call before the window is mapped.
+
+As always - report the bugs you find - including asthetic ones
+in the look & feel of widgets.
+
+3. Mac specific features
+------------------------
+
+There are several features or enhancements in Tk that are unique to 
+the Macintosh version of Tk.  Here is a list of those features and
+pointers to where you can find more information about the feature.
+
+* The menu command has special rules for accessing the Macintosh
+  Apple and Help menus.  See the menu.m man page for details.
+
+* If you have the special Tcl function "tkAboutDialog" defined, it
+  will be called instead of displaying the default About Box in the
+  console or other parts of the Wish application.  See below for
+  details.
+
+* In addition to the standard X cursors, the Mac version of Tk will
+  let you use any Mac cursor that is named and installed in your
+  application.  See the GetCursor.3 man page for details.
+
+* The wish application has a couple of hooks to know about the exit,
+  "open document" and "Do Script"  Mac High Level events.  
+  See below for details.
+
+* The command unsupported1 will allow you to set the style of new
+  toplevel windows on the Macintosh.  It is not really supported.
+  See below for details.
+
+* In addition to the standard built-in bitmaps that Tk supports, the
+  Mac version of Tk allows you to use several Mac specific icons.  See
+  the GetBitmap.3 man page for a complete list.
+
+* The send command does not yet work on the Macintosh.  We hope to
+  have it available in Tk 8.1.
+
+* The -use and -container options almost work. The focus bugs that
+  were in Tk8.0 final have been fixed.  But there are still some
+  known bugs that cause some major problems.  Be careful, if you
+  decide to use these features.  (See bugs.doc for details.)
+
+4. The Distribution
+-------------------
+
+Macintosh Tk is distributed in three different forms.  This 
+should make it easier to only download what you need.  The 
+packages are as follows:
+
+mactk8.0.sea.hqx
+
+    This distribution is a "binary" only release.  It contains an
+    installer program that will install a 68k, PowerPC, or Fat
+    version of the "Wish" application.  In addition, in installs
+    the Tcl & Tk libraries in the Extensions folder inside your
+    System Folder.  (No "INIT"'s or Control Pannels are installed.)
+
+mactcltk-full-8.0.sea.hqx
+
+    This release contains the full release of Tcl and Tk for the
+    Macintosh plus the More Files package on which Macintosh Tcl and
+    Tk rely.
+
+mactk-source-8.0.sea.hqx
+
+    This release contains the complete source to Tk for the Macintosh
+    In addition, Metrowerks CodeWarrior libraries and project files
+    are included.  However, you must already have the More Files
+    package to compile this code.
+
+5. Documentation
+----------------
+
+Two books are currently available for Tcl.  Both provide a good
+introduction to the language.  It is a good way to get started
+if you haven't used the language before:
+
+    Title:			Tcl and the Tk Toolkit
+    Author:			John K. Ousterhout
+    Publisher:			Addison-Wesley
+    ISBN:			0-201-63337-X
+
+    Title:			Practical Programming in Tcl and Tk
+    Author:			Brent Welch
+    Publisher:			Prentice Hall
+    ISBN:			0-13-182007-9
+
+The "doc" subdirectory contains reference in documentation
+in the "man" format found on most UNIX machines.  Unfortunately,
+there is not a suitable way to view these pages on the Macintosh.  
+A version suitable for viewing on the Macintosh has yet to be
+developed.  We are working are having better documentation for
+the Macintosh platform in the future.  However, if you have WWW 
+access you may access the Man pages at the following URL:
+
+	http://sunscript.sun.com/man/tcl8.0/contents.html
+
+Other documentation and sample Tcl scripts can be found at
+the Tcl ftp site: 
+
+	ftp://ftp.neosoft.com/tcl/
+
+The internet news group comp.lang.tcl is also a valuable
+source of information about Tcl.  A mailing list is also
+available (see below).
+
+6. Compiling Tk
+---------------
+
+In order to compile Macintosh Tk you must have the 
+following items:
+
+	CodeWarrior Pro 1 or higher (CodeWarrior release 9 or higher can work
+		and we have project files, but we are depricating support)
+	Mac Tcl 8.0 (source)
+	  (which requires More Files 1.4.2 or 1.4.3)
+	Mac Tk 8.0 (source)
+
+The project  files included with the Mac Tcl source should work 
+fine.  The only thing you may need to update are the access paths.
+As with Tcl, there is something in the initial release of the CW Pro 2
+linker that rendersthe CFM68K version of Wish very unstable.  I am
+working with Metrowerks to resolve the issue.
+
+Special notes:
+
+* Check out the file bugs.doc for information about known bugs.
+
+* We are starting to support the new Appearance Manager that shipped
+  with MacOS 8.  At this point, the only feature that we are using is 
+  the API to Iconify windows (so that wm iconify will work).   However,
+  as of the release of Tk8.0p1, the SDK from Apple is still in Beta, so 
+  we cannot ship it.  So support for the Appearance Manager is turned off
+  in the source version of Tk8.0p1.
+  If you want to build Tk, and want to get the Appearance Manager features, 
+  then need to do the following:
+      1) get the SDK from Apple
+      2) Uncomment the #define HAVE_APPEARANCE line in tk8.0:mac:MW_TkHeader.pch
+      3) Add the Appearance.lib to tk8.0:mac:TkShells.¼, and put the include 
+         directory of the SDK on your path in this project, and TkLibraries.¼.
+
+7. About Dialog
+---------------
+
+There is now a way to replace the default dialog box for the Wish
+application.  If you create the tcl procedure "tkAboutDialog" it will
+be called instead of creating the default dialog box.  Your procedure
+is then responsible for displaying a window, removing it, etc.  This
+interface is experimental and may change in the future - tell me what
+you think of it.
+
+8. Apple Events
+---------------
+
+Tcl/Tk currently doesn't have much in the way of support for Mac
+Apple Events.  There is no way to send an apple event (although you
+could write an extension to do this) and no general purpose way to
+recieve apple events.  However, there are a couple of hooks for
+dealing with some of the standard apple events.
+
+    exit - Generally, Tcl cleans up after it self when you exit.
+	However, your application may want to do application specifc
+	cleanup like saving a users data.  To do this you can rename
+	the exit command to something else.  Define your own exit
+	command to do whatever clean up you like and then call the
+	origional exit command.  For example,
+
+		rename exit __exit
+		proc exit {} {
+		  # Do your clean up hear
+		  __exit
+		}
+
+	Both incoming quit events and hitting the Quit menu item
+	will call the exit command.  However, don't expect you can
+	abort the exit.  Tk may exit anyway if the exit command it
+	calls does not actually quit the application.
+
+    open - The other apple event Tk supports is the open event.  The
+	open event is sent to Tk if, for example, you drop a file on
+	the Wish icon.  If you define a Tcl procedure with the name
+	"tkOpenDocument" it will be invoked on any Open Document
+	events that the application receives.  The a list of paths to
+	the various documents will be passed to the Tcl function.
+	Here is an example,
+
+		proc tkOpenDocument args {
+		  foreach file $args {
+		    # Deal with passed in file path
+		  }
+		}
+
+	Note: This isn't every thing you need to do to make your
+	application dropable.  You must still define a FREF resource
+	that makes sense for your application domain.  (Out of the
+	box, you will not be able to drop files on the Wish
+	application.  See the Inside Macintosh documentation for
+	details about the FREF resource.
+	
+    do script - This is a way for external applications to drive MacTk, or
+        to recieve information from it.  From AppleScript, you can say:
+        
+                tell application "Wish8.0"
+	            do script "console hide
+	                pack [button .b1 -text {Hello world} -command exit]"
+                end tell
+                
+        which will get Tk to run the canonical hello world application.
+                
+8. unsupported1
+---------------
+
+The unsupported1 command is a short term hack we made available to
+allow you to set the window style of a new toplevel window.  It works 
+much like the "wm overrideredirect" and "wm transient" commands in
+that it must be run before the window it's being applied to is mapped.
+
+The syntax of the command is as follows:
+
+	unsupported1 style <window> ?style?
+
+The <window> must be a toplevel window.  If the style is not given
+then the current style for the window is returned.  If you want to set
+the style you must do so before the window gets mapped for the first
+time.  The possible window styles include:
+
+	documentProc, dBoxProc, plainDBox, altDBoxProc,
+	movableDBoxProc, zoomDocProc, rDocProc, floatProc,
+	floatZoomProc, floatSideProc, or floatSideZoomProc
+
+NOTE: this is an unsupported command and it WILL go away in the
+future.
+
+
+If you have comments or Bug reports send them to:
+Jim Ingham
+jingham@eng.sun.com