* doc/tk_mac.n (new file): Description of OSX-specific functionality

	in Tk, contributed by Kevin Walzer.
	* doc/button.n, doc/font.n, doc/menu.n: Noted which parts of these
	commands are intentionally not fully supported on OSX.

5 files changed, 266 insertions, 0 deletions

diff --git a/ChangeLog b/ChangeLog
index 8448897..8ebb514 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2011-03-02  Donal K. Fellows  <dkf@users.sf.net>
+
+	* doc/tk_mac.n (new file): Description of OSX-specific functionality
+	in Tk, contributed by Kevin Walzer.
+	* doc/button.n, doc/font.n, doc/menu.n: Noted which parts of these
+	commands are intentionally not fully supported on OSX.
+
 2011-01-24  Joe English  <jenglish@users.sourceforge.net>
 
 	* generic/tkSelect.c: Fix for [Bug #3164879] 
diff --git a/doc/button.n b/doc/button.n
index 863773c..0089118 100644
--- a/doc/button.n
+++ b/doc/button.n
@@ -175,6 +175,14 @@ actions occur:  the button is completely non-responsive.
 .PP
 The behavior of buttons can be changed by defining new bindings for
 individual widgets or by redefining the class bindings.
+.SH "PLATFORM NOTES"
+.PP
+On Aqua/Mac OS X, some configuration options are ignored for the purpose of
+drawing of the widget because they would otherwise conflict with platform
+guidelines. The \fBconfigure\fR and \fBcget\fR subcommands can still
+manipulate the values, but do not cause any variation to the look of the
+widget. The options affected notably include \fB\-background\fR and
+\fB\-relief\fR.
 .SH EXAMPLES
 .PP
 This is the classic Tk
diff --git a/doc/font.n b/doc/font.n
index 65adffd..3184767 100644
--- a/doc/font.n
+++ b/doc/font.n
@@ -52,6 +52,14 @@ then the command modifies the given named font to have the given values; in
 this case, all widgets using that font will redisplay themselves using the
 new attributes for the font.  See \fBFONT OPTIONS\fR below for a list of the
 possible attributes.
+.RS
+.PP
+Note that on Aqua/Mac OS X, the system fonts (see
+\fBPLATFORM-SPECIFIC FONTS\fR below) may not be actually altered because they
+are implemented by the system theme. To achieve the effect of modification,
+use \fBfont actual\fR to get their configuration and \fBfont create\fR to
+synthesize a copy of the font which can be modified.
+.RE
 .TP
 \fBfont create\fR ?\fIfontname\fR? ?\fIoption value ...\fR?
 .
diff --git a/doc/menu.n b/doc/menu.n
index 665d4e8..67dd7d4 100644
--- a/doc/menu.n
+++ b/doc/menu.n
@@ -42,6 +42,8 @@ top.  If so, it will exist as entry 0 of the menu and the other
 entries will number starting at 1.  The default
 menu bindings arrange for the menu to be torn off when the tear-off
 entry is invoked.
+This option is ignored under Aqua/Mac OS X, where menus cannot
+be torn off.
 .OP \-tearoffcommand tearOffCommand TearOffCommand
 If this option has a non-empty value, then it specifies a Tcl command
 to invoke whenever the menu is torn off.  The actual command will
@@ -54,6 +56,8 @@ and menu \fB.x.y\fR is torn off to
 create a new menu \fB.x.tearoff1\fR, then the command
 .QW "\fBa b .x.y .x.tearoff1\fR"
 will be invoked.
+This option is ignored under Aqua/Mac OS X, where menus cannot
+be torn off.
 .OP \-title title Title
 The string will be used to title the window created when this menu is
 torn off. If the title is NULL, then the window will have the title
@@ -557,6 +561,8 @@ This option is not available for separator or tear-off entries.
 When this option is zero, the entry appears below the previous entry. When
 this option is one, the entry appears at the top of a new column in the
 menu.
+This option is ignored on Aqua/Mac OS X, where menus are always a single
+column.
 .TP
 \fB\-command \fIvalue\fR
 .
diff --git a/doc/tk_mac.n b/doc/tk_mac.n
new file mode 100644
index 0000000..bf683f8
--- /dev/null
+++ b/doc/tk_mac.n
@@ -0,0 +1,237 @@
+'\"
+'\" Copyright (c) 2011 Kevin Walzer.
+'\" Copyright (c) 2011 Donal K. Fellows.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.so man.macros
+.TH tk::mac n 8.6 Tk "Tk Built-In Commands"
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+tk::mac \- Access Mac-Specific Functionality on OS X from Tk
+.SH SYNOPSIS
+.nf
+\fB::tk::mac::ShowPreferences\fR
+\fB::tk::mac::OpenApplication\fR
+\fB::tk::mac::ReopenApplication\fR
+\fB::tk::mac::OpenDocument \fIfile...\fR
+\fB::tk::mac::PrintDocument \fIfile...\fR
+\fB::tk::mac::Quit\fR
+\fB::tk::mac::OnHide\fR
+\fB::tk::mac::OnShow\fR
+\fB::tk::mac::ShowHelp\fR
+
+\fB::tk::mac::standardAboutPanel\fR
+
+\fB::tk::mac::useCompatibilityMetrics \fIboolean\fR
+\fB::tk::mac::CGAntialiasLimit \fIlimit\fR
+\fB::tk::mac::antialiasedtext \fInumber\fR
+\fB::tk::mac::useThemedToplevel \fIboolean\fR
+
+\fB::tk::mac::iconBitmap \fIname width height \-kind value\fR
+.fi
+.BE
+.SH "EVENT HANDLER CALLBACKS"
+.PP
+The Aqua/Mac OS X application environment defines a number of additional
+events that applications should respond to. These events are mapped by Tk to
+calls to commands in the \fB::tk::mac\fR namespace; unless otherwise noted, if
+the command is absent, no action will be taken.
+.TP
+\fB::tk::mac::ShowPreferences\fR
+.
+The default Apple Event handler for kAEShowPreferences,
+.QW pref .
+The application menu
+.QW "Preferences"
+menu item is only enabled when this proc is defined. Typically this command is
+used to wrap a specific own preferences command, which pops up a preferences
+window. Something like:
+.RS
+.PP
+.CS
+proc ::tk::mac::ShowPreferences {} {
+    setPref
+}
+.CE
+.RE
+.TP
+\fB::tk::mac::OpenApplication\fR
+.
+If a proc of this name is defined, this proc fill fire when your application
+is intially opened. It is the default Apple Event handler for
+kAEOpenApplication,
+.QW oapp .
+.TP
+\fB::tk::mac::ReopenApplication\fR
+.
+If a proc of this name is defined it is the default Apple Event handler for
+kAEReopenApplication,
+.QW rapp ,
+the Apple Event sent when your application is opened when it is already
+running (e.g. by clicking its icon in the Dock). Here is a sample that raises
+a minimized window when the Dock icon is clicked:
+.RS
+.PP
+.CS
+proc ::tk::mac::ReopenApplication {} {
+    if {[wm state .] eq "withdrawn"} {
+        wm state . normal
+    } else {
+        wm deiconify .
+    }
+    raise .
+}
+.CE
+.RE
+.TP
+\fB::tk::mac::OpenDocument \fIfile...\fR
+.
+If a proc of this name is defined it is the default Apple Event handler for
+kAEOpenDocuments,
+.QW odoc ,
+the Apple Event sent when your application is asked to open one or more
+documents (e.g., by drag & drop onto the app or by opening a document of a
+type associated to the app). The proc should take as arguments paths to the
+files to be opened, like so:
+.RS
+.PP
+.CS
+proc ::tk::mac::OpenDocument {args} {
+    foreach f $args {my_open_document $f}
+}
+.CE
+.RE
+.TP
+\fB::tk::mac::PrintDocument \fIfile...\fR
+.
+If a proc of this name is defined it is the default Apple Event handler for
+kAEPrintDocuments,
+.QW pdoc ,
+the Apple Event sent when your application is asked to print one or more
+documents (e.g., via the Print menu item in the Finder).  It works the same
+way as \fBtk::mac::OpenDocument\fR in terms of arguments.
+.TP
+\fB::tk::mac::Quit\fR
+.
+If a proc of this name is defined it is the default Apple Event handler for
+kAEQuitApplication,
+.QW quit ,
+the Apple Event sent when your application is asked to be quit, e.g. via the
+quit menu item in the application menu, the quit menu item in the Dock menu,
+or during a logout/restart/shutdown etc. If this is not defined, \fBexit\fR is
+called instead.
+.TP
+\fB::tk::mac::OnHide\fR
+.
+If defined, this is called when your application receives a kEventAppHidden
+event, e.g. via the hide menu item in the application or Dock menus.
+.TP
+\fB::tk::mac::OnShow\fR
+.
+If defined, this is called when your application receives a kEventAppShown
+event, e.g. via the show all menu item in the application menu, or by clicking
+the Dock icon of a hidden application.
+.TP
+\fB::tk::mac::ShowHelp\fR
+.
+Customizes behavior of Apple Help menu; if this procedure is not defined, the
+platform-specific standard Help menu item
+.QW "YourApp Help"
+performs the default Cocoa action of showing the Help Book configured in the
+application's Info.plist (or displaying an alert if no Help Book is set).
+.SH "ADDITIONAL DIALOGS"
+.PP
+The Aqua/Mac OS X defines additional dialogs that applications should
+support.
+.TP
+\fB::tk::mac::standardAboutPanel\fR
+.
+Brings the standard Cocoa about panel to the front, with all its information
+filled in from your application bundle files (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.
+.SH "SYSTEM CONFIGURATION"
+.PP
+There are a number of additional global configuration options that control the
+details of how Tk renders by default.
+.TP
+\fB::tk::mac::useCompatibilityMetrics \fIboolean\fR
+.
+Preserves compatibility with older Tk/Aqua metrics; set to \fBfalse\fR for
+more native spacing.
+.TP
+\fB::tk::mac::CGAntialiasLimit \fIlimit\fR
+.
+Sets the antialiasing limit; lines thinner that \fIlimit\fR pixels will not be
+antialiased. Integer, set to 0 by default, making all lines be antialiased.
+.TP
+\fB::tk::mac::antialiasedtext \fInumber\fR
+.
+Sets anti-aliased text.  Controls text antialiasing, possible values for
+\fInumber\fR are -1 (default, use system default for text AA), 0 (no text AA),
+1 (use text AA).
+.TP
+\fB::tk::mac::useThemedToplevel \fIboolean\fR
+.
+Sets toplevel windows to draw with the modern grayish/ pinstripe Mac
+background. Equivalent to configuring the toplevel with
+.QW "\fB\-background systemWindowHeaderBackground\fR" ,
+or to using a \fBttk::frame\fR.
+.SH "SUPPORT COMMANDS"
+.TP
+\fB::tk::mac::iconBitmap \fIname width height \-kind value\fR
+.
+Renders native icons and bitmpas in Tk applications (including any image file
+readable by NSImage). A native bitmap name is interpreted as follows (in
+order):
+.RS
+.IP \(bu 3
+predefined builtin 32x32 icon name (\fBstop\fR, \fBcaution\fR, \fBdocument\fR,
+etc.)
+.IP \(bu 3
+\fIname\fR, as defined by \fBtk::mac::iconBitmap\fR
+.IP \(bu 3
+NSImage named image name
+.IP \(bu 3
+NSImage url string
+.IP \(bu 3
+4-char OSType of IconServices icon
+.PP
+The \fIwidth\fR and \fIheight\fR arguments to \fBtk::mac::iconBitmap\fR define
+the dimensions of the image to create, and \fI\-kind\fR must be one of:
+.TP
+\fB\-file\fR
+.
+icon of file at given path
+.TP
+\fB\-fileType\fR
+.
+icon of given file type
+.TP
+\fB\-osType\fR
+.
+icon of given 4-char OSType file type
+.TP
+\fB\-systemType\fR
+.
+icon for given IconServices 4-char OSType
+.TP
+\fB\-namedImage\fR
+.
+named NSImage for given name
+.TP
+\fB\-imageFile\fR
+.
+image at given path
+.RE
+.SH "SEE ALSO"
+bind(n), wm(n)
+.SH KEYWORDS
+about dialog, antialiasing, Apple event, icon, NSImage
+'\" Local Variables:
+'\" mode: nroff
+'\" End: