Add tk-mac doc to 8.5

1 files changed, 237 insertions, 0 deletions

diff --git a/doc/tk_mac.n b/doc/tk_mac.n
new file mode 100644
index 0000000..f29ef2f
--- /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.
+'\" 
+.TH tk::mac n 8.6 Tk "Tk Built-In Commands"
+.so man.macros
+.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 bitmaps 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: