Subversion Repositories or1k

Tk 8.0.4 for Macintosh

by Ray Johnson

Scriptics Corporation

rjohnson@scriptics.com

with major help from

Jim Ingham

Cygnus Solutions

jingham@cygnus.com

RCS: @(#) $Id: README,v 1.1.1.1 2002-01-16 10:25:55 markom Exp $

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.  Doing this is discouraged under Appearance, and we will probably

not implement it anytime soon.

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  is

the author of the new menu code.  Feel free to contact him if you

have questions or comments about the menu mechanism.

As of Tk 8.0.4, MacTk menus will adopt the backgrounds, shape, separator, etc

of the current theme.

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.4.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.4.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.4.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

----------------

There are now many books available for Tcl.  These two 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

More books are listed at

    http://www.scriptics.com/resource/doc/books/

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://www.scriptics.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)

                8.0.4 was build with CW Pro 3.

        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.0.  The Tk 8.0.3 release is the first Tk release

  that supports the Appearance Manager well.  Tk 8.0.4 extends this support

  to the menu system, though you have to have Appearance 1.0.1 or later

  installed for this to work.

* If you get the Unix tar file, it will untar into a directory tcl8.0.4.  However,

  the Macintosh project files expect the folder to be called tcl8.0.  You will need

  to rename the folder to tcl8.0, or change all the paths in the project files.

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  ?style?

The  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@cygnus.com