Tk Source Code

2012-03-13  Donal K. Fellows  <[email protected]>

	* doc/*.3, doc/*.n: Minor spelling fixes.

2012-03-07  Donal K. Fellows  <[email protected]>

	* generic/tkObj.c (GetPixelsFromObjEx): [Bug 3497848]: Better rounding
	of pixel values to integers.

2012-03-04  Jan Nijtmans  <[email protected]>

between \fBTk_ClipboardClear\fR and the following
\fBTk_ClipboardAppend\fR calls (otherwise someone could retrieve
a partially completed clipboard or claim ownership away from
this application).
.PP
\fBTk_ClipboardClear\fR may invoke callbacks, including arbitrary
Tcl scripts, as a result of losing the CLIPBOARD selection, so
any calling function should take care to be re-entrant at the point
\fBTk_ClipboardClear\fR is invoked.
.SH KEYWORDS
append, clipboard, clear, format, type

The only difference is that new X window for a top-level window
will not be a child of \fIparent\fR's X window.  For example, a pull-down
menu's \fIparent\fR would be the button-like window used to invoke it,
which would in turn be a child of the menu bar window.  A dialog box might
have the application's main window as its parent.
.PP
\fBTk_CreateAnonymousWindow\fR differs from \fBTk_CreateWindow\fR in
that it creates an unnamed window.  This window will be manipulatable
only using C interfaces, and will not be visible to Tcl scripts.  Both
interior windows and top-level windows may be created with
\fBTk_CreateAnonymousWindow\fR.
.PP
\fBTk_CreateWindowFromPath\fR offers an alternate way of specifying
new windows.  In \fBTk_CreateWindowFromPath\fR the new
window is specified with a token for any window in the target

as \fIversion\fR.
.BE
.SH INTRODUCTION
.PP
The Tcl stubs mechanism defines a way to dynamically bind
extensions to a particular Tcl implementation at run time.
the stubs mechanism requires no changes to applications
incorporating Tcl/Tk interpreters.  Only developers creating
C-based Tcl/Tk extensions need to take steps to use the
stubs mechanism with their extensions.
See the \fBTcl_InitStubs\fR page for more information.
.PP
Enabling the stubs mechanism for a Tcl/Tk extension requires the following
steps:
.IP 1) 5

and pointer events from Tk widgets, while overriding the widget's cursor with
a configurable busy cursor.
.SH INTRODUCTION
.PP
There are many times in applications where you want to temporarily restrict
what actions the user can take. For example, an application could have a
.QW Run
button that when pressed causes some processing to occur. However, while the
application is busy processing, you probably don't want the user to be
able to click the
.QW Run
button again. You may also want restrict the user from other tasks such as
clicking a
.QW Print
button.
.PP
The \fBtk busy\fR command lets you make Tk widgets busy. This means that user
interactions such as button clicks, moving the mouse, typing at the keyboard,
etc.\0are ignored by the widget. You can set a special cursor (like a watch)
that overrides the widget's normal cursor, providing feedback that the
application (widget) is temporarily busy.
.PP
When a widget is made busy, the widget and all of its descendants will ignore
events. It's easy to make an entire panel of widgets busy. You can simply make
the toplevel widget (such as
.QW . )
busy. This is easier and far much more efficient than recursively traversing
the widget hierarchy, disabling each widget and re-configuring its cursor.
.PP
Often, the \fBtk busy\fR command can be used instead of Tk's \fBgrab\fR

Tk toolkit loaded, and control over this interpreter is given through
the \fBconsole\fR command.  The behaviour of the console window is
defined mainly through the contents of the \fIconsole.tcl\fR file in
the Tk library. Except for TkAqua, this command is not available when
Tk is loaded into a tclsh interpreter with
.QW "\fBpackage require Tk\fR" ,
as a conventional terminal is expected to be present in that case.
In TkAqua, this command is only available when stdin is \fB/dev/null\fR
(as is the case e.g. when the application embedding Tk is started
from the Mac OS X Finder).
.PP
.TP
\fBconsole eval \fIscript\fR
Evaluate the \fIscript\fR argument as a Tcl script in the console
interpreter.  The normal interpreter is accessed through the

is a list of all the virtual events that are currently defined.
If \fB<<\fIvirtual\fB>>\fR is specified then the return value is
a list whose elements are the physical event sequences currently
defined for the given virtual event;  if the virtual event is
not defined then an empty string is returned.
.RS
.PP
Note that virtual events that are not bound to physical event
sequences are \fInot\fR returned by \fBevent info\fR.
.RE
.SH "EVENT FIELDS"
.PP
The following options are supported for the \fBevent generate\fR
command.  These correspond to the
.QW %

first argument.  The following forms are currently supported:
.TP
\fBfont actual \fIfont\fR ?\fB\-displayof \fIwindow\fR? ?\fIoption\fR? ?\fB\-\|\-\fR? ?\fIchar\fR?
.
Returns information about the actual attributes that are obtained when
\fIfont\fR is used on \fIwindow\fR's display; the actual attributes obtained
may differ from the attributes requested due to platform-dependent
limitations, such as the availability of font families and point sizes.
\fIfont\fR is a font description; see \fBFONT DESCRIPTIONS\fR below.  If the
\fIwindow\fR argument is omitted, it defaults to the main window.  If
\fIoption\fR is specified, returns the value of that attribute; if it is
omitted, the return value is a list of all the attributes and their values.
See \fBFONT OPTIONS\fR below for a list of the possible attributes.  If the
\fIchar\fR argument is supplied, it must be a single character. The font
attributes returned will be those of the specific font used to render

selection dialog, care needs to be taken to correctly handle focus changes: the
font selected in the dialog should always match the current font of the widget
with the focus, and the \fB\-command\fR callback should only act on the widget
with the focus. The recommended practice is to set font dialog \fB\-font\fR and
\fB\-command\fR configuration options in per\-widget \fB<FocusIn>\fR handlers
(and if necessary to unset them \- i.e. set to the empty string \- in
corresponding \fB<FocusOut>\fR handlers). This is particularly important for
implementers of library code using the font selection dialog, to avoid
conflicting with application code that may also want to use the dialog.
.PP
Because the font selection dialog is application-global, in the presence of
multiple interpreters calling \fBtk fontchooser\fR, only the \fB\-command\fR
callback set by the interpreter that most recently called \fBtk fontchooser\fR
\fBconfigure\fR or \fBtk fontchooser\fR \fBshow\fR will be invoked in response
to user action and only the \fB\-parent\fR set by that interpreter will receive

\fIbitmap\fR has not been specified, or if it is specified as an empty string,
then a solid fill will be used for the background.
.TP
\fB\-borderwidth \fIpixels\fR
.
\fIPixels\fR specifies the width of a border to draw around the tag using any
of the forms accepted by \fBTk_GetPixels\fR. This option should be used in
conjunction with the \fB\-relief\fR option to provide the desired border.
.TP
\fB\-elide \fIboolean\fR
.
\fIElide\fR specifies whether the data should be elided. Elided data
(characters, images, embedded windows, etc.) is not displayed and takes no
space on screen, but further on behaves just as normal data.
.TP

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

.AP Ttk_Box parcel in
A rectangular region, allocated from a cavity.
.AP int relief in
One of the standard Tk relief options 
(TK_RELIEF_RAISED, TK_RELIEF_SUNKEN, etc.).  
See \fBTk_GetReliefFromObj\fR.
.AP short right in
Extra padding (in pixels) to add to the right side of a region.
.AP Ttk_Side side in
One of \fBTTK_SIDE_LEFT\fR, \fBTTK_SIDE_TOP\fR, 
\fBTTK_SIDE_RIGHT\fR, or \fBTTK_SIDE_BOTTOM\fR.
.AP unsigned sticky in
A bitmask containing one or more of the bits
\fBTTK_STICK_W\fR (west, or left), 
\fBTTK_STICK_E\fR (east, or right, 

    int \fIy\fR;
    int \fIwidth\fR;
    int \fIheight\fR;
} \fBTtk_Box\fR;
.CE
All coordinates are relative to the window.
.PP
\fBTtk_MakeBox\fR is a convenience routine that constructs
a \fBTtk_Box\fR structure representing a region \fIwidth\fR pixels
wide, \fIheight\fR pixels tall, at the specified \fIx, y\fR coordinates.
.PP
\fBTtk_PadBox\fR returns a new box located inside the specified \fIparcel\fR,
shrunken according to the left, top, right, and bottom margins
specified by \fIpadding\fR.
.PP

    short \fIleft\fR;
    short \fItop\fR;
    short \fIright\fR;
    short \fIbottom\fR;
} \fBTtk_Padding\fR;
.CE
.PP
\fBTtk_MakePadding\fR is a convenience routine that constructs
a \fBTtk_Padding\fR structure with the specified left, top, right, and bottom
components.
.PP
\fBTtk_UniformPadding\fR constructs a \fBTtk_Padding\fR structure
with all components equal to the specified \fIborder\fR.
.PP
\fBTtk_AddPadding\fR adds two \fBTtk_Padding\fRs together

.SH SYNOPSIS
\fBttk::style element create \fIname\fR \fBvsapi\fR \fIclassName\fR \fIpartId\fR ?\fIstateMap\fR? ?\fIoptions\fR?
.BE
.SH DESCRIPTION
.PP
The \fBvsapi\fR element factory creates a new element
in the current theme whose visual appearance is drawn using the
Microsoft Visual Styles API which is responsible for the themed styles
on Windows XP and Vista. This factory permits any of the Visual
Styles parts to be declared as Ttk elements that can then be
included in a style layout to modify the appearance of Ttk widgets.
.PP
\fIclassName\fR and \fIpartId\fR are required parameters and specify
the Visual Styles class and part as given in the Microsoft
documentation. The \fIstateMap\fR may be provided to map Ttk states to

\fB\-height \fIheight\fR
.
Specifies the height of the element. See the comments for \fB\-width\fR.
.SH "STATE MAP"
.PP
The \fIstateMap\fR parameter is a list of ttk states and the
corresponding Visual Styles API state value.
This permits the element appearance to respond to changes in the
widget state such as becoming active or being pressed. The list should
be as described for the \fBttk::style map\fR command but note that the
last pair in the list should be the default state and is typically and
empty list and 1. Unfortunately all the Visual Styles parts have
different state values and these must be looked up either in the
Microsoft documentation or more likely in the header files. The
original header to use was \fItmschema.h\fR, but in more recent

.CS
ttk::style element create smallclose \fBvsapi\fR WINDOW 19 \\
    {disabled 4 pressed 3 active 2 {} 1}
ttk::style layout CloseButton {CloseButton.smallclose -sticky news}
pack [ttk::button .close -style CloseButton]
.CE
.PP
Change the appearance of a \fBttk::checkbutton\fR(n) to use the
Explorer pin part EBP_HEADERPIN.
.CS
ttk::style element create pin \fBvsapi\fR EXPLORERBAR 3 {
    {pressed !selected} 3
    {active !selected} 2
    {pressed selected} 6
    {active selected} 5

Returns the geometry for \fIwindow\fR, in the form
\fIwidth\fBx\fIheight\fB+\fIx\fB+\fIy\fR.  All dimensions are
in pixels.
.TP
\fBwinfo height \fIwindow\fR
Returns a decimal string giving \fIwindow\fR's height in pixels.
When a window is first created its height will be 1 pixel;  the
height will eventually be changed by a geometry manager to fulfil
the window's needs.
If you need the true height immediately after creating a widget,
invoke \fBupdate\fR to force the geometry manager to arrange it,
or use \fBwinfo reqheight\fR to get the window's requested height
instead of its actual height.
.TP
\fBwinfo id \fIwindow\fR

relative to the root window of its screen.
This is normally either zero or negative.
Returns 0 if there is no virtual root window for \fIwindow\fR.
.TP
\fBwinfo width \fIwindow\fR
Returns a decimal string giving \fIwindow\fR's width in pixels.
When a window is first created its width will be 1 pixel;  the
width will eventually be changed by a geometry manager to fulfil
the window's needs.
If you need the true width immediately after creating a widget,
invoke \fBupdate\fR to force the geometry manager to arrange it,
or use \fBwinfo reqwidth\fR to get the window's requested width
instead of its actual width.
.TP
\fBwinfo x \fIwindow\fR

.
Specifies the path of the file referenced as the window proxy icon (which
can be dragged and dropped in lieu of the file's finder icon).
.TP
\fB\-transparent\fR
.
Makes the window content area transparent and turns off the window shadow. For
the transparency to be effective, the toplevel background needs to be set to a
color with some alpha, e.g.
.QW systemTransparent .
.PP
On X11, the following attributes may be set. These are not supported by all
window managers, and will have no effect under older WMs.
.\" See http://www.freedesktop.org/Standards/wm-spec
.TP
\fB\-type\fR
.VS 8.6
Requests that the window should be interpreted by the window manager as being
of the specified type(s). This may cause the window to be decorated in a
different way or otherwise managed differently, though exactly what happens is
entirely up to the window manager. A list of types may be used, in order of
preference. The following values are mapped to constants defined in the EWMH
specification (using others is possible, but not advised):

.RS
.TP
\fBdesktop\fR
.
indicates a desktop feature,
.TP
\fBdock\fR