Thread: [TCLCORE] Merging TkAqua Cocoa port into Tk HEAD

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Hi All,

as you may know, I have been working on a port of TkAqua to the Cocoa
API for some time, with the goal to get TkAqua to run on 64bit, and to
move away from Mac OS X Carbon API that has been deprecated.

The Cocoa port has now been feature complete for about a month and I
believe is of equal or better quality than the existing TkAqua
implementation, it has been built, tested and is already being used
successfully by various parties, and IMO is now ready to be merged
into the Tk mainline.

The port is available as patches against HEAD (large!)
	http://www.categorifiedcoder.info/tcltk/patches/tk-de-carbon.diff.bz2
	http://www.categorifiedcoder.info/tcltk/patches/tcl-de-carbon.diff.bz2
or from github with full history:
	http://github.com/das/tcltk/commits/de-carbon

The patch to Tcl only touches the macosx README and the Xcode
projects, related generally applicable changes to Tcl (in particular
the revised macosx notifier) have already gone in a few weeks ago for
8.5.7.

The principal new constraint of the TkAqua Cocoa port is that it
requires Mac OS X 10.5 or later (TkAqua currently requires Mac OS X
10.3).

After discussion with Jeff and other TkAqua maintainers and
distributors, we have decided that the Tk 8.6 release is a reasonable
moment to drop support for pre-10.5 OS X, as users who still need to
run on earlier OS versions should be able to remain with 8.5 for some
time.

There is a 8.5 backport of TkAqua Cocoa, which I will continue to
maintain as a fork at github (to avoid a system requirements jump in a
8.5 point release):
	http://github.com/das/tcltk/commits/de-carbon-8-5

There should be no script-visible changes to standard Tk functionality
introduced by the Cocoa port; there are some additions of
TkAqua-specific functionality (c.f. excerpt from tk/macosx/README
below) and a few removals of obsolete unsupported Carbon-specific bits
in the tk::mac namespace.
Various longstanding missing features have been implemented (e.g. [wm
aspect]) and a number of bugs tightly tied to the old implementation
are fixed by the rewrite. Drawing performance is also significantly
improved (e.g. >2x speedup of a benchmark that draws many short lines
on a canvas).

At the public Tk C API level, there is a tiny signature change to
macosx-specific API in the public plat stubs table (replacing two
Carbon pointer types that should never have entered a public x-plat
header by void*).
Otherwise, public API is unchanged and extensions that use only public
Tk API are unaffected and should continue to work unchanged (verified
with extensions like TkImg and TkTable).
Thus I believe there is no requirement for a TIP for the integration
of the Cocoa port changes.

There are also no additions/removals to the private plat stubs table,
but a significant number of signature changes (mostly turning more
Carbon pointer types into void*).
However, many of the macosx private stubs API calls had unfortunately
exposed details of the internal Carbon implementation that could not
be preserved, such calls had to be neutered and are now just NOPs. Tk
extensions that rely on these or make other assumptions about TkAqua
internals (like the presence of QuickDraw and QD ports) will have to
be ported to support TkAqua Cocoa (e.g. Treectrl and Tile are known to
be affected).

I am planning to move forward with the merge tonight (CEST), so if you
have objections, please speak up soon!

Cheers,

Daniel

-- 
** Daniel A. Steffen                   **
** <mailto:da...@us...>  **

==== From tk/macosx/README ====

- The default metrics of native buttons, radiobuttons, checkboxes and
menubuttons in the Cocoa-based Tk 8.6b2 and later preserve
compatibility with the older Carbon-based implementation, you can turn
off the compatibility metrics to get more native-looking spacing by
setting:
	set tk::mac::useCompatibilityMetrics 0

- TkAqua provides access to native OS X images via the Tk native
bitmap facility (including any image file readable by NSImage). A
native bitmap name is interpreted as follows (in order):
    - predefined builtin 32x32 Tk icon name (stop, caution, document, etc)
    - name defined by [tk::mac::iconBitmap]
    - NSImage named image name
    - NSImage url string
    - 4-char OSType of IconServices icon
the syntax of [tk::mac::iconBitmap] is as follows:
	tk::mac::iconBitmap name width height -kind value
where -kind is one of
    -file	    icon of file at given path
    -fileType	    icon of given file type
    -osType	    icon of given 4-char OSType file type
    -systemType	    icon for given IconServices 4-char OSType
    -namedImage	    named NSImage for given name
    -imageFile	    image at given path
This support was added with the Cocoa-based Tk 8.6b2.

- TkAqua cursor names are interpred as follows (in order):
    - standard or platform-specific Tk cursor name (c.f. cursors.n)
    - @path to any image file readable by NSImage
    - NSImage named image name
Support for the latter two was added with the Cocoa-based Tk 8.6b2.

- The standard Tk dialog commands [tk_getOpenFile],
[tk_chooseDirectory], [tk_getSaveFile] and [tk_messageBox] all take an
additional optional -command parameter on TkAqua. If it is present,
the given command prefix is evaluated at the global level when the
dialog closes, with the dialog command's result appended (the dialog
command itself returning an emtpy result). If the -parent option is
also present, the dialog is configured as a modeless (window-modal)
sheet attached to the parent window and the dialog command returns
immediately.
Support for -command was added with the Cocoa-based Tk 8.6b2.

- The TkAqua-specific [tk::mac::standardAboutPanel] command brings the
standard Cocoa about panel to the front, with all its information
filled in from your application bundle files (i.e. standard about
panel with no options specified). See Apple Technote TN2179 and the
AppKit documentation for -[NSApplication
orderFrontStandardAboutPanelWithOptions:] for details on the
Info.plist keys and app bundle files used by the about panel.
This support was added with the Cocoa-based Tk 8.6b2.

- TkAqua has three special menu names that give access to the standard
Application, Window and Help menus, see menu.n for details.
Support for the Window menu was added with the Cocoa-based Tk 8.6b2.

- The TkAqua-specific command [tk::unsupported::MacWindowStyle style]
is used to get and set Mac OS X-specific toplevel window class and
attributes. Note that the window class and many attributes have to be
set before the window is first mapped for the change to have any
effect.
The command has the following syntax:
	tk::unsupported::MacWindowStyle style window ?class? ?attributes?
The 2 argument form returns a list of the current class and attributes
for the given window. The 3 argument form sets the class for the given
window using the default attributes for that class. The 4 argument
form sets the class and the list of attributes for the given window.
Window class names:
    document, modal, floating, utility, toolbar, simple, help, overlay
Window attribute names:
    standardDocument, standardFloating, resizable, fullZoom, horizontalZoom,
    verticalZoom, closeBox, collapseBox, toolbarButton, sideTitlebar,
    noTitleBar, unifiedTitleAndToolbar, metal, hud, noShadow, doesNotCycle,
    noActivates, hideOnSuspend, inWindowMenu, ignoreClicks, doesNotHide,
    canJoinAllSpaces, moveToActiveSpace, nonActivating
Note that not all attributes are valid for all window classes.
Support for the 3 argument form was added with the Cocoa-based Tk
8.6b2, at the same time support for some legacy Carbon-specific
classes and attributes was removed (they are still accepted by the
command but no longer have any effect).

- The Cocoa-based TkAqua can be distinguished from the older
Carbon-based version via the [winfo server .] command, example output
on Mac OS X 10.5.7:
    Cocoa-based:	CG409.3 Apple AppKit GC 949.46 Mac OS X 1057
    Carbon-based:	QD10R30 Apple 1057

Thread: [TCLCORE] Merging TkAqua Cocoa port into Tk HEAD

The Tool Command Language implementation

tcl-core