1tk::mac(n) Tk Built-In Commands tk::mac(n)
2______________________________________________________________________________
6
8 tk::mac - Access Mac-Specific Functionality on OS X from Tk
9
11 ::tk::mac::DoScriptFile
12 ::tk::mac::DoScriptText
13 ::tk::mac::ShowPreferences
14 ::tk::mac::OpenApplication
15 ::tk::mac::ReopenApplication
16 ::tk::mac::OpenDocument file...
17 ::tk::mac::PrintDocument file...
18 ::tk::mac::Quit
19 ::tk::mac::OnHide
20 ::tk::mac::OnShow
21 ::tk::mac::ShowHelp
22 ::tk::mac::PerformService
23 ::tk::mac::LaunchURL URL...
24 ::tk::mac::GetAppPath
25 ::tk::mac::standardAboutPanel
27 ::tk::mac::useCompatibilityMetrics boolean
29 ::tk::mac::CGAntialiasLimit limit
30 ::tk::mac::antialiasedtext number
31 ::tk::mac::useThemedToplevel boolean
32 ::tk::mac::iconBitmap name width height -kind value
35______________________________________________________________________________
36
38 The Aqua/Mac OS X application environment defines a number of addi‐
39 tional events that applications should respond to. These events are
40 mapped by Tk to calls to commands in the ::tk::mac namespace; unless
41 otherwise noted, if the command is absent, no action will be taken.
42 ::tk::mac::DoScriptFile
44 The default Apple Event handler for AEDoScriptHandler. This com‐
45 mand executes a Tcl file when an AppleScript sends a “do script”
46 command to Wish with a file path as a parameter.
47 ::tk::mac::DoScriptText
49 The default Apple Event handler for AEDoScriptHandler. This com‐
50 mand executes Tcl code when an AppleScript sends a “do script”
51 command to Wish with Tcl code or a Tcl procedure as a parameter.
52 ::tk::mac::ShowPreferences
54 The default Apple Event handler for kAEShowPreferences, “pref”.
55 The application menu “Preferences” menu item is only enabled
56 when this proc is defined. Typically this command is used to
57 wrap a specific own preferences command, which pops up a prefer‐
58 ences window. Something like:
59 proc ::tk::mac::ShowPreferences {} {
61 setPref
62 }
63 ::tk::mac::OpenApplication
65 If a proc of this name is defined, this proc fill fire when your
66 application is initially opened. It is the default Apple Event
67 handler for kAEOpenApplication, “oapp”.
68 ::tk::mac::ReopenApplication
70 If a proc of this name is defined it is the default Apple Event
71 handler for kAEReopenApplication, “rapp”, the Apple Event sent
72 when your application is opened when it is already running (e.g.
73 by clicking its icon in the Dock). Here is a sample that raises
74 a minimized window when the Dock icon is clicked:
75 proc ::tk::mac::ReopenApplication {} {
77 if {[wm state .] eq "withdrawn"} {
78 wm state . normal
79 } else {
80 wm deiconify .
81 }
82 raise .
83 }
84 ::tk::mac::OpenDocument file...
86 If a proc of this name is defined it is the default Apple Event
87 handler for kAEOpenDocuments, “odoc”, the Apple Event sent when
88 your application is asked to open one or more documents (e.g.,
89 by drag & drop onto the app or by opening a document of a type
90 associated to the app). The proc should take as arguments paths
91 to the files to be opened, like so:
92 proc ::tk::mac::OpenDocument {args} {
94 foreach f $args {my_open_document $f}
95 }
96 ::tk::mac::PrintDocument file...
98 If a proc of this name is defined it is the default Apple Event
99 handler for kAEPrintDocuments, “pdoc”, the Apple Event sent when
100 your application is asked to print a document. It takes a sin‐
101 gle absolute file path as an argument.
102 ::tk::mac::Quit
104 If a proc of this name is defined it is the default Apple Event
105 handler for kAEQuitApplication, “quit”, the Apple Event sent
106 when your application is asked to be quit, e.g. via the quit
107 menu item in the application menu, the quit menu item in the
108 Dock menu, or during a logout/restart/shutdown etc. If this is
109 not defined, exit is called instead.
110 ::tk::mac::OnHide
112 If defined, this is called when your application receives a
113 kEventAppHidden event, e.g. via the hide menu item in the appli‐
114 cation or Dock menus.
115 ::tk::mac::OnShow
117 If defined, this is called when your application receives a
118 kEventAppShown event, e.g. via the show all menu item in the ap‐
119 plication menu, or by clicking the Dock icon of a hidden appli‐
120 cation.
121 ::tk::mac::ShowHelp
123 Customizes behavior of Apple Help menu; if this procedure is not
124 defined, the platform-specific standard Help menu item “YourApp
125 Help” performs the default Cocoa action of showing the Help Book
126 configured in the application's Info.plist (or displaying an
127 alert if no Help Book is set).
128 ::tk::mac::PerformService
130 Executes a Tcl procedure called from the macOS “Services” menu
131 in the Application menu item. The “Services” menu item allows
132 for inter-application communication; data from one application,
133 such as selected text, can be sent to another application for
134 processing, for example to Safari as a search item for Google,
135 or to TextEdit to be appended to a file. An example of the proc
136 is below, and should be rewritten in an application script for
137 customization:
138 proc ::tk::mac::PerformService {} {
140 set data [clipboard get]
141 $w insert end $data
142 }
143 Note that the mechanism for retrieving the data is from the clipboard;
144 there is no other supported way to obtain the data. If the Services
145 process is not desired, the NSServices keys can be deleted from the ap‐
146 plication's Info.plist file. The underlying code supporting this com‐
147 mand also allows the text, entry and ttk::entry widgets to access ser‐
148 vices from other applications via the Services menu. The NSPortName key
149 in Wish's Info.plist file is currently set as “Wish” ; if a developer
150 changes the name of the Wish executable to something
151 else, this key should be modified with the same name.
152 ::tk::mac::LaunchURL URL...
154 If defined, launches a URL within Tk. This would be used if a Tk
155 application wants to handle a URL itself, such as displaying
156 data from an RSS feed, rather than launching a default applica‐
157 tion to handle the URL, although it can defined as such. Wish
158 includes a stub URL scheme of “foo://” in the CFBundleURLSchemes
159 key of its Info.plist file; this should be customized for the
160 specific URL scheme the developer wants to support.
161 ::tk::mac::GetAppPath
163 Returns the current applications's file path.
164 ADDITIONAL DIALOGS
169 The Aqua/Mac OS X defines additional dialogs that applications should
171 support.
172 ::tk::mac::standardAboutPanel
174 Brings the standard Cocoa about panel to the front with informa‐
175 tion filled in from the application bundle files. The panel dis‐
176 plays the application icon and the values associated to the
177 info.plist keys named CFBundleName, CFBundleShortVersionString,
178 NSAboutPanelOptionVersion and NSHumanReadableCopyright. If a
179 file named Credits.html or Credits.rtf exists in the bundle's
180 Resources directory then its contents will be displayed in a
181 scrolling text box at the bottom of the dialog. See the documen‐
182 tation for -[NSApplication orderFrontStandardAboutPanelWithOp‐
183 tions:] for more details. A hook is also provided for a custom
184 About dialog. If a Tcl proc named tkAboutDialog is defined in
185 the main interpreter then that procedure will be called instead
186 of opening the standardAboutPanel.
187
189 There are a number of additional global configuration options that con‐
190 trol the details of how Tk renders by default.
191 ::tk::mac::useCompatibilityMetrics boolean
193 Preserves compatibility with older Tk/Aqua metrics; set to false
194 for more native spacing.
195 ::tk::mac::CGAntialiasLimit limit
197 Sets the antialiasing limit; lines thinner that limit pixels
198 will not be antialiased. Integer, set to 0 by default, making
199 all lines be antialiased.
200 ::tk::mac::antialiasedtext number
202 Sets anti-aliased text. Controls text antialiasing, possible
203 values for number are -1 (default, use system default for text
204 AA), 0 (no text AA), 1 (use text AA).
205 ::tk::mac::useThemedToplevel boolean
207 Sets toplevel windows to draw with the modern grayish/ pinstripe
208 Mac background. Equivalent to configuring the toplevel with
209 “-background systemWindowHeaderBackground”, or to using a
210 ttk::frame.
211
213 ::tk::mac::iconBitmap name width height -kind value
214 Renders native icons and bitmaps in Tk applications (including
215 any image file readable by NSImage). A native bitmap name is in‐
216 terpreted as follows (in order):
217 • predefined builtin 32x32 icon name (stop, caution, document,
219 etc.)
220 • name, as defined by tk::mac::iconBitmap
222 • NSImage named image name
224 • NSImage url string
226 • 4-char OSType of IconServices icon
228 The width and height arguments to tk::mac::iconBitmap define the
230 dimensions of the image to create, and -kind must be one of:
231 -file icon of file at given path
233 -fileType
235 icon of given file type
236 -osType
238 icon of given 4-char OSType file type
239 -systemType
241 icon for given IconServices 4-char OSType
242 -namedImage
244 named NSImage for given name
245 -imageFile
247 image at given path
248
250 bind(n), wm(n)
251
253 about dialog, antialiasing, Apple event, icon, NSImage
254Tk 8.6 tk::mac(n)