Tk Source Code

        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl 8.6
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: core-8-branch
          path: tcl
      - name: Setup Environment (compiler=${{ matrix.compiler }})
        run: |
          sudo apt-get install libxss-dev libxft-dev
          mkdir "$HOME/install dir"
          touch tk/doc/man.macros tk/generic/tkStubInit.c
          echo "CFGOPT=$CFGOPT" >> $GITHUB_ENV

        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: core-8-branch
          path: tcl
      - name: Setup Environment (compiler=${{ matrix.compiler }})
        run: |
          sudo apt-get install libxss-dev libxft-dev xvfb libicu-dev
          mkdir "$HOME/install dir"
          touch tk/doc/man.macros tk/generic/tkStubInit.c
          echo "CFGOPT=$CFGOPT" >> $GITHUB_ENV

name: Linux (with Tcl 8.6)
on:
  push:
    branches:
    - "main"
    - "core-8-branch"
    - "core-8-6-branch"
    tags:
    - "core-**"
permissions:
  contents: read
defaults:
  run:
    shell: bash
    working-directory: tk/unix
env:
  ERROR_ON_FAILURES: 1
jobs:
  build:
    runs-on: ubuntu-22.04
    strategy:
      matrix:
        compiler:
          - "gcc"
          - "clang"
        cfgopt:
          - ""
          - "CFLAGS=-DTK_NO_DEPRECATED=1"
          - "--disable-xft"
          - "--disable-xss"
          - "--enable-symbols"
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: core-8-6-branch
          path: tcl
      - name: Setup Environment (compiler=${{ matrix.compiler }})
        run: |
          sudo apt-get install libxss-dev libxft-dev
          mkdir "$HOME/install dir"
          touch tk/doc/man.macros tk/generic/tkStubInit.c
          echo "CFGOPT=$CFGOPT" >> $GITHUB_ENV
          echo "CC=$COMPILER" >> $GITHUB_ENV
          echo "TOOL_DIR=$(cd tcl/tools;pwd)" >> $GITHUB_ENV
          echo "BUILD_CONFIG_ID=$OPTS" >> $GITHUB_ENV
        working-directory: "."
        env:
          CFGOPT: ${{ matrix.cfgopt }}
          COMPILER: ${{ matrix.compiler }}
          OPTS: ${{ matrix.compiler }}${{ matrix.cfgopt }}
      - name: Configure and Build Tcl
        run: |
          ./configure $CFGOPT "--prefix=$HOME/install dir" || {
            cat config.log
            echo "::warning::Failure during Tcl Configure"
            exit 1
          }
          make all install  || {
            echo "::warning::Failure during Tcl Build"
            exit 1
          }
          echo "TCL_CONFIG_PATH=`pwd`" >> $GITHUB_ENV
        working-directory: tcl/unix
      - name: Configure (opts=${{ matrix.cfgopt }})
        run: |
          ./configure $CFGOPT --with-tcl=$TCL_CONFIG_PATH --disable-zipfs "--prefix=$HOME/install dir" || {
            cat config.log
            echo "::error::Failure during Configure"
            exit 1
          }
      - name: Build
        run: |
          make binaries libraries || {
            echo "::error::Failure during Build"
            exit 1
          }
      - name: Build Test Harness
        run: |
          make tktest || {
            echo "::error::Failure during Build"
            exit 1
          }
      - name: Test-Drive Installation
        run: |
          make install || {
            echo "::error::Failure during Install"
            exit 1
          }
      - name: Create Distribution Package
        run: |
          make dist || {
            echo "::error::Failure during Distribute"
            exit 1
          }
      - name: Convert Documentation to HTML
        run: |
          make html-tk TOOL_DIR=$TOOL_DIR || {
            echo "::error::Failure during Distribute"
            exit 1
          }
  test:
    runs-on: ubuntu-22.04
    strategy:
      matrix:
        compiler:
          - "gcc"
        cfgopt:
          - ""
          - "--disable-xft"
          - "--enable-symbols"
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: core-8-6-branch
          path: tcl
      - name: Setup Environment (compiler=${{ matrix.compiler }})
        run: |
          sudo apt-get install libxss-dev libxft-dev xvfb libicu-dev
          mkdir "$HOME/install dir"
          touch tk/doc/man.macros tk/generic/tkStubInit.c
          echo "CFGOPT=$CFGOPT" >> $GITHUB_ENV
          echo "CC=$COMPILER" >> $GITHUB_ENV
        working-directory: "."
        env:
          CFGOPT: ${{ matrix.cfgopt }}
          COMPILER: ${{ matrix.compiler }}
      - name: Configure and Build Tcl
        run: |
          ./configure $CFGOPT "--prefix=$HOME/install dir" || {
            cat config.log
            echo "::warning::Failure during Tcl Configure"
            exit 1
          }
          make all install  || {
            echo "::warning::Failure during Tcl Build"
            exit 1
          }
          echo "TCL_CONFIG_PATH=`pwd`" >> $GITHUB_ENV
        working-directory: tcl/unix
      - name: Configure ${{ matrix.cfgopt }}
        run: |
          ./configure $CFGOPT --with-tcl=$TCL_CONFIG_PATH "--prefix=$HOME/install dir" || {
            cat config.log
            echo "::error::Failure during Configure"
            exit 1
          }
      - name: Build
        run: |
          make binaries libraries tktest || {
            echo "::error::Failure during Build"
            exit 1
          }
      - name: Run Tests
        run: |
          xvfb-run --auto-servernum make test-classic | tee out-classic.txt
          xvfb-run --auto-servernum make test-ttk | tee out-ttk.txt
          grep -q "Failed	0" out-classic.txt || {
            echo "::error::Failure during Test"
            exit 1
          }
          grep -q "Failed	0" out-ttk.txt || {
            echo "::error::Failure during Test"
            exit 1
          }
        timeout-minutes: 15

name: Linux (with Tcl 9.0)
on:
  push:
    branches:
    - "main"
    - "core-8-branch"
    - "core-8-6-branch"
    tags:
    - "core-**"
permissions:
  contents: read
defaults:
  run:
    shell: bash
    working-directory: tk/unix
env:
  ERROR_ON_FAILURES: 1
jobs:
  build:
    runs-on: ubuntu-22.04
    strategy:
      matrix:
        compiler:
          - "gcc"
          - "clang"
        cfgopt:
          - ""
          - "CFLAGS=-DTK_NO_DEPRECATED=1"
          - "--disable-xft"
          - "--disable-xss"
          - "--enable-symbols"
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: main
          path: tcl
      - name: Setup Environment (compiler=${{ matrix.compiler }})
        run: |
          sudo apt-get install libxss-dev libxft-dev
          mkdir "$HOME/install dir"
          touch tk/doc/man.macros tk/generic/tkStubInit.c
          echo "CFGOPT=$CFGOPT" >> $GITHUB_ENV
          echo "CC=$COMPILER" >> $GITHUB_ENV
          echo "TOOL_DIR=$(cd tcl/tools;pwd)" >> $GITHUB_ENV
          echo "BUILD_CONFIG_ID=$OPTS" >> $GITHUB_ENV
        working-directory: "."
        env:
          CFGOPT: ${{ matrix.cfgopt }}
          COMPILER: ${{ matrix.compiler }}
          OPTS: ${{ matrix.compiler }}${{ matrix.cfgopt }}
      - name: Configure and Build Tcl
        run: |
          ./configure $CFGOPT "--prefix=$HOME/install dir" || {
            cat config.log
            echo "::warning::Failure during Tcl Configure"
            exit 1
          }
          make all install  || {
            echo "::warning::Failure during Tcl Build"
            exit 1
          }
          echo "TCL_CONFIG_PATH=`pwd`" >> $GITHUB_ENV
        working-directory: tcl/unix
      - name: Configure (opts=${{ matrix.cfgopt }})
        run: |
          ./configure $CFGOPT --with-tcl=$TCL_CONFIG_PATH "--prefix=$HOME/install dir" || {
            cat config.log
            echo "::error::Failure during Configure"
            exit 1
          }
      - name: Build
        run: |
          make binaries libraries || {
            echo "::error::Failure during Build"
            exit 1
          }
      - name: Build Test Harness
        run: |
          make tktest || {
            echo "::error::Failure during Build"
            exit 1
          }
      - name: Test-Drive Installation
        run: |
          make install || {
            echo "::error::Failure during Install"
            exit 1
          }
      - name: Create Distribution Package
        run: |
          make dist || {
            echo "::error::Failure during Distribute"
            exit 1
          }
      - name: Convert Documentation to HTML
        run: |
          make html-tk TOOL_DIR=$TOOL_DIR || {
            echo "::error::Failure during Distribute"
            exit 1
          }
  test:
    runs-on: ubuntu-22.04
    strategy:
      matrix:
        compiler:
          - "gcc"
        cfgopt:
          - ""
          - "--disable-xft"
          - "--enable-symbols"
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: main
          path: tcl
      - name: Setup Environment (compiler=${{ matrix.compiler }})
        run: |
          sudo apt-get install libxss-dev libxft-dev xvfb libicu-dev
          mkdir "$HOME/install dir"
          touch tk/doc/man.macros tk/generic/tkStubInit.c
          echo "CFGOPT=$CFGOPT" >> $GITHUB_ENV
          echo "CC=$COMPILER" >> $GITHUB_ENV
        working-directory: "."
        env:
          CFGOPT: ${{ matrix.cfgopt }}
          COMPILER: ${{ matrix.compiler }}
      - name: Configure and Build Tcl
        run: |
          ./configure $CFGOPT "--prefix=$HOME/install dir" || {
            cat config.log
            echo "::warning::Failure during Tcl Configure"
            exit 1
          }
          make all install  || {
            echo "::warning::Failure during Tcl Build"
            exit 1
          }
          echo "TCL_CONFIG_PATH=`pwd`" >> $GITHUB_ENV
        working-directory: tcl/unix
      - name: Configure ${{ matrix.cfgopt }}
        run: |
          ./configure $CFGOPT --with-tcl=$TCL_CONFIG_PATH "--prefix=$HOME/install dir" || {
            cat config.log
            echo "::error::Failure during Configure"
            exit 1
          }
      - name: Build
        run: |
          make binaries libraries tktest || {
            echo "::error::Failure during Build"
            exit 1
          }
      - name: Run Tests
        run: |
          xvfb-run --auto-servernum make test-classic | tee out-classic.txt
          xvfb-run --auto-servernum make test-ttk | tee out-ttk.txt
          grep -q "Failed	0" out-classic.txt || {
            echo "::error::Failure during Test"
            exit 1
          }
          grep -q "Failed	0" out-ttk.txt || {
            echo "::error::Failure during Test"
            exit 1
          }
        timeout-minutes: 15

        shell: bash
        working-directory: tk/macosx
    steps:
      - name: Checkout Tk
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: core-8-branch
          path: tcl
      - name: Prepare checked out repositories
        run: |
          touch tk/generic/tkStubInit.c
          mkdir build
          echo "BUILD_DIR=`cd build && pwd`" >> $GITHUB_ENV
          echo "DESTDIR=`cd build && pwd`" >> $GITHUB_ENV

        shell: bash
        working-directory: tk/unix
    steps:
      - name: Checkout Tk
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: core-8-branch
          path: tcl
      - name: Prepare checked out repositories
        env:
          SET_DISPLAY: ${{ contains(matrix.options, '--disable-aqua') }}
        run: |
          touch tkStubInit.c
          mkdir "$HOME/install dir"

      CC: gcc
      CFGOPT: --disable-symbols --disable-shared
    steps:
      - name: Checkout Tk
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl 8.7
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: core-8-branch
          path: tcl
      - name: Setup Environment
        run: |
          sudo apt-get install libxss-dev libxft-dev
          touch tcl/generic/tclStubInit.c tcl/generic/tclOOStubInit.c
          touch tk/generic/tkStubInit.c
          echo "INST_DIR=$(cd install;pwd)" >> $GITHUB_ENV

      - name: Build & Install Tk
        run: |
          make binaries libraries install
        working-directory: tk/unix
        # TODO: need the Tk version separately for distro naming below
      - name: Package
        run: |
          cp bin/wish8.7 ${BUILD_NAME}
          chmod +x ${BUILD_NAME}
          tar -cf ${BUILD_NAME}.tar ${BUILD_NAME}
        working-directory: ${{ env.INST_DIR }}
        env:
          BUILD_NAME: wish${{ env.TCL_PATCHLEVEL }}_snapshot
      - name: Upload
        uses: actions/upload-artifact@v4
        with:
          name: Wish ${{ env.TCL_PATCHLEVEL }} Linux single-file build (snapshot)
          path: ${{ env.INST_DIR }}/*.tar
      - name: Describe Installation Zip Contents
        if: ${{ always() }}
        run: |
          unzip -l wish${{ env.TCL_PATCHLEVEL }}_snapshot || true
        working-directory: ${{ env.INST_DIR }}
  macos:
    name: macOS
    runs-on: macos-13
    defaults:
      run:
        shell: bash
    env:
      CC: gcc
      CFGOPT: --disable-symbols --disable-shared
    steps:
      - name: Checkout Tk
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl 8.7
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: core-8-branch
          path: tcl
      - name: Checkout create-dmg
        uses: actions/checkout@v4
        with:
          repository: create-dmg/create-dmg
          ref: v1.0.8
          path: create-dmg

        with:
          msystem: MINGW64
          install: git mingw-w64-x86_64-toolchain make zip
      - name: Checkout Tk
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl 8.7
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: core-8-branch
          path: tcl
      - name: Setup Environment
        run: |
          mkdir -p install/combined
          touch tcl/generic/tclStubInit.c tcl/generic/tclOOStubInit.c
          touch tk/generic/tkStubInit.c
          echo "INST_DIR=$(cd install;pwd)" >> $GITHUB_ENV

        working-directory: tk/win
    # Using powershell means we need to explicitly stop on failure
    strategy:
      matrix:
        config:
          - ""
          - "OPTS=symbols"
          - "OPTS=symbols STATS=compdbg,memdbg"
          - "OPTS=static"
    steps:
      - name: Checkout Tk
        uses: actions/checkout@v4
        with:
          path: tk
      - name: Checkout Tcl 8.7
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: core-8-branch
          path: tcl
      - name: Init MSVC
        uses: ilammy/msvc-dev-cmd@v1
      - name: Make Install Location
        working-directory: tcl
        run: |
          echo "TCLDIR=`pwd`" >> $GITHUB_ENV

      - name: Install MSYS2
        uses: msys2/setup-msys2@v2
        with:
          msystem: MINGW64
          install: git mingw-w64-x86_64-toolchain make zip
      - name: Checkout Tk
        uses: actions/checkout@v4
      - name: Checkout Tcl 8.7
        uses: actions/checkout@v4
        with:
          repository: tcltk/tcl
          ref: core-8-branch
          path: tcl
      - name: Prepare
        run: |
          touch tkStubInit.c
          touch "${HOME}/forWinDialog-5.12.7"
          mkdir "${HOME}/install_dir"
          echo "INSTALL_DIR=${HOME}/install_dir" >> $GITHUB_ENV

<?xml version="1.0" encoding="UTF-8"?>
<projectDescription>
	<name>tk8.7</name>
	<comment></comment>
	<projects>
	</projects>
	<buildSpec>
	</buildSpec>
	<natures>
	</natures>

# README:  Tk

This is the **Tk 8.7b1** source distribution.

You can get any source release of Tk from [our distribution
site](https://sourceforge.net/projects/tcl/files/Tcl/).

9.0 (production release, daily build)
[![Build Status](https://github.com/tcltk/tk/actions/workflows/linux-build.yml/badge.svg?branch=main)](https://github.com/tcltk/tk/actions/workflows/linux-build.yml?query=branch%3Amain)
[![Build Status](https://github.com/tcltk/tk/actions/workflows/win-build.yml/badge.svg?branch=main)](https://github.com/tcltk/tk/actions/workflows/win-build.yml?query=branch%3Amain)
[![Build Status](https://github.com/tcltk/tk/actions/workflows/mac-build.yml/badge.svg?branch=main)](https://github.com/tcltk/tk/actions/workflows/mac-build.yml?query=branch%3Amain)
<br>
8.7 (in development, daily build)
[![Build Status](https://github.com/tcltk/tk/actions/workflows/linux-build.yml/badge.svg?branch=core-8-branch)](https://github.com/tcltk/tk/actions/workflows/linux-build.yml?query=branch%3Acore-8-branch)
[![Build Status](https://github.com/tcltk/tk/actions/workflows/win-build.yml/badge.svg?branch=core-8-branch)](https://github.com/tcltk/tk/actions/workflows/win-build.yml?query=branch%3Acore-8-branch)
[![Build Status](https://github.com/tcltk/tk/actions/workflows/mac-build.yml/badge.svg?branch=core-8-branch)](https://github.com/tcltk/tk/actions/workflows/mac-build.yml?query=branch%3Acore-8-branch)






## <a id="intro">1.</a> Introduction

This directory contains the sources and documentation for Tk, a
cross-platform GUI toolkit implemented with the Tcl scripting language.

For details on features, incompatibilities, and potential problems with
this release, see [the Tcl/Tk 8.7 Web page](https://www.tcl-lang.org/software/tcltk/8.7.html)
or refer to the "changes" file in this directory, which contains a
historical record of all changes to Tk.

Tk is maintained, enhanced, and distributed freely by the Tcl community.
Source code development and tracking of bug reports and feature requests
take place at [core.tcl-lang.org](https://core.tcl-lang.org/).
Tcl/Tk release and mailing list services are [hosted by

The source code for Tk is managed by fossil.  Tk developers coordinate all
changes to the Tk source code at

> [Tk Source Code](https://core.tcl-lang.org/tk/)

Release Tk 8.7b1 arises from the check-in with tag core-8-7-b1.

Highlighted differences between Tk 8.7 and Tk 8.6 are summarized below,
with focus on changes important to programmers using the Tk library and
writing Tcl scripts containing Tk commands.

## Many improvements to use of platform features and conventions.
 - Built-in widgets and themes are scaling-aware.
 - Improved support of two-finger gestures, where available
 - The `tk windowingsystem` "aqua" needs macOS 10.9 or later

## New commands and options
 - `tk sysnotify` — Access to the OS notifications system
 - `tk systray` — Access to the OS tray facility
 - `tk print` — Access to the OS printing facility

## Widget options
 - New `ttk::progressbar` option: **-text**
 - `$frame ... -backgroundimage $img -tile $bool`
 - `$menu id`, `$menu add|insert ... ?$id? ...`
 - `$image get ... -withalpha ...`
 - All indices now accept the forms **end**, **end-int**, **int+|-int**

\fB#include <tk.h>\fR
.sp
void
\fBTk_AddOption\fR(\fItkwin, name, value, priority\fR)
.sp
Tcl_Obj *
\fBTk_GetSystemDefault\fR(\fItkwin, dbName, className\fR)

.SH ARGUMENTS
.AP Tk_Window tkwin in
Token for window.
.AP "const char" *name in
Multi-element name of option.
.AP "const char" *value in
Value of option.

.SH NAME
Tk_CreateBindingTable, Tk_DeleteBindingTable, Tk_CreateBinding, Tk_DeleteBinding, Tk_GetBinding, Tk_GetAllBindings, Tk_DeleteAllBindings, Tk_BindEvent \- invoke scripts in response to X events
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Tk_BindingTable
\fBTk_CreateBindingTable(\fIinterp\fB)\fR
.sp
\fBTk_DeleteBindingTable(\fIbindingTable\fB)\fR
.sp
unsigned long
\fBTk_CreateBinding(\fIinterp, bindingTable, object, eventString, script, append\fB)\fR
.sp
int
\fBTk_DeleteBinding(\fIinterp, bindingTable, object, eventString\fB)\fR
.sp
const char *
\fBTk_GetBinding(\fIinterp, bindingTable, object, eventString\fB)\fR
.sp
\fBTk_GetAllBindings(\fIinterp, bindingTable, object\fB)\fR
.sp
\fBTk_DeleteAllBindings(\fIbindingTable, object\fB)\fR
.sp
\fBTk_BindEvent(\fIbindingTable, eventPtr, tkwin, numObjects, objectPtr\fB)\fR

.SH ARGUMENTS
.AS Tk_BindingTable bindingTable
.AP Tcl_Interp *interp in
Interpreter to use when invoking bindings in binding table.  Also
used for returning results and errors from binding procedures.
.AP Tk_BindingTable bindingTable in
Token for binding table;  must have been returned by some previous

Non-zero means append \fIscript\fR to existing script for binding,
if any; zero means replace existing script with new one.
.AP XEvent *eventPtr in
X event to match against bindings in \fIbindingTable\fR.
.AP Tk_Window tkwin in
Identifier for any window on the display where the event occurred.
Used to find display-related information such as key maps.
.AP int numObjects in
Number of object identifiers pointed to by \fIobjectPtr\fR.
.AP "void **" objectPtr in
Points to an array of object identifiers:  bindings will be considered
for each of these objects in order from first to last.
.BE
.SH DESCRIPTION
.PP

int
\fBTk_CanvasPsFont\fR(\fIinterp, canvas, tkFont\fR)
.sp
\fBTk_CanvasPsPath\fR(\fIinterp, canvas, coordPtr, numPoints\fR)
.sp
int
\fBTk_CanvasPsStipple\fR(\fIinterp, canvas, bitmap\fR)

.SH ARGUMENTS
.AS int "numPoints"
.AP Tk_Canvas canvas in
A token that identifies a canvas widget for which Postscript is
being generated.
.AP double canvasY in
Y-coordinate in the space of the canvas.
.AP Tcl_Interp *interp in/out
A Tcl interpreter;  Postscript is appended to its result, or the

.AP Tk_Font tkFont in
Font for which Postscript is to be generated.
.AP double *coordPtr in
Pointer to an array of coordinates for one or more
points specified in canvas coordinates.
The order of values in \fIcoordPtr\fR is x1, y1, x2, y2, x3, y3,
and so on.
.AP int numPoints in
Number of points at \fIcoordPtr\fR.
.BE
.SH DESCRIPTION
.PP
These procedures are called by canvas type managers to carry out
common functions related to generating Postscript.
Most of the procedures take a \fIcanvas\fR argument, which

\fBTk_CanvasWindowCoords\fR(\fIcanvas, x, y, screenXPtr, screenYPtr\fR)
.sp
\fBTk_CanvasEventuallyRedraw\fR(\fIcanvas, x1, y1, x2, y2\fR)
.sp
Tk_OptionParseProc *\fBTk_CanvasTagsParseProc\fR;
.sp
Tk_OptionPrintProc *\fBTk_CanvasTagsPrintProc\fR;

.SH ARGUMENTS
.AS Tk_ItemType *drawableXPtr
.AP Tk_Canvas canvas in
A token that identifies a canvas widget.
.AP Tcl_Interp *interp in/out
Interpreter to use for error reporting.
.AP "const char" *string in

.CS
static const Tk_CustomOption tagsOption = {Tk_CanvasTagsParseProc,
    Tk_CanvasTagsPrintProc, NULL
};

static const Tk_ConfigSpec configSpecs[] = {
    ...
    {TK_CONFIG_CUSTOM, "\-tags", NULL, NULL,
        NULL, 0, TK_CONFIG_NULL_OK, &tagsOption},
    ...
};
.CE
.SH KEYWORDS
canvas, focus, item type, redisplay, selection, type manager

Tk_CanvasTextInfo \- additional information for managing text items in canvases
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Tk_CanvasTextInfo *
\fBTk_CanvasGetTextInfo\fR(\fIcanvas\fR)

.SH ARGUMENTS
.AS Tk_Canvas canvas
.AP Tk_Canvas canvas in
A token that identifies a particular canvas widget.
.BE
.SH DESCRIPTION
.PP
Textual canvas items are somewhat more complicated to manage than
other items, due to things like the selection and the input focus.
\fBTk_CanvasGetTextInfo\fR may be invoked by a type manager
to obtain additional information needed for items that display text.
The return value from \fBTk_CanvasGetTextInfo\fR is a pointer to
a structure that is shared between Tk and all the items that display
text.
The structure has the following form:
.CS
typedef struct Tk_CanvasTextInfo {
    Tk_3DBorder \fIselBorder\fR;
    int \fIselBorderWidth\fR;
    XColor *\fIselFgColorPtr\fR;
    Tk_Item *\fIselItemPtr\fR;
    int \fIselectFirst\fR;
    int \fIselectLast\fR;
    Tk_Item *\fIanchorItemPtr\fR;

\fB#include <tk.h>\fR
.sp
int
\fBTk_ClipboardClear\fR(\fIinterp, tkwin\fR)
.sp
int
\fBTk_ClipboardAppend\fR(\fIinterp, tkwin, target, format, buffer\fR)

.SH ARGUMENTS
.AS Tk_ClipboardClear tkwin
.AP Tcl_Interp *interp in
Interpreter to use for reporting errors.
.AP Tk_Window tkwin in
Window that determines which display's clipboard to manipulate.
.AP Atom target in

.SH NAME
Tk_ClearSelection \- Deselect a selection
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_ClearSelection\fR(\fItkwin, selection\fR)

.SH ARGUMENTS
.AS Tk_Window tkwin
.AP Tk_Window tkwin in
The selection will be cleared from the display containing this
window.
.AP Atom selection in
The name of selection to be cleared.

.SH NAME
Tk_ConfigureWidget, Tk_ConfigureInfo, Tk_ConfigureValue, Tk_FreeOptions \- process configuration options for widgets
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_ConfigureWidget(\fIinterp, tkwin, specs, argc, argv, widgRec, flags\fB)\fR
.sp
int
\fBTk_ConfigureInfo(\fIinterp, tkwin, specs, widgRec, argvName, flags\fB)\fR
.sp
int
\fBTk_ConfigureValue(\fIinterp, tkwin, specs, widgRec, argvName, flags\fB)\fR
.sp
\fBTk_FreeOptions(\fIspecs, widgRec, display, flags\fB)\fR

.SH ARGUMENTS
.AS void *widgRec in/out
.AP Tcl_Interp *interp in
Interpreter to use for returning error messages.
.AP Tk_Window tkwin in
Window used to represent widget (needed to set up X resources).
.AP "const Tk_ConfigSpec" *specs in
Pointer to table specifying legal configuration options for this
widget.
.AP int argc in
Number of arguments in \fIargv\fR.
.AP "const char" **argv in
Command-line options for configuring widget.
.AP char *widgRec in/out
Points to widget record structure.  Fields in this structure get
modified by \fBTk_ConfigureWidget\fR to hold configuration information.
.AP int flags in
If non-zero, then it specifies an OR-ed combination of flags that
control the processing of configuration information.

options.
.AP Display *display in
Display containing widget whose record is being freed;  needed in
order to free up resources.
.BE
.SH DESCRIPTION
.PP
Note: \fBTk_ConfigureWidget\fR should be replaced with the new
\fBTcl_Obj\fR based API \fBTk_SetOptions\fR.  The old interface is
retained for backward compatibility.
.PP
\fBTk_ConfigureWidget\fR is called to configure various aspects of a
widget, such as colors, fonts, border width, etc.
It is intended as a convenience procedure to reduce the amount
of code that must be written in individual widget managers to
handle configuration information.
It is typically
invoked when widgets are created, and again when the \fBconfigure\fR
command is invoked for a widget.
Although intended primarily for widgets, \fBTk_ConfigureWidget\fR
can be used in other situations where \fIargc-argv\fR information
is to be used to fill in a record structure, such as configuring
graphical elements for a canvas widget or entries of a menu.
.PP
\fBTk_ConfigureWidget\fR processes
a table specifying the configuration options that are supported
(\fIspecs\fR) and a collection of command-line arguments (\fIargc\fR and
\fIargv\fR) to fill in fields of a record (\fIwidgRec\fR).
It uses the option database and defaults specified in \fIspecs\fR
to fill in fields of \fIwidgRec\fR that are not specified in \fIargv\fR.
\fBTk_ConfigureWidget\fR normally returns the value \fBTCL_OK\fR; in this
case it does not modify \fIinterp\fR.
If an error
occurs then \fBTCL_ERROR\fR is returned and \fBTk_ConfigureWidget\fR will
leave an error message in interpreter \fIinterp\fR's result in the standard Tcl
fashion.
In the event of an error return, some of the fields of \fIwidgRec\fR

(e.g. \fBTK_CONFIG_COLOR\fR for a color value, or \fBTK_CONFIG_INT\fR for
an integer value).  The \fItype\fR field indicates how to use the
value of the option (more on this below).
The \fIargvName\fR field is a string such as
.QW \-font
or
.QW \-bg ,
which is compared with the values in \fIargv\fR (if \fIargvName\fR is
NULL it means this is a grouped entry;  see \fBGROUPED ENTRIES\fR below).  The
\fIdbName\fR and \fIdbClass\fR fields are used to look up a value
for this option in the option database.  The \fIdefValue\fR field
specifies a default value for this configuration option if no
value is specified in either \fIargv\fR or the option database.
\fIOffset\fR indicates where in \fIwidgRec\fR to store information
about this option, and \fIspecFlags\fR contains additional information
to control the processing of this configuration option (see FLAGS
below).
The last field, \fIcustomPtr\fR, is only used if \fItype\fR is
\fBTK_CONFIG_CUSTOM\fR;  see CUSTOM OPTION TYPES below.
.PP
\fBTk_ConfigureWidget\fR first processes \fIargv\fR to see which
(if any) configuration options are specified there.  \fIArgv\fR
must contain an even number of fields;  the first of each pair
of fields must match the \fIargvName\fR of some entry in \fIspecs\fR
(unique abbreviations are acceptable),
and the second field of the pair contains the value for that
configuration option.  If there are entries in \fIspec\fR for which
there were no matching entries in \fIargv\fR,
\fBTk_ConfigureWidget\fR uses the \fIdbName\fR and \fIdbClass\fR
fields of the \fIspecs\fR entry to probe the option database;  if
a value is found, then it is used as the value for the option.
Finally, if no entry is found in the option database, the
\fIdefValue\fR field of the \fIspecs\fR entry is used as the
value for the configuration option.  If the \fIdefValue\fR is
NULL, or if the \fBTK_CONFIG_DONT_SET_DEFAULT\fR bit is set in
\fIflags\fR, then there is no default value and this \fIspecs\fR entry
will be ignored if no value is specified in \fIargv\fR or the
option database.
.PP
Once a string value has been determined for a configuration option,
\fBTk_ConfigureWidget\fR translates the string value into a more useful
form, such as a color if \fItype\fR is \fBTK_CONFIG_COLOR\fR or an integer
if \fItype\fR is \fBTK_CONFIG_INT\fR.  This value is then stored in the
record pointed to by \fIwidgRec\fR.  This record is assumed to

in the descriptions below.
.PP
The \fItype\fR field of each entry in \fIspecs\fR determines what
to do with the string value of that configuration option.  The
legal values for \fItype\fR, and the corresponding actions, are:
.TP
\fBTK_CONFIG_ACTIVE_CURSOR\fR

The value
must be an ASCII string identifying a cursor in a form
suitable for passing to \fBTk_GetCursor\fR.
The value is converted to a \fBTk_Cursor\fR by calling
\fBTk_GetCursor\fR and the result is stored in the target.
In addition, the resulting cursor is made the active cursor
for \fItkwin\fR by calling \fBXDefineCursor\fR.
If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
may be an empty string, in which case the target and \fItkwin\fR's
active cursor will be set to \fBNone\fR.
If the previous value of the target
was not \fBNone\fR, then it is freed by passing it to \fBTk_FreeCursor\fR.
.TP
\fBTK_CONFIG_ANCHOR\fR

The value must be an ASCII string identifying an anchor point in one of the ways
accepted by \fBTk_GetAnchor\fR.
The string is converted to a \fBTk_Anchor\fR by calling
\fBTk_GetAnchor\fR and the result is stored in the target.
.TP
\fBTK_CONFIG_BITMAP\fR

The value must be an ASCII string identifying a bitmap in a form
suitable for passing to \fBTk_GetBitmap\fR.  The value is converted
to a \fBPixmap\fR by calling \fBTk_GetBitmap\fR and the result
is stored in the target.
If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
may be an empty string, in which case the target is set to \fBNone\fR.
If the previous value of the target
was not \fBNone\fR, then it is freed by passing it to \fBTk_FreeBitmap\fR.
.TP
\fBTK_CONFIG_BOOLEAN\fR

The value must be an ASCII string specifying a boolean value.  Any
of the values
.QW true ,
.QW yes ,
.QW on ,
or
.QW 1 ,
or an abbreviation of one of these values, means true;
any of the values
.QW false ,
.QW no ,
.QW off ,
or
.QW 0 ,
or an abbreviation of one of these values, means false.
The target is expected to be an integer;  for true values it will
be set to 1 and for false values it will be set to 0.
.TP
\fBTK_CONFIG_BORDER\fR

The value must be an ASCII string identifying a border color in a form
suitable for passing to \fBTk_Get3DBorder\fR.  The value is converted
to a (\fBTk_3DBorder *\fR) by calling \fBTk_Get3DBorder\fR and the result
is stored in the target.
If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
may be an empty string, in which case the target will be set to NULL.
If the previous value of the target
was not NULL, then it is freed by passing it to \fBTk_Free3DBorder\fR.
.TP
\fBTK_CONFIG_CAP_STYLE\fR

The value must be
an ASCII string identifying a cap style in one of the ways
accepted by \fBTk_GetCapStyle\fR.
The string is converted to an integer value corresponding
to the cap style by calling
\fBTk_GetCapStyle\fR and the result is stored in the target.
.TP
\fBTK_CONFIG_COLOR\fR

The value must be an ASCII string identifying a color in a form
suitable for passing to \fBTk_GetColor\fR.  The value is converted
to an (\fBXColor *\fR) by calling \fBTk_GetColor\fR and the result
is stored in the target.
If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
may be an empty string, in which case the target will be set to \fBNone\fR.
If the previous value of the target
was not NULL, then it is freed by passing it to \fBTk_FreeColor\fR.
.TP
\fBTK_CONFIG_CURSOR\fR

This option is identical to \fBTK_CONFIG_ACTIVE_CURSOR\fR except
that the new cursor is not made the active one for \fItkwin\fR.
.TP
\fBTK_CONFIG_CUSTOM\fR

This option allows applications to define new option types.
The \fIcustomPtr\fR field of the entry points to a structure
defining the new option type.
See the section \fBCUSTOM OPTION TYPES\fR below for details.
.TP
\fBTK_CONFIG_DOUBLE\fR

The value must be an ASCII floating-point number in
the format accepted by \fBstrtol\fR.  The string is converted
to a \fBdouble\fR value, and the value is stored in the
target.
.TP
\fBTK_CONFIG_END\fR

Marks the end of the table.  The last entry in \fIspecs\fR
must have this type;  all of its other fields are ignored and it
will never match any arguments.
.TP
\fBTK_CONFIG_FONT\fR

The value must be an ASCII string identifying a font in a form
suitable for passing to \fBTk_GetFont\fR.  The value is converted
to a \fBTk_Font\fR by calling \fBTk_GetFont\fR and the result
is stored in the target.
If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
may be an empty string, in which case the target will be set to NULL.
If the previous value of the target
was not NULL, then it is freed by passing it to \fBTk_FreeFont\fR.
.TP
\fBTK_CONFIG_INT\fR

The value must be an ASCII integer string
in the format accepted by \fBstrtol\fR (e.g.
.QW 0
and
.QW 0x
prefixes may be used to specify octal or hexadecimal
numbers, respectively).  The string is converted to an integer
value and the integer is stored in the target.
.TP
\fBTK_CONFIG_JOIN_STYLE\fR

The value must be
an ASCII string identifying a join style in one of the ways
accepted by \fBTk_GetJoinStyle\fR.
The string is converted to an integer value corresponding
to the join style by calling
\fBTk_GetJoinStyle\fR and the result is stored in the target.
.TP
\fBTK_CONFIG_JUSTIFY\fR

The value must be
an ASCII string identifying a justification method in one of the
ways accepted by \fBTk_GetJustify\fR.
The string is converted to a \fBTk_Justify\fR by calling
\fBTk_GetJustify\fR and the result is stored in the target.
.TP
\fBTK_CONFIG_MM\fR

The value must specify a screen distance in one of the forms acceptable
to \fBTk_GetScreenMM\fR.
The string is converted to double-precision floating-point distance
in millimeters and the value is stored in the target.
.TP
\fBTK_CONFIG_PIXELS\fR

The value must specify screen units in one of the forms acceptable
to \fBTk_GetPixels\fR.
The string is converted to an integer distance in pixels and the
value is stored in the target.
.TP
\fBTK_CONFIG_RELIEF\fR

The value must be an ASCII string identifying a relief in a form
suitable for passing to \fBTk_GetRelief\fR.  The value is converted
to an integer relief value by calling \fBTk_GetRelief\fR and the result
is stored in the target.
.TP
\fBTK_CONFIG_STRING\fR

A copy
of the value is made by allocating memory space with
\fBTcl_Alloc\fR and copying the value into the dynamically-allocated
space.  A pointer to the new string is stored in the target.
If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
may be an empty string, in which case the target will be set to NULL.
If the previous value of the target was not NULL, then it is
freed by passing it to \fBTcl_Free\fR.
.TP
\fBTK_CONFIG_SYNONYM\fR

This \fItype\fR value identifies special entries in \fIspecs\fR that
are synonyms for other entries.  If an \fIargv\fR value matches the
\fIargvName\fR of a \fBTK_CONFIG_SYNONYM\fR entry, the entry is not used
directly. Instead, \fBTk_ConfigureWidget\fR searches \fIspecs\fR
for another entry whose \fIargvName\fR is the same as the \fIdbName\fR
field in the \fBTK_CONFIG_SYNONYM\fR entry;  this new entry is used just
as if its \fIargvName\fR had matched the \fIargv\fR value.  The
synonym mechanism allows multiple \fIargv\fR values to be used for
a single configuration option, such as
.QW \-background
and
.QW \-bg .
.TP
\fBTK_CONFIG_UID\fR

The value is translated to a \fBTk_Uid\fR
(by passing it to \fBTk_GetUid\fR).  The resulting value
is stored in the target.
If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR and the value
is an empty string then the target will be set to NULL.
.TP
\fBTK_CONFIG_WINDOW\fR

The value must be a window path name.  It is translated to a
\fBTk_Window\fR token and the token is stored in the target.
.SH "GROUPED ENTRIES"
.PP
In some cases it is useful to generate multiple resources from
a single configuration value.  For example, a color name might
be used both to generate the background color for a widget (using

The \fIflags\fR argument passed to \fBTk_ConfigureWidget\fR is used
in conjunction with the \fIspecFlags\fR fields in the entries of \fIspecs\fR
to provide additional control over the processing of configuration
options.  These values are used in three different ways as
described below.
.PP
First, if the \fIflags\fR argument to \fBTk_ConfigureWidget\fR has
the \fBTK_CONFIG_ARGV_ONLY\fR bit set (i.e., \fIflags\fR | \fBTK_CONFIG_ARGV_ONLY\fR != 0),

then the option database and
\fIdefValue\fR fields are not used.  In this case, if an entry in
\fIspecs\fR does not match a field in \fIargv\fR then nothing happens:
the corresponding target is not modified.  This feature is useful
when the goal is to modify certain configuration options while
leaving others in their current state, such as when a \fBconfigure\fR
widget command is being processed.
.PP
Second, the \fIspecFlags\fR field of an entry in \fIspecs\fR may be used
to control the processing of that entry.  Each \fIspecFlags\fR
field may consists of an OR-ed combination of the following values:
.TP
\fBTK_CONFIG_COLOR_ONLY\fR

If this bit is set then the entry will only be considered if the
display for \fItkwin\fR has more than one bit plane.  If the display
is monochromatic then this \fIspecs\fR entry will be ignored.
.TP
\fBTK_CONFIG_MONO_ONLY\fR

If this bit is set then the entry will only be considered if the
display for \fItkwin\fR has exactly one bit plane.  If the display
is not monochromatic then this \fIspecs\fR entry will be ignored.
.TP
\fBTK_CONFIG_NULL_OK\fR

This bit is only relevant for some types of entries (see the
descriptions of the various entry types above).
If this bit is set, it indicates that an empty string value
for the field is acceptable and if it occurs then the
target should be set to NULL or \fBNone\fR, depending
on the type of the target.
This flag is typically used to allow a
feature to be turned off entirely, e.g. set a cursor value to
\fBNone\fR so that a window simply inherits its parent's cursor.
If this bit is not set then empty strings are processed as strings,
which generally results in an error.
.TP
\fBTK_CONFIG_DONT_SET_DEFAULT\fR

If this bit is one, it means that the \fIdefValue\fR field of the
entry should only be used for returning the default value in
\fBTk_ConfigureInfo\fR.
In calls to \fBTk_ConfigureWidget\fR no default will be supplied
for entries with this flag set;  it is assumed that the
caller has already supplied a default value in the target location.
This flag provides a performance optimization where it is expensive
to process the default string:  the client can compute the default
once, save the value, and provide it before calling
\fBTk_ConfigureWidget\fR.
.TP
\fBTK_CONFIG_OPTION_SPECIFIED\fR
This bit is
deprecated. It used to be set and cleared by \fBTk_ConfigureWidget\fR
so that callers could detect what entries were specified in
\fIargv\fR, but it was removed because it was inherently
thread-unsafe. Code that wishes to detect what options were specified
should use \fBTk_SetOptions\fR instead.
.PP
The \fBTK_CONFIG_MONO_ONLY\fR and \fBTK_CONFIG_COLOR_ONLY\fR flags are typically
used to specify different default values for
monochrome and color displays.  This is done by creating two
entries in \fIspecs\fR that are identical except for their
\fIdefValue\fR and \fIspecFlags\fR fields.  One entry should have
the value \fBTK_CONFIG_MONO_ONLY\fR in its \fIspecFlags\fR and the

corresponding field of the widget record to null.
.SH "CUSTOM OPTION TYPES"
.PP
Applications can extend the built-in configuration types with additional
configuration types by writing procedures to parse and print options
of the a type and creating a structure pointing to those procedures:
.CS
typedef struct Tk_CustomOption {
    Tk_OptionParseProc *\fIparseProc\fR;
    Tk_OptionPrintProc *\fIprintProc\fR;
    void *\fIclientData\fR;
} \fBTk_CustomOption\fR;

typedef int \fBTk_OptionParseProc\fR(
        void *\fIclientData\fR,
        Tcl_Interp *\fIinterp\fR,
        Tk_Window \fItkwin\fR,
        char *\fIvalue\fR,
        char *\fIwidgRec\fR,
        int \fIoffset\fR);

typedef const char *\fBTk_OptionPrintProc\fR(
        void *\fIclientData\fR,
        Tk_Window \fItkwin\fR,
        char *\fIwidgRec\fR,
        int \fIoffset\fR,
        Tcl_FreeProc **\fIfreeProcPtr\fR);
.CE
The Tk_CustomOption structure contains three fields, which are pointers
to the two procedures and a \fIclientData\fR value to be passed to those
procedures when they are invoked.  The \fIclientData\fR value typically
points to a structure containing information that is needed by the
procedures when they are parsing and printing options.

\fBTk_SetWindowBorderPixmap\fR(\fItkwin, pixmap\fR)
.sp
\fBTk_SetWindowColormap\fR(\fItkwin, colormap\fR)
.sp
\fBTk_DefineCursor\fR(\fItkwin, cursor\fR)
.sp
\fBTk_UndefineCursor\fR(\fItkwin\fR)

.SH ARGUMENTS
.AS XSetWindowAttributes borderWidth
.AP Tk_Window tkwin in
Token for window.
.AP "unsigned int" valueMask in
OR-ed mask of values like \fBCWX\fR or \fBCWBorderPixel\fR,
indicating which fields of \fI*valuePtr\fR or \fI*attsPtr\fR to use.

Tk_CoordsToWindow \- Find window containing a point
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Tk_Window
\fBTk_CoordsToWindow\fR(\fIrootX, rootY, tkwin\fR)

.SH ARGUMENTS
.AS Tk_Window tkwin
.AP int rootX in
X-coordinate (in root window coordinates).
.AP int rootY in
Y-coordinate (in root window coordinates).
.AP Tk_Window tkwin in

.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_CreateClientMessageHandler\fR(\fIproc\fR)
.sp
\fBTk_DeleteClientMessageHandler\fR(\fIproc\fR)

.SH ARGUMENTS
.AP Tk_ClientMessageProc *proc in
Procedure to invoke whenever a ClientMessage X event occurs on any display.
.BE
.SH DESCRIPTION
.PP
\fBTk_CreateClientMessageHandler\fR arranges for \fIproc\fR to be invoked

.SH NAME
Tk_InitConsoleChannels \- Install the console channels as standard channels
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_InitConsoleChannels\fR(\fIinterp\fR)

.SH ARGUMENTS
.AS Tcl_Interp *interp in
.AP Tcl_Interp *interp in
Interpreter in which the console channels are created.
.BE
.SH DESCRIPTION
.PP

.nf
\fB#include <tk.h>\fR
.sp
Tk_ErrorHandler
\fBTk_CreateErrorHandler\fR(\fIdisplay, error, request, minor, proc, clientData\fR)
.sp
\fBTk_DeleteErrorHandler\fR(\fIhandler\fR)

.SH ARGUMENTS
.AS "Tk_ErrorHandler" clientData
.AP Display *display in
Display whose errors are to be handled.
.AP int error in
Match only error events with this value in the \fIerror_code\fR
field.  If \-1, then match any \fIerror_code\fR value.

.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_CreateGenericHandler\fR(\fIproc, clientData\fR)
.sp
\fBTk_DeleteGenericHandler\fR(\fIproc, clientData\fR)

.SH ARGUMENTS
.AS "Tk_GenericProc" clientData
.AP Tk_GenericProc *proc in
Procedure to invoke whenever any X event occurs on any display.
.AP void *clientData in
Arbitrary one-word value to pass to \fIproc\fR.
.BE

'\"
'\" Copyright (c) 1994 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH Tk_CreateImageType 3 8.5 Tk "Tk Library Procedures"
.so man.macros
.BS
.SH NAME
Tk_CreateImageType, Tk_GetImageModelData, Tk_InitImageArgs \- define new kind of image
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_CreateImageType\fR(\fItypePtr\fR)
.sp
void *
\fBTk_GetImageModelData\fR(\fIinterp, name, typePtrPtr\fR)
.sp
\fBTk_InitImageArgs\fR(\fIinterp, argc, argvPtr\fR)
.SH ARGUMENTS
.AS "const Tk_ImageType" *typePtrPtr
.AP "const Tk_ImageType" *typePtr in
Structure that defines the new type of image.
For Tk 8.4 and earlier this must be static: a
pointer to this structure is retained by the image code.
In Tk 8.5, this limitation was relaxed.
.AP Tcl_Interp *interp in
Interpreter in which image was created.
.AP "const char" *name in
Name of existing image.
.AP Tk_ImageType **typePtrPtr out
Points to word in which to store a pointer to type information for
the given image, if it exists.
.AP int argc in
Number of arguments
.AP char ***argvPtr in/out
Pointer to argument list
.BE
.SH DESCRIPTION
.PP
\fBTk_CreateImageType\fR is invoked to define a new kind of image.
An image type corresponds to a particular value of the \fItype\fR

\fIimage manager\fR.
It consists of a collection of procedures plus three different
kinds of data structures.
The first data structure is a Tk_ImageType structure, which contains
the name of the image type and pointers to five procedures provided
by the image manager to deal with images of this type:
.CS
typedef struct Tk_ImageType {
    const char *\fIname\fR;
    Tk_ImageCreateProc *\fIcreateProc\fR;
    Tk_ImageGetProc *\fIgetProc\fR;
    Tk_ImageDisplayProc *\fIdisplayProc\fR;
    Tk_ImageFreeProc *\fIfreeProc\fR;
    Tk_ImageDeleteProc *\fIdeleteProc\fR;
} \fBTk_ImageType\fR;

in the interpreter given by \fIinterp\fR, then \fI*typePtrPtr\fR is
filled in with type information for the image (the \fItypePtr\fR value
passed to \fBTk_CreateImageType\fR when the image type was registered)
and the return value is the clientData value returned by the
\fIcreateProc\fR when the image was created (this is typically a
pointer to the image model data structure).  If no such image exists
then NULL is returned and NULL is stored at \fI*typePtrPtr\fR.
.SH "LEGACY INTERFACE SUPPORT"
.PP
In Tk 8.2 and earlier, the definition of \fBTk_ImageCreateProc\fR
was incompatibly different, with the following prototype:
.CS
typedef int \fBTk_ImageCreateProc\fR(
        Tcl_Interp *\fIinterp\fR,
        char *\fIname\fR,
        int \fIargc\fR,
        char **\fIargv\fR,
        Tk_ImageType *\fItypePtr\fR,
        Tk_ImageModel \fImodel\fR,
        void **\fImodelDataPtr\fR);
.CE
Legacy programs and libraries dating from those days may still
contain code that defines extended Tk image types using the old
interface.  The Tk header file will still support this legacy
interface if the code is compiled with the macro \fBUSE_OLD_IMAGE\fR
defined.
.PP
When the \fBUSE_OLD_IMAGE\fR legacy support is enabled, you may
see the routine \fBTk_InitImageArgs\fR in use.  This was a migration
tool used to create stub-enabled extensions that could be loaded
into interps containing all versions of Tk 8.1 and later.  Tk 8.5 no longer
provides this routine, but uses a macro to convert any attempted
calls of this routine into an empty comment.  Any stub-enabled
extension providing an extended image type via the legacy interface
that is compiled against Tk 8.5 headers and linked against the
Tk 8.5 stub library will produce a file that can be loaded only
into interps with Tk 8.5 or later; that is, the normal stub-compatibility
rules.  If a developer needs to generate from such code a file
that is loadable into interps with Tk 8.4 or earlier, they must
use Tk 8.4 headers and stub libraries to do so.
.PP
Any new code written today should not make use of the legacy
interfaces.  Expect their support to go away in Tk 9.
.SH "SEE ALSO"
Tk_ImageChanged, Tk_GetImage, Tk_FreeImage, Tk_RedrawImage, Tk_SizeOfImage
.SH KEYWORDS
image manager, image type, instance, model

.nf
\fB#include <tk.h>\fR
.sp
\fBTk_CreateItemType\fR(\fItypePtr\fR)
.sp
Tk_ItemType *
\fBTk_GetItemTypes\fR()

.SH ARGUMENTS
.AS Tk_ItemType *typePtr
.AP Tk_ItemType *typePtr in
Structure that defines the new type of canvas item.

.BE
.SH INTRODUCTION
.PP
\fBTk_CreateItemType\fR is invoked to define a new kind of canvas item
described by the \fItypePtr\fR argument.
An item type corresponds to a particular value of the \fItype\fR
argument to the \fBcreate\fR widget command for canvases, and

    size_t \fIitemSize\fR;
    Tk_ItemCreateProc *\fIcreateProc\fR;
    const Tk_ConfigSpec *\fIconfigSpecs\fR;
    Tk_ItemConfigureProc *\fIconfigProc\fR;
    Tk_ItemCoordProc *\fIcoordProc\fR;
    Tk_ItemDeleteProc *\fIdeleteProc\fR;
    Tk_ItemDisplayProc *\fIdisplayProc\fR;
    int \fIalwaysRedraw\fR;
    Tk_ItemPointProc *\fIpointProc\fR;
    Tk_ItemAreaProc *\fIareaProc\fR;
    Tk_ItemPostscriptProc *\fIpostscriptProc\fR;
    Tk_ItemScaleProc *\fIscaleProc\fR;
    Tk_ItemTranslateProc *\fItranslateProc\fR;
    Tk_ItemIndexProc *\fIindexProc\fR;
    Tk_ItemCursorProc *\fIicursorProc\fR;
    Tk_ItemSelectionProc *\fIselectionProc\fR;
    Tk_ItemInsertProc *\fIinsertProc\fR;
    Tk_ItemDCharsProc *\fIdCharsProc\fR;
    Tk_ItemType *\fInextPtr\fR;
.VS "8.7, TIP164"
    Tk_ItemRotateProc *\fIrotateProc\fR;
.VE "8.7, TIP164"
} \fBTk_ItemType\fR;
.CE
.PP
The fields of a Tk_ItemType structure are described in more detail

defined by Tk via the type Tk_Item; the rest of the item
record is defined by the type manager.
A type manager must define its item records with a Tk_Item as
the first field.
For example, the item record for bitmap items is defined as follows:
.PP
.CS
typedef struct BitmapItem {
    Tk_Item \fIheader\fR;
    double \fIx\fR, \fIy\fR;
    Tk_Anchor \fIanchor\fR;
    Pixmap \fIbitmap\fR;
    XColor *\fIfgColor\fR;
    XColor *\fIbgColor\fR;
    GC \fIgc\fR;

Once \fBTk_CreateImageType\fR returns, this name may be used
in \fBcreate\fR widget commands to create items of the new
type.
If there already existed an item type by this name then
the new item type replaces the old one.
.SS "FLAGS (IN ALWAYSREDRAW)"
.PP
The \fItypePtr\->alwaysRedraw\fR field (so named for historic reasons)
contains a collection of flag bits that modify how the canvas core interacts
with the item. The following bits are defined:
.TP
\fBTK_ALWAYS_REDRAW\fR
.
Indicates that the item should always be redrawn when any part of the canvas
is redrawn, rather than only when the bounding box of the item overlaps the
area being redrawn. This is used by window items, for example, which need to
unmap subwindows that are not on the screen.
.TP
\fBTK_CONFIG_OBJS\fR
.
Indicates that operations which would otherwise take a string (or array of
strings) actually take a Tcl_Obj reference (or an array of such references).
The operations to which this applies are the \fIconfigProc\fR, the
\fIcoordProc\fR, the \fIcreateProc\fR, the \fIindexProc\fR and the
\fIinsertProc\fR.
.TP
\fBTK_MOVABLE_POINTS\fR
.VS 8.6
Indicates that the item supports the \fIdCharsProc\fR, \fIindexProc\fR and
\fIinsertProc\fR with the same semantics as Tk's built-in line and polygon
types, and that hence individual coordinate points can be moved. Must not be
set if any of the above methods is NULL.

\fIitemPtr\fR is a pointer to a newly-allocated item of
size \fItypePtr\->itemSize\fR.
Tk has already initialized the item's header (the first
\fBsizeof(Tk_ItemType)\fR bytes).
The \fIobjc\fR and \fIobjv\fR arguments describe all of the
arguments to the \fBcreate\fR command after the \fItype\fR
argument.
Note that if \fBTK_CONFIG_OBJS\fR is not set in the
\fItypePtr\->alwaysRedraw\fR field, the \fIobjv\fR parameter will actually
contain a pointer to an array of constant strings.
For example, in the widget command:
.PP
.CS
\fB\&.c create rectangle 10 20 50 50 \-fill black\fR
.CE
.PP
\fIobjc\fR will be \fB6\fR and \fIobjv\fR[0] will contain the

\fBTk_ConfigureWidget\fR.
This table will normally be used by \fItypePtr\->createProc\fR
and \fItypePtr\->configProc\fR, but Tk also uses it directly
to retrieve option information in the \fBitemcget\fR and
\fBitemconfigure\fR widget commands.
\fItypePtr\->configSpecs\fR must point to the configuration table
for this type.

Note: Tk provides a custom option type \fBtk_CanvasTagsOption\fR
for implementing the \fB\-tags\fR option; see an existing type
manager for an example of how to use it in \fIconfigSpecs\fR.
.SS CONFIGPROC
.PP
\fItypePtr\->configProc\fR is called by Tk whenever the
\fBitemconfigure\fR widget command is invoked to change the
configuration options for a canvas item.

        int \fIflags\fR);
.CE
.PP
The \fIinterp\fR argument identifies the interpreter in which the
widget command was invoked, \fIcanvas\fR is a handle for the canvas
widget, and \fIitemPtr\fR is a pointer to the item being configured.
\fIobjc\fR and \fIobjv\fR contain the configuration options.
Note that if \fBTK_CONFIG_OBJS\fR is not set in the
\fItypePtr\->alwaysRedraw\fR field, the \fIobjv\fR parameter will actually
contain a pointer to an array of constant strings.
For example, if the following command is invoked:
.PP
.CS
\fB\&.c itemconfigure 2 \-fill red \-outline black\fR
.CE
.PP
\fIobjc\fR is \fB4\fR and \fIobjv\fR contains the string objects \fB\-fill\fR

        int \fIobjc\fR,
        Tcl_Obj *const \fIobjv\fR[]);
.CE
.PP
The arguments \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR
all have the standard meanings, and \fIobjc\fR and \fIobjv\fR
describe the coordinate arguments.
Note that if \fBTK_CONFIG_OBJS\fR is not set in the
\fItypePtr\->alwaysRedraw\fR field, the \fIobjv\fR parameter will actually
contain a pointer to an array of constant strings.
For example, if the following widget command is invoked:
.PP
.CS
\fB\&.c coords 2 30 90\fR
.CE
.PP
\fIobjc\fR will be \fB2\fR and \fBobjv\fR will contain the integer objects

will not necessarily be the same as those in the canvas.
\fIdisplayProc\fR should call \fBTk_CanvasDrawableCoords\fR
to transform coordinates from those of the canvas to those
of \fIdst\fR.
.PP
Normally an item's \fIdisplayProc\fR is only invoked if the item
overlaps the area being displayed.
However, if bit zero of \fItypePtr\->alwaysRedraw\fR is 1,
(i.e.\|
.QW "\fItypePtr\->alwaysRedraw & 1 == 1\fR" )
then \fIdisplayProc\fR is invoked during every redisplay operation,
even if the item does not overlap the area of redisplay; this is useful for
cases such as window items, where the subwindow needs to be unmapped when it
is off the screen.
.SS POINTPROC
.PP
\fItypePtr\->pointProc\fR is invoked by Tk to find out how close

the item is to be rotated, and \fIangleRad\fR gives the anticlockwise
rotation to be applied in radians.
The item should adjust the coordinates of its control points so that where
they used to have coordinates \fIx\fR and \fIy\fR, they will have new
coordinates \fIx\(fm\fR and \fIy\(fm\fR, where
.PP
.CS
\fIrelX\fR = \fIx\fR - \fIoriginX\fR
\fIrelY\fR = \fIy\fR - \fIoriginY\fR
\fIx\(fm\fR = \fIoriginX\fR + \fIrelX\fR \(mu cos(\fIangleRad\fR) + \fIrelY\fR \(mu sin(\fIangleRad\fR)
\fIy\(fm\fR = \fIoriginY\fR \(mi \fIrelX\fR \(mu sin(\fIangleRad\fR) + \fIrelY\fR \(mu cos(\fIangleRad\fR)
.CE
.PP
The control points for an item are not necessarily the coordinates provided to
the item when it is created (or via the \fItypePtr\->coordProc\fR), but could
instead be derived from them.

.CE
.PP
The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all
have the usual meaning.
\fIindexObj\fR contains a textual description of an index,
and \fIindexPtr\fR points to an integer value that should be
filled in with a numerical index.
Note that if \fBTK_CONFIG_OBJS\fR is not set in the
\fItypePtr\->alwaysRedraw\fR field, the \fIindexObj\fR parameter will
actually contain a pointer to a constant string.
It is up to the type manager to decide what forms of index
are supported (e.g., numbers, \fBinsert\fR, \fBsel.first\fR,
\fBend\fR, etc.).
\fIindexProc\fR should return a Tcl completion code and set
the interpreter result in the event of an error.
.SS ICURSORPROC
.PP

.CE
.PP
\fIcanvas\fR and \fIitemPtr\fR have the usual meanings.
\fIindex\fR is an index into the item's text, as returned by a
previous call to \fItypePtr\->insertProc\fR, and \fIobj\fR
contains new text to insert just before the character given
by \fIindex\fR.
Note that if \fBTK_CONFIG_OBJS\fR is not set in the
\fItypePtr\->alwaysRedraw\fR field, the \fIobj\fR parameter will
actually contain a pointer to a constant string to be inserted.
If the item supports modification of the coordinates list by this
.PP
The type manager should insert the text and recompute the bounding
box in the item's header.
.SS DCHARSPROC
.PP
\fItypePtr\->dCharsProc\fR is invoked by Tk during the \fBdchars\fR

An image file format handler consists of a collection of procedures
plus a \fBTk_PhotoImageFormatVersion3\fR structure, which contains the
name of the image file format and pointers to six procedures provided
by the handler to deal with files and strings in this format.  The
Tk_PhotoImageFormatVersion3 structure contains the following fields:
.VS 8.7
.CS
typedef struct Tk_PhotoImageFormatVersion3 {
    const char *\fIname\fR;
    Tk_ImageFileMatchProcVersion3 *\fIfileMatchProc\fR;
    Tk_ImageStringMatchProcVersion3 *\fIstringMatchProc\fR;
    Tk_ImageFileReadProcVersion3 *\fIfileReadProc\fR;
    Tk_ImageStringReadProcVersion3 *\fIstringReadProc\fR;
    Tk_ImageFileWriteProcVersion3 *\fIfileWriteProc\fR;
    Tk_ImageStringWriteProcVersion3 *\fIstringWriteProc\fR;

return 0.
.SS FILEREADPROC
.PP
\fIformatPtr->fileReadProc\fR provides the address of a procedure for
Tk to call to read data from an image file into a photo image.
\fIformatPtr->fileReadProc\fR must match the following prototype:
.CS
typedef int \fBTk_ImageFileReadProc\fR(
        Tcl_Interp *\fIinterp\fR,
        Tcl_Channel \fIchan\fR,
        const char *\fIfileName\fR,
        Tcl_Obj *\fIformat\fR,
        Tcl_Obj *\fImetadataIn\fR,
        PhotoHandle \fIimageHandle\fR,
        int \fIdestX\fR, int \fIdestY\fR,

The return value is a standard Tcl return value.
.SS STRINGREADPROC
.PP
\fIformatPtr->stringReadProc\fR provides the address of a procedure
for Tk to call to read data from a string into a photo image.
\fIformatPtr->stringReadProc\fR must match the following prototype:
.CS
typedef int \fBTk_ImageStringReadProc\fR(
        Tcl_Interp *\fIinterp\fR,
        Tcl_Obj *\fIdata\fR,
        Tcl_Obj *\fIformat\fR,
        Tcl_Obj *\fImetadataIn\fR,
        PhotoHandle \fIimageHandle\fR,
        int \fIdestX\fR, int \fIdestY\fR,
        int \fIwidth\fR, int \fIheight\fR,

The return value is a standard Tcl return value.
.SS FILEWRITEPROC
.PP
\fIformatPtr->fileWriteProc\fR provides the address of a procedure for
Tk to call to write data from a photo image to a file.
\fIformatPtr->fileWriteProc\fR must match the following prototype:
.CS
typedef int \fBTk_ImageFileWriteProc\fR(
        Tcl_Interp *\fIinterp\fR,
        const char *\fIfileName\fR,
        Tcl_Obj *\fIformat\fR,
        Tcl_Obj *\fImetadataIn\fR,
        Tk_PhotoImageBlock *\fIblockPtr\fR);
.CE
The \fIinterp\fR argument is the interpreter in which the command was

.SS STRINGWRITEPROC
.PP
\fIformatPtr->stringWriteProc\fR provides the address of a procedure
for Tk to call to translate image data from a photo image into a
string.
\fIformatPtr->stringWriteProc\fR must match the following prototype:
.CS
typedef int \fBTk_ImageStringWriteProc\fR(
        Tcl_Interp *\fIinterp\fR,
        Tcl_Obj *\fIformat\fR,
        Tcl_Obj *\fImetadataIn\fR,
        Tk_PhotoImageBlock *\fIblockPtr\fR);
.CE
The \fIinterp\fR argument is the interpreter in which the command was
invoked to convert the image; it should be used for reporting errors.

.PP
Image formats contain a description of the image bitmap and may
contain additional information like image resolution or comments.
Image metadata may be read from image files and passed to the script
level by including dictionary keys into the metadata property of the
image. Image metadata may be written to image data on file write or
image data output.
.PP
.PP
.SS "METADATA KEYS"
.PP
The metadata may contain any key.
A driver will handle only a set of dictionary keys documented in the
documentation. See the photo image manual page for currently defined
keys for the system drivers.
.PP
The following rules may give guidance to name metadata keys:
.RS
Abreviation are in upper case
.RE
.RS
Words are in US English in small case (except proper nouns)
.RE
.RS
Vertical DPI is expressed as DPI/aspect. The reason is, that some
image formats may feature aspect and no resolution value.
.RE
.SS "METADATA INPUT"
.PP
Each driver function gets a Tcl object pointer \fBmetadataIn\fR as
parameter. This parameter serves to input a metadata dict to the
driver function.
It may be NULL to flag that the metadata dict is empty.
.PP
A typical driver code snipped to check for a metadata key is:
.CS
if (NULL != metadataIn) {
    Tcl_Obj *itemData;
    Tcl_DictObjGet(interp, metadataIn, Tcl_NewStringObj("Comment",-1), &itemData));



.CE
.PP
The \-metadata command option data of the following commands is passed
to the driver: \fBimage create\fR, \fBconfigure\fR, \fBput\fR,
\fBread\fR, \fBdata\fR and \fBwrite\fR.
If no \-metadata command option available or not given, the metadata
property of the image is passed to the driver using the following
commands: \fBcget\fR, \fBconfigure\fR, \fBdata\fR and \fBwrite\fR.
.PP
Note that setting the \-metadata property of an image using
\fBconfigure\fR without any other option does not invoke any driver
function.
.PP
The metadata dictionary is not suited to pass options to the driver
related to the bitmap representation, as the image bitmap is not
recreated on a metadata change. The format string should be used for
this purpose.
.PP
.SS "METADATA OUTPUT"
.PP
The image match and read driver functions may set keys in a prepared
matadata dict to return them.
Those functions get a Tcl object pointer \fBmetadataOut\fR as
parameter.
metadataOut may be NULL to indicate, that no metadata return is
attended(\fBput\fR, \fBread\fR subcommands).
\fBmetadataOut\fR is initialized to an empty unshared dict object if
metadata return is attended (\fBimage create\fR command, \fBconfigure\fR
subcommand). The driver may set dict keys in this object to return
metadata.
If a match function succeeds, the metadataOut pointer is passed to the
corresponding read function.
.PP
A sample driver code snippet is:
.CS
if (NULL != metadataOut) {
    Tcl_DictObjPut(NULL, metadataOut, Tcl_NewStringObj("XMP",-1), Tcl_NewStringObj(xmpMetadata);


.CE
.PP
The metadata keys returned by the driver are merged into the present
metadata property of the image or into the metadata dict given by the
\fB\-metadata\fR command line option.
At the script level, the command \fBimage create\fR and the
\fBconfigure\fR method may return metadata from the driver.

Structure that defines the new file format.
.BE
.SS DESCRIPTION
A driver using the version 2 interface invokes \fBTk_CreatePhotoImageFormat\fR
for driver registration. The Tk_PhotoImageFormat structure
contains the following fields:
.CS
typedef struct Tk_PhotoImageFormat {
    const char *\fIname\fR;
    Tk_ImageFileMatchProc *\fIfileMatchProc\fR;
    Tk_ImageStringMatchProc *\fIstringMatchProc\fR;
    Tk_ImageFileReadProc *\fIfileReadProc\fR;
    Tk_ImageStringReadProc *\fIstringReadProc\fR;
    Tk_ImageFileWriteProc *\fIfileWriteProc\fR;
    Tk_ImageStringWriteProc *\fIstringWriteProc\fR;

\fIformatPtr->stringWriteProc\fR must match the following prototype:
.CS
typedef int \fBTk_ImageStringWriteProc\fR(
        Tcl_Interp *\fIinterp\fR,
        Tcl_Obj *\fIformat\fR,
        Tk_PhotoImageBlock *\fIblockPtr\fR);
.CE
.PP
.SH "LEGACY INTERFACE SUPPORT"
.PP
In Tk 8.2 and earlier, the definition of all the function pointer
types stored in fields of a \fBTk_PhotoImageFormat\fR struct were
incompatibly different.  Legacy programs and libraries dating from
those days may still contain code that defines extended Tk photo image
formats using the old interface.  The Tk header file will still support
this legacy interface if the code is compiled with the
macro \fBUSE_OLD_IMAGE\fR defined.  Alternatively, the legacy interfaces
are used if the first character of \fIformatPtr->name\fR is an
uppercase ASCII character (\fBA\fR-\fBZ\fR), and explicit casts
are used to forgive the type mismatch.  For example,
.CS
static Tk_PhotoImageFormat myFormat = {
    "MyFormat",
    (Tk_ImageFileMatchProc *) FileMatch,
    NULL,
    (Tk_ImageFileReadProc *) FileRead,
    NULL,
    NULL,
    NULL
};
.CE
would define a minimal \fBTk_PhotoImageFormat\fR that operates provide
only file reading capability, where \fBFileMatch\fR and \fBFileRead\fR
are written according to the legacy interfaces of Tk 8.2 or earlier.
.PP
Any stub-enabled extension providing an extended photo image format
via the legacy interface enabled by the \fBUSE_OLD_IMAGE\fR macro
that is compiled against Tk 8.5 headers and linked against the
Tk 8.5 stub library will produce a file that can be loaded only
into interps with Tk 8.5 or later; that is, the normal stub-compatibility
rules.  If a developer needs to generate from such code a file
that is loadable into interps with Tk 8.4 or earlier, they must
use Tk 8.4 headers and stub libraries to do so.
.PP
Any new code written today should not make use of the legacy
interfaces.  Expect their support to go away in Tk 9.
.SH "SEE ALSO"
Tk_FindPhoto, Tk_PhotoPutBlock
.SH KEYWORDS
photo image, image file

.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_CreateSelHandler\fR(\fItkwin, selection, target, proc, clientData, format\fR)
.sp
\fBTk_DeleteSelHandler\fR(\fItkwin, selection, target\fR)

.SH ARGUMENTS
.AS Tk_SelectionProc clientData
.AP Tk_Window tkwin in
Window for which \fIproc\fR will provide selection information.
.AP Atom selection in
The name of the selection for which \fIproc\fR will provide
selection information.

X Inter-Client Communication Conventions Manual (ICCCM) or
any other form in which an application is willing to present
the selection.  The most common form is STRING.
.PP
\fIProc\fR should have arguments and result that match the
type \fBTk_SelectionProc\fR:
.CS
typedef int \fBTk_SelectionProc\fR(
        void *\fIclientData\fR,
        int \fIoffset\fR,
        char *\fIbuffer\fR,
        int \fImaxBytes\fR);
.CE
The \fIclientData\fR parameter to \fIproc\fR is a copy of the
\fIclientData\fR argument given to \fBTk_CreateSelHandler\fR.
Typically, \fIclientData\fR points to a data
structure containing application-specific information that is
needed to retrieve the selection.  \fIOffset\fR specifies an
offset position into the selection, \fIbuffer\fR specifies a

.sp
Tk_Window
\fBTk_CreateWindowFromPath\fR(\fIinterp, tkwin, pathName, topLevScreen\fR)
.sp
\fBTk_DestroyWindow\fR(\fItkwin\fR)
.sp
\fBTk_MakeWindowExist\fR(\fItkwin\fR)

.SH ARGUMENTS
.AS Tcl_Interp *topLevScreen
.AP Tcl_Interp *interp out
Tcl interpreter to use for error reporting.  If no error occurs,
then \fI*interp\fR is not modified.
.AP Tk_Window parent in
Token for the window that is to serve as the logical parent of

.SH NAME
Tk_DeleteImage \- Destroy an image.
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_DeleteImage\fR(\fIinterp, name\fR)

.SH ARGUMENTS
.AS Tcl_Interp *interp
.AP Tcl_Interp *interp in
Interpreter for which the image was created.
.AP "const char" *name in
Name of the image.
.BE

.BS
.SH NAME
Tk_DrawFocusHighlight \- draw the traversal highlight ring for a widget
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_DrawFocusHighlight(\fItkwin, gc, width, drawable\fB)\fR

.SH ARGUMENTS
.AS "Tcl_Interp" *joinPtr
.AP Tk_Window tkwin in
Window for which the highlight is being drawn.  Used to retrieve
the window's dimensions, among other things.
.AP GC gc in
Graphics context to use for drawing the highlight.

\fBTk_CreateEventHandler\fR(\fItkwin, mask, proc, clientData\fR)
.sp
\fBTk_DeleteEventHandler\fR(\fItkwin, mask, proc, clientData\fR)
.sp
\fBTk_GetButtonMask\fR(\fIbutton\fR)
.sp
\fBTk_SendVirtualEvent\fR(\fItkwin, eventName, detail\fR)

.SH ARGUMENTS
.AS "unsigned long" clientData
.AP unsigned button in
Button number.
.AP "const char" *eventName in
The name of the virtual event.
.AP Tcl_Obj *detail in

int
\fBTk_PhotoPutZoomedBlock\fR(\fIinterp, handle, blockPtr, x, y, width, height,\
zoomX, zoomY, subsampleX, subsampleY, compRule\fR)
.sp
int
\fBTk_PhotoGetImage\fR(\fIhandle, blockPtr\fR)
.sp
void
\fBTk_PhotoBlank\fR(\fIhandle\fR)
.sp
int
\fBTk_PhotoExpand\fR(\fIinterp, handle, width, height\fR)
.sp
void
\fBTk_PhotoGetSize\fR(\fIhandle, widthPtr, heightPtr\fR)
.sp
int
\fBTk_PhotoSetSize\fR(\fIinterp. handle, width, height\fR)

.SH ARGUMENTS
.AS Tk_PhotoImageBlock window_path
.AP Tcl_Interp *interp in
Interpreter in which image was created and in which error reporting is
to be done.
.AP "const char" *imageName in
Name of the photo image.

Tk_FontId, Tk_GetFontMetrics, Tk_PostscriptFontName \- accessor functions for
fonts
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Font
\fBTk_FontId(\fItkfont\fB)\fR
.sp
\fBTk_GetFontMetrics(\fItkfont, fmPtr\fB)\fR
.sp
int
\fBTk_PostscriptFontName(\fItkfont, dsPtr\fB)\fR

.SH ARGUMENTS
.AS Tk_FontMetrics *dsPtr
.AP Tk_Font tkfont in
Opaque font token being queried.  Must have been returned by a previous
call to \fBTk_GetFont\fR.
.AP Tk_FontMetrics *fmPtr out
Pointer to structure in which the font metrics for \fItkfont\fR will

Any other font families may not print correctly because the computed
Postscript font name may be incorrect or not exist on the printer.
.SH "DATA STRUCTURES"
.PP
The \fBTk_FontMetrics\fR data structure is used by \fBTk_GetFontMetrics\fR to
return information about a font and is defined as follows:
.CS
typedef struct Tk_FontMetrics {
    int \fIascent\fR;
    int \fIdescent\fR;
    int \fIlinespace\fR;
} \fBTk_FontMetrics\fR;
.CE
.PP
The \fIascent\fR field is the amount in pixels that the tallest

'\"
'\" Copyright (c) 1990 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH Tk_FreeXId 3 4.0 Tk "Tk Library Procedures"
.so man.macros
.BS
.SH NAME
Tk_FreeXId \- make X resource identifier available for reuse
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_FreeXId(\fIdisplay, id\fB)\fR
.SH ARGUMENTS
.AS Display *display out
.AP Display *display in
Display for which \fIid\fR was allocated.
.AP XID id in
Identifier of X resource (window, font, pixmap, cursor, graphics
context, or colormap) that is no longer in use.
.BE
.SH DESCRIPTION
.PP
This function is deprecated, it doesn't do anything since 2008-08-19.
.SH KEYWORDS
resource identifier

\fBTk_GeometryRequest\fR(\fItkwin, reqWidth, reqHeight\fR)
.sp
\fBTk_SetMinimumRequestSize\fR(\fItkwin, minWidth, minHeight\fR)
.sp
\fBTk_SetInternalBorder\fR(\fItkwin, width\fR)
.sp
\fBTk_SetInternalBorderEx\fR(\fItkwin, left, right, top, bottom\fR)

.SH ARGUMENTS
.AS baseHeight clientData
.AP Tk_Window tkwin in
Window for which geometry is being requested.
.AP int reqWidth in
Desired width for \fItkwin\fR, in pixel units.
.AP int reqHeight in
Desired height for \fItkwin\fR, in pixel units.
.AP int minWidth in
Desired minimum requested width for \fItkwin\fR, in pixel units.
.AP int minHeight in
Desired minimum requested height for \fItkwin\fR, in pixel units.
.AP int width in
Space to leave for internal border for \fItkwin\fR, in pixel units.
.AP int left in
Space to leave for left side of internal border for \fItkwin\fR, in pixel units.

.AP int right in
Space to leave for right side of internal border for \fItkwin\fR, in pixel units.

.AP int top in
Space to leave for top side of internal border for \fItkwin\fR, in pixel units.

.AP int bottom in
Space to leave for bottom side of internal border for \fItkwin\fR, in pixel units.

.BE
.SH DESCRIPTION
.PP
\fBTk_GeometryRequest\fR is called by widget code to indicate its
preference for the dimensions of a particular window.  The arguments
to \fBTk_GeometryRequest\fR are made available to the geometry
manager for the window, which then decides on the actual geometry

.SH NAME
Tk_GetAnchorFromObj, Tk_GetAnchor, Tk_NameOfAnchor \- translate between strings and anchor positions
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_GetAnchorFromObj(\fIinterp, objPtr, anchorPtr\fB)\fR
.sp
int
\fBTk_GetAnchor(\fIinterp, string, anchorPtr\fB)\fR
.sp
const char *
\fBTk_NameOfAnchor(\fIanchor\fB)\fR

.SH ARGUMENTS
.AS "Tk_Anchor" *anchorPtr
.AP Tcl_Interp *interp in
Interpreter to use for error reporting, or NULL.
.AP Tcl_Obj *objPtr in/out
String value contains name of anchor point:
.QW \fBn\fR  ,

.SH NAME
Tk_AllocBitmapFromObj, Tk_GetBitmap, Tk_GetBitmapFromObj, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmapFromObj, Tk_FreeBitmap \- maintain database of single-plane pixmaps
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Pixmap
\fBTk_AllocBitmapFromObj(\fIinterp, tkwin, objPtr\fB)\fR
.sp
Pixmap
\fBTk_GetBitmap(\fIinterp, tkwin, info\fB)\fR
.sp
Pixmap
\fBTk_GetBitmapFromObj(\fItkwin, objPtr\fB)\fR
.sp
int
\fBTk_DefineBitmap(\fIinterp, name, source, width, height\fB)\fR
.sp
const char *
\fBTk_NameOfBitmap(\fIdisplay, bitmap\fB)\fR
.sp
\fBTk_SizeOfBitmap(\fIdisplay, bitmap, widthPtr, heightPtr\fB)\fR
.sp
\fBTk_FreeBitmapFromObj(\fItkwin, objPtr\fB)\fR
.sp
\fBTk_FreeBitmap(\fIdisplay, bitmap\fB)\fR

.SH ARGUMENTS
.AS "unsigned long" *pixelPtr
.AP Tcl_Interp *interp in
Interpreter to use for error reporting; if NULL then no error message
is left after errors.
.AP Tk_Window tkwin in
Token for window in which the bitmap will be used.

\fBTk_AllocBitmapFromObj\fR returns a Pixmap identifier for a bitmap
that matches the description in \fIobjPtr\fR and is suitable for use
in \fItkwin\fR.  It re-uses an existing bitmap, if possible, and
creates a new one otherwise.  \fIObjPtr\fR's value must have one
of the following forms:
.TP 20
\fB@\fIfileName\fR

\fIFileName\fR must be the name of a file containing a bitmap
description in the standard X11 format.
.TP 20
\fIname\fR

\fIName\fR must be the name of a bitmap defined previously with
a call to \fBTk_DefineBitmap\fR.  The following names are pre-defined
by Tk:
.RS
.TP 12
\fBerror\fR
The international
.QW don't
symbol:  a circle with a diagonal line across it.
.TP 12
\fBgray75\fR
75% gray: a checkerboard pattern where three out of four bits are on.
.TP 12
\fBgray50\fR
50% gray: a checkerboard pattern where every other bit is on.
.TP 12
\fBgray25\fR
25% gray: a checkerboard pattern where one out of every four bits is on.
.TP 12
\fBgray12\fR
12.5% gray: a pattern where one-eighth of the bits are on, consisting of
every fourth pixel in every other row.
.TP 12
\fBhourglass\fR
An hourglass symbol.
.TP 12
\fBinfo\fR
A large letter
.QW i .
.TP 12
\fBquesthead\fR
The silhouette of a human head, with a question mark in it.
.TP 12
\fBquestion\fR
A large question-mark.
.TP 12
\fBwarning\fR
A large exclamation point.
.PP
In addition, the following pre-defined names are available only on the
\fBMacintosh\fR platform:
.TP 12
\fBdocument\fR
A generic document.
.TP 12
\fBstationery\fR
Document stationery.
.TP 12
\fBedition\fR
The \fIedition\fR symbol.
.TP 12
\fBapplication\fR
Generic application icon.
.TP 12
\fBaccessory\fR
A desk accessory.
.TP 12
\fBfolder\fR
Generic folder icon.
.TP 12
\fBpfolder\fR
A locked folder.
.TP 12
\fBtrash\fR
A trash can.
.TP 12
\fBfloppy\fR
A floppy disk.
.TP 12
\fBramdisk\fR
A floppy disk with chip.
.TP 12
\fBcdrom\fR
A cd disk icon.
.TP 12
\fBpreferences\fR
A folder with prefs symbol.
.TP 12
\fBquerydoc\fR
A database document icon.
.TP 12
\fBstop\fR
A stop sign.
.TP 12
\fBnote\fR
A face with balloon words.
.TP 12
\fBcaution\fR
A triangle with an exclamation point.
.RE
.LP
Under normal conditions, \fBTk_AllocBitmapFromObj\fR
returns an identifier for the requested bitmap.  If an error
occurs in creating the bitmap, such as when \fIobjPtr\fR refers
to a non-existent file, then \fBNone\fR is returned and an error

have been used in a call to \fBTk_DefineBitmap\fR.
The arguments \fIsource\fR, \fIwidth\fR, and \fIheight\fR
describe the bitmap.
\fBTk_DefineBitmap\fR normally returns \fBTCL_OK\fR; if an error occurs
(e.g. a bitmap named \fInameId\fR has already been defined) then
\fBTCL_ERROR\fR is returned and an error message is left in
interpreter \fIinterp\fR's result.
Note:  \fBTk_DefineBitmap\fR expects the memory pointed to by
\fIsource\fR to be static:  \fBTk_DefineBitmap\fR does not make
a private copy of this memory, but uses the bytes pointed to
by \fIsource\fR later in calls to \fBTk_AllocBitmapFromObj\fR or
\fBTk_GetBitmap\fR.
.PP
Typically \fBTk_DefineBitmap\fR is used by \fB#include\fR-ing a
bitmap file directly into a C program and then referencing

.SH NAME
Tk_GetCapStyle, Tk_NameOfCapStyle \- translate between strings and cap styles
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_GetCapStyle(\fIinterp, string, capPtr\fB)\fR
.sp
const char *
\fBTk_NameOfCapStyle(\fIcap\fB)\fR

.SH ARGUMENTS
.AS "Tcl_Interp" *capPtr
.AP Tcl_Interp *interp in
Interpreter to use for error reporting.
.AP "const char" *string in
String containing name of cap style \- one of
.QW \fBbutt\fR ,

.SH NAME
Tk_GetColormap, Tk_PreserveColormap, Tk_FreeColormap \- allocate and free colormaps
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Colormap
\fBTk_GetColormap(\fIinterp, tkwin, string\fB)\fR
.sp
\fBTk_PreserveColormap(\fIdisplay, colormap\fB)\fR
.sp
\fBTk_FreeColormap(\fIdisplay, colormap\fB)\fR

.SH ARGUMENTS
.AS "Colormap" colormap
.AP Tcl_Interp *interp in
Interpreter to use for error reporting.
.AP Tk_Window tkwin in
Token for window in which colormap will be used.
.AP "const char" *string in

.SH NAME
Tk_AllocFontFromObj, Tk_GetFont, Tk_GetFontFromObj, Tk_NameOfFont, Tk_FontGetDescription, Tk_FreeFontFromObj, Tk_FreeFont \- maintain database of fonts
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Tk_Font
\fBTk_AllocFontFromObj(\fIinterp, tkwin, objPtr\fB)\fR
.sp
Tk_Font
\fBTk_GetFont(\fIinterp, tkwin, string\fB)\fR
.sp
Tk_Font
\fBTk_GetFontFromObj(\fItkwin, objPtr\fB)\fR
.sp
Tcl_Obj *
\fBTk_FontGetDescription(\fItkfont\fB)\fR
.sp
const char *
\fBTk_NameOfFont(\fItkfont\fB)\fR
.sp
Tk_Font
\fBTk_FreeFontFromObj(\fItkwin, objPtr\fB)\fR
.sp
void
\fBTk_FreeFont(\fItkfont\fB)\fR

.SH ARGUMENTS
.AS "const char" *tkfont
.AP "Tcl_Interp" *interp in
Interpreter to use for error reporting.  If \fBNULL\fR, then no error
messages are left after errors.
.AP Tk_Window tkwin in
Token for window in which font will be used.

a database of all fonts they have allocated.  If
the same font is requested multiple times (e.g. by different
windows or for different purposes), then a single Tk_Font will be
shared for all uses.  The underlying resources will be freed automatically
when no-one is using the font anymore.
.PP
The procedure \fBTk_FontGetDescription\fR returns information about the font
description as a Tcl list. One possible result is "{{DejaVu Sans} -16 bold underline}".

.PP
The procedure \fBTk_NameOfFont\fR is roughly the inverse of
\fBTk_GetFont\fR.  Given a \fItkfont\fR that was created by
\fBTk_GetFont\fR (or \fBTk_AllocFontFromObj\fR), the return value is
the \fIstring\fR argument that was
passed to \fBTk_GetFont\fR to create the font.  The string returned by
\fBTk_NameOfFont\fR is only guaranteed to persist until the \fItkfont\fR

.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
GC
\fBTk_GetGC\fR(\fItkwin, valueMask, valuePtr\fR)
.sp
\fBTk_FreeGC(\fIdisplay, gc\fR)

.SH ARGUMENTS
.AS "unsigned long" valueMask
.AP Tk_Window tkwin in
Token for window in which the graphics context will be used.
.AP "unsigned long" valueMask in
Mask of bits (such as \fBGCForeground\fR or \fBGCStipple\fR)
indicating which fields of \fI*valuePtr\fR are valid.

Tk_GetHINSTANCE \- retrieve the global application instance handle
.SH SYNOPSIS
.nf
\fB#include <tkPlatDecls.h>\fR
.sp
HINSTANCE
\fBTk_GetHINSTANCE\fR()

.BE
.SH DESCRIPTION
.PP
\fBTk_GetHINSTANCE\fR returns the Windows application instance handle
for the Tk application.  This function is only available on Windows platforms.
.SH KEYWORDS
identifier, instance

\fB#include <tkPlatDecls.h>\fR
.sp
HWND
\fBTk_GetHWND\fR(\fIwindow\fR)
.sp
Window
\fBTk_AttachHWND\fR(\fItkwin, hwnd\fR)

.SH ARGUMENTS
.AP Window window in
X token for window.
.AP Tk_Window tkwin in
Tk window for window.
.AP HWND hwnd in
Windows HWND for window.

\fBTk_GetImage\fR(\fIinterp, tkwin, name, changeProc, clientData\fR)
.sp
\fBTk_RedrawImage\fR(\fIimage, imageX, imageY, width, height, drawable, drawableX, drawableY\fR)
.sp
\fBTk_SizeOfImage\fR(\fIimage, widthPtr, heightPtr\fR)
.sp
\fBTk_FreeImage\fR(\fIimage\fR)

.SH ARGUMENTS
.AS Tk_ImageChangedProc *changeProc
.AP Tcl_Interp *interp in
Place to leave error message.
.AP Tk_Window tkwin in
Window in which image will be used.
.AP "const char" *name in

.SH NAME
Tk_GetJoinStyle, Tk_NameOfJoinStyle \- translate between strings and join styles
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_GetJoinStyle(\fIinterp, string, joinPtr\fB)\fR
.sp
const char *
\fBTk_NameOfJoinStyle(\fIjoin\fB)\fR

.SH ARGUMENTS
.AS "Tcl_Interp" *joinPtr
.AP Tcl_Interp *interp in
Interpreter to use for error reporting.
.AP "const char" *string in
String containing name of join style \- one of
.QW \fBbevel\fR ,

.SH NAME
Tk_GetJustifyFromObj, Tk_GetJustify, Tk_NameOfJustify \- translate between strings and justification styles
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_GetJustifyFromObj(\fIinterp, objPtr, justifyPtr\fB)\fR
.sp
int
\fBTk_GetJustify(\fIinterp, string, justifyPtr\fB)\fR
.sp
const char *
\fBTk_NameOfJustify(\fIjustify\fB)\fR

.SH ARGUMENTS
.AS "Tk_Justify" *justifyPtr
.AP Tcl_Interp *interp in
Interpreter to use for error reporting, or NULL.
.AP Tcl_Obj *objPtr in/out
String value contains name of justification style \- one of
.QW \fBleft\fR ,

Justification style (one of the values listed below).
.BE
.SH DESCRIPTION
.PP
\fBTk_GetJustifyFromObj\fR places in \fI*justifyPtr\fR the justify value
corresponding to \fIobjPtr\fR's value.
This value will be one of the following:
.TP
\fBTK_JUSTIFY_LEFT\fR
Means that the text on each line should start at the left edge of
the line;  as a result, the right edges of lines may be ragged.
.TP
\fBTK_JUSTIFY_RIGHT\fR
Means that the text on each line should end at the right edge of
the line;  as a result, the left edges of lines may be ragged.
.TP
\fBTK_JUSTIFY_CENTER\fR
Means that the text on each line should be centered;  as a result,
both the left and right edges of lines may be ragged.
.PP
Under normal circumstances the return value is \fBTCL_OK\fR and
\fIinterp\fR is unused.
If \fIobjPtr\fR does not contain a valid justification style
or an abbreviation of one of these names, \fBTCL_ERROR\fR is returned,

Tk_GetOption \- retrieve an option from the option database
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Tk_Uid
\fBTk_GetOption\fR(\fItkwin, name, class\fR)

.SH ARGUMENTS
.AS Tk_Window *class
.AP Tk_Window tkwin in
Token for window.
.AP "const char" *name in
Name of desired option.
.AP "const char" *class in

.SH NAME
Tk_GetPixelsFromObj, Tk_GetPixels, Tk_GetMMFromObj, Tk_GetScreenMM, Tk_GetDoublePixelsFromObj \- translate between strings and screen units
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_GetPixelsFromObj(\fIinterp, tkwin, objPtr, intPtr\fB)\fR
.sp
int
\fBTk_GetDoublePixelsFromObj(\fIinterp, tkwin, objPtr, doublePtr\fB)\fR
.sp
int
\fBTk_GetPixels(\fIinterp, tkwin, string, intPtr\fB)\fR
.sp
int
\fBTk_GetMMFromObj(\fIinterp, tkwin, objPtr, doublePtr\fB)\fR
.sp
int
\fBTk_GetScreenMM(\fIinterp, tkwin, string, doublePtr\fB)\fR

.SH ARGUMENTS
.AS "Tcl_Interp" *joinPtr
.AP Tcl_Interp *interp in
Interpreter to use for error reporting.
.AP Tk_Window tkwin in
Window whose screen geometry determines the conversion between absolute
units and pixels.

the screen (\fIobjPtr\fR or \fIstring\fR) and compute the
corresponding distance either in integer pixels or floating-point millimeters.
In either case,
\fIobjPtr\fR or \fIstring\fR
specifies a screen distance as a
floating-point number followed by one of the following characters
that indicates units:
.TP
<none>
The number specifies a distance in pixels.
.TP
\fBc\fR
The number specifies a distance in centimeters on the screen.
.TP
\fBi\fR
The number specifies a distance in inches on the screen.
.TP
\fBm\fR
The number specifies a distance in millimeters on the screen.
.TP
\fBp\fR
The number specifies a distance in printer's points (1/72 inch)
on the screen.
.PP
\fBTk_GetPixelsFromObj\fR converts the value of \fIobjPtr\fR to the
nearest even number of pixels and stores that value at \fI*intPtr\fR.
It returns \fBTCL_OK\fR under normal circumstances.
If an error occurs (e.g. \fIobjPtr\fR contains a number followed

.SH NAME
Tk_GetPixmap, Tk_FreePixmap \- allocate and free pixmaps
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Pixmap
\fBTk_GetPixmap(\fIdisplay, d, width, height, depth\fB)\fR
.sp
\fBTk_FreePixmap(\fIdisplay, pixmap\fB)\fR

.SH ARGUMENTS
.AS "Drawable" *pixelPtr
.AP Display *display in
X display for the pixmap.
.AP Drawable d in
Pixmap or window where the new pixmap will be used for drawing.
.AP "int" width in

.SH NAME
Tk_GetRootCoords \- Compute root-window coordinates of window
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_GetRootCoords\fR(\fItkwin, xPtr, yPtr\fR)

.SH ARGUMENTS
.AS Tk_Window tkwin
.AP Tk_Window tkwin in
Token for window.
.AP int *xPtr out
Pointer to location in which to store root-window x-coordinate
corresponding to left edge of \fItkwin\fR's border.

.SH NAME
Tk_GetScrollInfoObj, Tk_GetScrollInfo \- parse arguments for scrolling commands
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_GetScrollInfoObj(\fIinterp, objc, objv, fractionPtr, stepsPtr\fB)\fR
.sp
int
\fBTk_GetScrollInfo(\fIinterp, argc, argv, fractionPtr, stepsPtr\fB)\fR

.SH ARGUMENTS
.AS "Tcl_Interp" *fractionPtr
.AP Tcl_Interp *interp in
Interpreter to use for error reporting.
.AP int objc in
Number of Tcl_Obj's in \fIobjv\fR array.
.AP "Tcl_Obj *const *" objv in
Argument objects.  These represent the entire widget command, of
which the first word is typically the widget name and the second
word is typically \fBxview\fR or \fByview\fR.
.AP int argc in
Number of strings in \fIargv\fR array.

Tk_GetSelection \- retrieve the contents of a selection
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_GetSelection\fR(\fIinterp, tkwin, selection, target, proc, clientData\fR)

.SH ARGUMENTS
.AS Tk_GetSelProc clientData
.AP Tcl_Interp *interp in
Interpreter to use for reporting errors.
.AP Tk_Window tkwin in
Window on whose behalf to retrieve the selection (determines
display from which to retrieve).

Tk_GetUid, Tk_Uid \- convert from string to unique identifier
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Tk_Uid
\fBTk_GetUid\fR(\fIstring\fR)

.SH ARGUMENTS
.AP char *string in
String for which the corresponding unique identifier is
desired.
.BE
.SH DESCRIPTION
.PP

.BS
.SH NAME
Tk_GetVRootGeometry \- Get location and size of virtual root for window
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_GetVRootGeometry(\fItkwin, xPtr, yPtr, widthPtr, heightPtr\fB)\fR

.SH ARGUMENTS
.AS Tk_Window heightPtr
.AP Tk_Window tkwin in
Token for window whose virtual root is to be queried.
.AP int xPtr out
Points to word in which to store x-offset of virtual root.
.AP int yPtr out

.SH NAME
Tk_GetVisual \- translate from string to visual
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Visual *
\fBTk_GetVisual(\fIinterp, tkwin, string, depthPtr, colormapPtr\fB)\fR

.SH ARGUMENTS
.AS "Tcl_Interp" *colormapPtr
.AP Tcl_Interp *interp in
Interpreter to use for error reporting.
.AP Tk_Window tkwin in
Token for window in which the visual will be used.
.AP "const char" *string in

also locates an appropriate colormap for use with the result visual
and stores its X identifier at \fI*colormapPtr\fR.
.PP
The \fIstring\fR argument specifies the desired visual in one
of the following ways:
.TP 15
\fIclass depth\fR

The string consists of a class name followed by an integer depth,
with any amount of white space (including none) in between.
\fIclass\fR selects what sort of visual is desired and must be one of
\fBdirectcolor\fR, \fBgrayscale\fR, \fBgreyscale\fR, \fBpseudocolor\fR,
\fBstaticcolor\fR, \fBstaticgray\fR, \fBstaticgrey\fR, or
\fBtruecolor\fR, or a unique abbreviation.
\fIdepth\fR specifies how many bits per pixel are needed for the
visual.
If possible, \fBTk_GetVisual\fR will return a visual with this depth;
if there is no visual of the desired depth then \fBTk_GetVisual\fR
looks first for a visual with greater depth, then one with less
depth.
.TP 15
\fBdefault\fR

Use the default visual for \fItkwin\fR's screen.
.TP 15
\fIpathName\fR

Use the visual for the window given by \fIpathName\fR.
\fIpathName\fR must be the name of a window on the same screen
as \fItkwin\fR.
.TP 15
\fInumber\fR

Use the visual whose X identifier is \fInumber\fR.
.TP 15
\fBbest\fR ?\fIdepth\fR?

Choose the
.QW "best possible"
visual, using the following rules, in decreasing order of priority:
.RS
.IP (a)
a visual that has exactly the desired depth is best, followed
by a visual with greater depth than requested (but as little extra

.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_Grab\fR(\fIinterp, tkwin, grabGlobal\fR)
.sp
void
\fBTk_Ungrab\fR(\fItkwin\fR)

.SH ARGUMENTS
.AP Tcl_Interp *interp in
Interpreter to use for error reporting
.AP Tk_Window tkwin in
Window on whose behalf the pointer is to be grabbed or released
.AP int grabGlobal in
Boolean indicating whether the grab is global or application local

Tk_HWNDToWindow \- Find Tk's window information for a Windows window
.SH SYNOPSIS
.nf
\fB#include <tkPlatDecls.h>\fR
.sp
Tk_Window
\fBTk_HWNDToWindow\fR(\fIhwnd\fR)

.SH ARGUMENTS
.AP HWND hwnd in
Windows handle for the window.
.BE
.SH DESCRIPTION
.PP
Given a Windows HWND window identifier, this procedure returns the

.SH NAME
Tk_HandleEvent \- invoke event handlers for window system events
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_HandleEvent\fR(\fIeventPtr\fR)

.SH ARGUMENTS
.AS XEvent *eventPtr
.AP XEvent *eventPtr in
Pointer to X event to dispatch to relevant handler(s). It is important
that all unused fields of the structure be set to zero.
.BE
.SH DESCRIPTION

Tk_IdToWindow \- Find Tk's window information for an X window
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Tk_Window
\fBTk_IdToWindow\fR(\fIdisplay, window\fR)

.SH ARGUMENTS
.AS Tk_Window display
.AP Display *display in
X display containing the window.
.AP Window window in
X id for window.
.BE

.SH NAME
Tk_ImageChanged \- notify widgets that image needs to be redrawn
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_ImageChanged\fR(\fImodel, x, y, width, height, imageWidth, imageHeight\fR)

.SH ARGUMENTS
.AS Tk_ImageModel imageHeight
.AP Tk_ImageModel model in
Token for image, which was passed to image's \fIcreateProc\fR when
the image was created.
.AP int x in
X-coordinate of upper-left corner of region that needs redisplay (measured

.SH NAME
Tk_GetUserInactiveTime, Tk_ResetUserInactiveTime \- discover user inactivity time
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
long
\fBTk_GetUserInactiveTime(\fIdisplay\fB)\fR
.sp
\fBTk_ResetUserInactiveTime(\fIdisplay\fB)\fR

.SH ARGUMENTS
.AS Display *display
.AP Display *display in
The display on which the user inactivity timer is to be queried or
reset.
.BE
.SH DESCRIPTION

.SH NAME
Tk_InternAtom, Tk_GetAtomName \- manage cache of X atoms
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Atom
\fBTk_InternAtom(\fItkwin, name\fR)
.sp
const char *
\fBTk_GetAtomName(\fItkwin, atom\fR)

.SH ARGUMENTS
.AS Tk_Window parent
.AP Tk_Window tkwin in
Token for window.  Used to map atom or name relative to a particular display.
.AP "const char" *name in
String name for which atom is desired.
.AP Atom atom in

.SH NAME
Tk_MainLoop \- loop for events until all windows are deleted
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_MainLoop\fR()

.BE
.SH DESCRIPTION
.PP
\fBTk_MainLoop\fR is a procedure that loops repeatedly calling
\fBTcl_DoOneEvent\fR.  It returns only when there are no applications
left in this process (i.e. no main windows exist anymore).  Most
windowing applications will call \fBTk_MainLoop\fR after

.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Tk_Window
\fBTk_MainWindow\fR(\fIinterp\fR)
.sp
void
\fBTk_SetMainMenubar\fR(\fIinterp, tkwin, menuName\fR)
.sp
void
\fBTk_SetWindowMenubar\fR(\fIinterp, tkwin, oldMenuName, menuName\fR)
.sp
int
\fBTk_GetNumMainWindows\fR()

.SH ARGUMENTS
.AS Tcl_Interp *pathName
.AP Tcl_Interp *interp in/out
Interpreter associated with the application.
.AP Tk_Window tkwin in
Token for main window.
.AP const char *menuName in

associated with \fIinterp\fR then \fBTk_MainWindow\fR returns NULL and
leaves an error message in interpreter \fIinterp\fR's result.
.PP
\fBTk_GetNumMainWindows\fR returns a count of the number of main
windows currently open in the current thread.
\fBTk_SetMainMenubar\fR
Called when a toplevel widget is brought to front. On the Macintosh,
sets up the menubar that goes accross the top of the main monitor. On
other platforms, nothing is necessary.
\fBTk_SetWindowMenubar\fR associates a menu with a window.
The old menu clones for the menubar are thrown away, and a handler is
set up to allocate the new ones.
.SH KEYWORDS
application, main window

.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_MaintainGeometry\fR(\fIwindow, container, x, y, width, height\fR)
.sp
\fBTk_UnmaintainGeometry\fR(\fIwindow, container\fR)

.SH ARGUMENTS
.AS Tk_Window container
.AP Tk_Window window in
Window whose geometry is to be controlled.
.AP Tk_Window container in
Window relative to which \fIwindow\fR's geometry will be controlled.
.AP int x in

.SH NAME
Tk_ManageGeometry \- arrange to handle geometry requests for a window
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_ManageGeometry\fR(\fItkwin, mgrPtr, clientData\fR)

.SH ARGUMENTS
.AS Tk_GeometryProc clientData
.AP Tk_Window tkwin in
Token for window to be managed.
.AP "const Tk_GeomMgr" *mgrPtr in
Pointer to data structure containing information about the
geometry manager, or NULL to indicate that \fItkwin\fR's geometry

.nf
\fB#include <tk.h>\fR
.sp
Tk_Window
\fBTk_MapWindow\fR(\fItkwin\fR)
.sp
\fBTk_UnmapWindow\fR(\fItkwin\fR)

.SH ARGUMENTS
.AS Tk_Window parent
.AP Tk_Window tkwin in
Token for window.
.BE
.SH DESCRIPTION
.PP

.SH NAME
Tk_MeasureChars, Tk_TextWidth, Tk_DrawChars, Tk_UnderlineChars \- routines to measure and display simple single-line strings.
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_MeasureChars(\fItkfont, string, numBytes, maxPixels, flags, lengthPtr\fB)\fR
.sp
int
\fBTk_TextWidth(\fItkfont, string, numBytes\fB)\fR
.sp
\fBTk_DrawChars(\fIdisplay, drawable, gc, tkfont, string, numBytes, x, y\fB)\fR
.sp
\fBTk_UnderlineChars(\fIdisplay, drawable, gc, tkfont, string, x, y, firstByte, lastByte\fB)\fR
.sp
.SH ARGUMENTS
.AS "const char" firstChar
.AP Tk_Font tkfont in
Token for font in which text is to be drawn or measured.  Must have been
returned by a previous call to \fBTk_GetFont\fR.
.AP "const char" *string in
Text to be measured or displayed.  Need not be null terminated.  Any
non-printing meta-characters in the string (such as tabs, newlines, and
other control characters) will be measured or displayed in a
platform-dependent manner.
.AP int numBytes in
The maximum number of bytes to consider when measuring or drawing
\fIstring\fR.  Must be greater than or equal to 0.
.AP int maxPixels in
If \fImaxPixels\fR is >= 0, it specifies the longest permissible
line length in pixels.  Characters from \fIstring\fR are processed only
until this many pixels have been covered.  If \fImaxPixels\fR is < 0, then
the line length is unbounded and the \fIflags\fR argument is ignored.
.AP int flags in
Various flag bits OR-ed together: \fBTK_PARTIAL_OK\fR means include a character
as long as any part of it fits in the length given by \fImaxPixels\fR;
otherwise, a character must fit completely to be considered.
\fBTK_WHOLE_WORDS\fR means stop on a word boundary, if possible.  If
\fBTK_AT_LEAST_ONE\fR is set, it means return at least one character even if no
characters could fit in the length given by \fImaxPixels\fR.  If
\fBTK_AT_LEAST_ONE\fR is set and \fBTK_WHOLE_WORDS\fR is also set, it means that if
not even one word fits on the line, return the first few letters of the
word that did fit; if not even one letter of the word fit, then the first
letter will still be returned.
.AP int *lengthPtr out
Filled with the number of pixels occupied by the number of characters
returned as the result of \fBTk_MeasureChars\fR.
.AP Display *display in
Display on which to draw.

.BS
.SH NAME
Tk_MoveToplevelWindow \- Adjust the position of a top-level window
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_MoveToplevelWindow(\fItkwin, x, y\fB)\fR

.SH ARGUMENTS
.AS Tk_Window tkwin
.AP Tk_Window tkwin in
Token for top-level window to move.
.AP int x in
New x-coordinate for the top-left pixel of \fItkwin\fR's border, or the
top-left pixel of the decorative border supplied for \fItkwin\fR by the

\fBTk_Name\fR(\fItkwin\fR)
.sp
char *
\fBTk_PathName\fR(\fItkwin\fR)
.sp
Tk_Window
\fBTk_NameToWindow\fR(\fIinterp, pathName, tkwin\fR)

.SH ARGUMENTS
.AS Tcl_Interp *pathName
.AP Tk_Window tkwin in
Token for window.
.AP Tcl_Interp *interp out
Interpreter to use for error reporting.
.AP "const char" *pathName in

Tk_NameOfImage \- Return name of image.
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
const char *
\fBTk_NameOfImage\fR(\fIimageModel\fR)

.SH ARGUMENTS
.AS Tk_ImageModel imageModel
.AP Tk_ImageModel imageModel in
Token for image, which was passed to image manager's \fIcreateProc\fR when
the image was created.
.BE
.SH DESCRIPTION

.SH NAME
Tk_OwnSelection \- make a window the owner of the primary selection
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_OwnSelection\fR(\fItkwin, selection, proc, clientData\fR)

.SH ARGUMENTS
.AS Tk_LostSelProc clientData
.AP Tk_Window tkwin in
Window that is to become new selection owner.
.AP Atom selection in
The name of the selection to be owned, such as XA_PRIMARY.
.AP Tk_LostSelProc *proc in

Tk_ParseArgv \- process command-line options
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_ParseArgv\fR(\fIinterp, tkwin, argcPtr, argv, argTable, flags\fR)

.SH ARGUMENTS
.AS Tk_ArgvInfo *argTable
.AP Tcl_Interp *interp in
Interpreter to use for returning error messages.
.AP Tk_Window tkwin in
Window to use when arguments specify Tk options.  If NULL, then
no Tk options will be processed.

.QW "the matching argument"
in the descriptions below.  As part of the processing,
\fBTk_ParseArgv\fR may also use the next argument in \fIargv\fR
after the matching argument, which is called
.QW "the following argument" .
The legal values for \fItype\fR, and the processing
that they cause, are as follows:
.TP
\fBTK_ARGV_END\fR
Marks the end of the table.  The last entry in \fIargTable\fR
must have this type;  all of its other fields are ignored and it
will never match any arguments.
.TP
\fBTK_ARGV_CONSTANT\fR
\fISrc\fR is treated as an integer and \fIdst\fR is treated
as a pointer to an integer.  \fISrc\fR is stored at \fI*dst\fR.
The matching argument is discarded.
.TP
\fBTK_ARGV_INT\fR
The following argument must contain an
integer string in the format accepted by \fBstrtol\fR (e.g.
.QW 0
and
.QW 0x
prefixes may be used to specify octal or hexadecimal
numbers, respectively).  \fIDst\fR is treated as a pointer to an
integer;  the following argument is converted to an integer value
and stored at \fI*dst\fR.  \fISrc\fR is ignored.  The matching
and following arguments are discarded from \fIargv\fR.
.TP
\fBTK_ARGV_FLOAT\fR
The following argument must contain a floating-point number in
the format accepted by \fBstrtol\fR.
\fIDst\fR is treated as the address of a double-precision
floating point value;  the following argument is converted to a
double-precision value and stored at \fI*dst\fR.  The matching
and following arguments are discarded from \fIargv\fR.
.TP
\fBTK_ARGV_STRING\fR
In this form, \fIdst\fR is treated as a pointer to a (char *);
\fBTk_ParseArgv\fR stores at \fI*dst\fR a pointer to the following
argument, and discards the matching and following arguments from
\fIargv\fR.  \fISrc\fR is ignored.
.TP
\fBTK_ARGV_UID\fR
This form is similar to \fBTK_ARGV_STRING\fR, except that the argument
is turned into a Tk_Uid by calling \fBTk_GetUid\fR.
\fIDst\fR is treated as a pointer to a
Tk_Uid; \fBTk_ParseArgv\fR stores at \fI*dst\fR the Tk_Uid
corresponding to the following
argument, and discards the matching and following arguments from
\fIargv\fR.  \fISrc\fR is ignored.
.TP
\fBTK_ARGV_CONST_OPTION\fR
This form causes a Tk option to be set (as if the \fBoption\fR
command had been invoked).  The \fIsrc\fR field is treated as a
pointer to a string giving the value of an option, and \fIdst\fR
is treated as a pointer to the name of the option.  The matching
argument is discarded.  If \fItkwin\fR is NULL, then argument
specifiers of this type are ignored (as if they did not exist).
.TP
\fBTK_ARGV_OPTION_VALUE\fR
This form is similar to \fBTK_ARGV_CONST_OPTION\fR, except that the
value of the option is taken from the following argument instead
of from \fIsrc\fR.  \fIDst\fR is used as the name of the option.
\fISrc\fR is ignored.  The matching and following arguments
are discarded.  If \fItkwin\fR is NULL, then argument
specifiers of this type are ignored (as if they did not exist).
.TP
\fBTK_ARGV_OPTION_NAME_VALUE\fR
In this case the following argument is taken as the name of a Tk
option and the argument after that is taken as the value for that
option.  Both \fIsrc\fR and \fIdst\fR are ignored.  All three
arguments are discarded from \fIargv\fR.  If \fItkwin\fR is NULL,
then argument
specifiers of this type are ignored (as if they did not exist).
.TP
\fBTK_ARGV_HELP\fR
When this kind of option is encountered, \fBTk_ParseArgv\fR uses the
\fIhelp\fR fields of \fIargTable\fR to format a message describing
all the valid arguments.  The message is placed in interpreter
\fIinterp\fR's result
and \fBTk_ParseArgv\fR returns \fBTCL_ERROR\fR.  When this happens, the
caller normally prints the help message and aborts.  If the \fIkey\fR
field of a \fBTK_ARGV_HELP\fR specifier is NULL, then the specifier will
never match any arguments;  in this case the specifier simply provides
extra documentation, which will be included when some other
\fBTK_ARGV_HELP\fR entry causes help information to be returned.
.TP
\fBTK_ARGV_REST\fR
This option is used by programs or commands that allow the last
several of their options to be the name and/or options for some
other program.  If a \fBTK_ARGV_REST\fR argument is found, then
\fBTk_ParseArgv\fR does not process any
of the remaining arguments;  it returns them all at
the beginning of \fIargv\fR (along with any other unprocessed arguments).
In addition, \fBTk_ParseArgv\fR treats \fIdst\fR as the address of an
integer value, and stores at \fI*dst\fR the index of the first of the
\fBTK_ARGV_REST\fR options in the returned \fIargv\fR.  This allows the
program to distinguish the \fBTK_ARGV_REST\fR options from other
unprocessed options that preceded the \fBTK_ARGV_REST\fR.
.TP
\fBTK_ARGV_FUNC\fR
For this kind of argument, \fIsrc\fR is treated as the address of
a procedure, which is invoked to process the following argument.
The procedure should have the following structure:
.RS
.CS
int
\fIfunc\fR(\fIdst\fR, \fIkey\fR, \fInextArg\fR)

(or NULL if there are not any more arguments left in \fIargv\fR).
If \fIfunc\fR uses \fInextArg\fR (so that
\fBTk_ParseArgv\fR should discard it), then it should return 1.  Otherwise it
should return 0 and \fBTkParseArgv\fR will process the following
argument in the normal fashion.  In either event the matching argument
is discarded.
.RE
.TP
\fBTK_ARGV_GENFUNC\fR
This form provides a more general procedural escape.  It treats
\fIsrc\fR as the address of a procedure, and passes that procedure
all of the remaining arguments.  The procedure should have the following
form:
.RS
.CS
int

\fBTk_ParseArgv\fR will process them.  If \fIgenfunc\fR encounters
an error then it should leave an error message in interpreter
\fIinterp\fR's result,
in the usual Tcl fashion, and return \-1;  when this happens
\fBTk_ParseArgv\fR will abort its processing and return \fBTCL_ERROR\fR.
.RE
.SS "FLAGS"
.TP
\fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR
\fBTk_ParseArgv\fR normally treats \fIargv[0]\fR as a program
or command name, and returns it to the caller just as if it
had not matched \fIargTable\fR.  If this flag is given, then
\fIargv[0]\fR is not given special treatment.
.TP
\fBTK_ARGV_NO_ABBREV\fR
Normally, \fBTk_ParseArgv\fR accepts unique abbreviations for
\fIkey\fR values in \fIargTable\fR.  If this flag is given then
only exact matches will be acceptable.
.TP
\fBTK_ARGV_NO_LEFTOVERS\fR
Normally, \fBTk_ParseArgv\fR returns unrecognized arguments to the
caller.  If this bit is set in \fIflags\fR then \fBTk_ParseArgv\fR
will return an error if it encounters any argument that does not
match \fIargTable\fR.  The only exception to this rule is \fIargv[0]\fR,
which will be returned to the caller with no errors as
long as \fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR is not specified.
.TP
\fBTK_ARGV_NO_DEFAULTS\fR
Normally, \fBTk_ParseArgv\fR searches an internal table of
standard argument specifiers in addition to \fIargTable\fR.  If
this bit is set in \fIflags\fR, then \fBTk_ParseArgv\fR will
use only \fIargTable\fR and not its default table.
.SH EXAMPLE
.PP
Here is an example definition of an \fIargTable\fR and

char *fileName = defaultFileName;
Boolean exec = FALSE;

/*
 * Define option descriptions.
 */
Tk_ArgvInfo argTable[] = {
    {"\-X", TK_ARGV_CONSTANT, (char *) 1, &debugFlag,
        "Turn on debugging printfs"},
    {"\-N", TK_ARGV_INT, NULL, &numReps,
        "Number of repetitions"},
    {"\-of", TK_ARGV_STRING, NULL, &fileName,
        "Name of file for output"},
    {"x", TK_ARGV_REST, NULL, &exec,
        "File to exec, followed by any arguments (must be last argument)."},
    {NULL, TK_ARGV_END, NULL, NULL,
        NULL}
};

main(argc, argv)
    int argc;
    char *argv[];
{
    \&...

    if (Tk_ParseArgv(interp, tkwin, &argc, argv, argTable, 0) != TCL_OK) {
        fprintf(stderr, "%s\en", Tcl_GetString(Tcl_GetObjResult(interp)));
        exit(1);
    }

    /*
     * Remainder of the program.
     */
}
.CE
.PP
Note that default values can be assigned to variables named in
\fIargTable\fR:  the variables will only be overwritten if the
particular arguments are present in \fIargv\fR.
Here are some example command lines and their effects.
.CS
prog \-N 200 infile        # just sets the numReps variable to 200
prog \-of out200 infile    # sets fileName to reference "out200"
prog \-XN 10 infile        # sets the debug flag, also sets numReps
.CE
In all of the above examples, \fIargc\fR will be set by \fBTk_ParseArgv\fR to 2,
\fIargv\fR[0] will be
.QW prog ,
\fIargv\fR[1] will be
.QW infile ,
and \fIargv\fR[2] will be NULL.
.SH KEYWORDS
arguments, command line, options

.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_CollapseMotionEvents\fR(\fIdisplay, collapse\fR)
.sp
\fBTk_QueueWindowEvent\fR(\fIeventPtr, position\fR)

.SH ARGUMENTS
.AS Tcl_QueuePosition position
.AP Display *display  in
Display for which to control motion event collapsing.
.AP int collapse in
Indicates whether motion events should be collapsed or not.
.AP XEvent *eventPtr  in

Tk_RestackWindow \- Change a window's position in the stacking order
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_RestackWindow\fR(\fItkwin, aboveBelow, other\fR)

.SH ARGUMENTS
.AS Tk_Window aboveBelow
.AP Tk_Window tkwin in
Token for window to restack.
.AP int aboveBelow in
Indicates new position of \fItkwin\fR relative to \fIother\fR;
must be \fBAbove\fR or \fBBelow\fR.

Tk_RestrictEvents \- filter and selectively delay X events
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Tk_RestrictProc *
\fBTk_RestrictEvents\fR(\fIproc, arg, prevArgPtr\fR)

.SH ARGUMENTS
.AS Tk_RestrictProc **prevArgPtr
.AP Tk_RestrictProc *proc in
Predicate procedure to call to filter incoming X events.
NULL means do not restrict events at all.
.AP void *arg in
Arbitrary argument to pass to \fIproc\fR.

Tk_SetAppName \- Set the name of an application for 'send' commands
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
const char *
\fBTk_SetAppName\fR(\fItkwin, name\fR)

.SH ARGUMENTS
.AS Tk_Window parent
.AP Tk_Window tkwin in
Token for window in application.  Used only to select a particular
application.
.AP "const char" *name in
Name under which to register the application.

Tk_SetCaretPos \- set the display caret location
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_SetCaretPos\fR(\fItkwin, x, y, height\fR)

.SH ARGUMENTS
.AP Tk_Window tkwin in
Token for window.
.AP int x in
Window-relative x coordinate.
.AP int y in
Window-relative y coordinate.

.nf
\fB#include <tk.h>\fR
.sp
\fBTk_SetClass\fR(\fItkwin, class\fR)
.sp
Tk_Uid
\fBTk_Class\fR(\fItkwin\fR)

.SH ARGUMENTS
.AS Tk_Window parent
.AP Tk_Window tkwin in
Token for window.
.AP char *class in
New class name for window.
.BE

.SH NAME
Tk_SetClassProcs \- register widget specific procedures
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_SetClassProcs\fR(\fItkwin, procs, instanceData\fR)

.SH ARGUMENTS
.AS Tk_ClassProc instanceData
.AP Tk_Window tkwin in
Token for window to modify.
.AP "const Tk_ClassProcs" *procs in
Pointer to data structure containing widget specific procedures.
The data structure pointed to by \fIprocs\fR must be static:
Tk keeps a reference to it as long as the window exists.
.AP void *instanceData in
Arbitrary one-word value to pass to widget callbacks.
.BE
.SH DESCRIPTION
.PP
\fBTk_SetClassProcs\fR is called to register a set of procedures that
are used as callbacks in different places.
.PP
The structure pointed to by \fIprocs\fR contains the following:
.CS
typedef struct Tk_ClassProcs {
    size_t \fIsize\fR;
    Tk_ClassWorldChangedProc *\fIworldChangedProc\fR;
    Tk_ClassCreateProc *\fIcreateProc\fR;
    Tk_ClassModalProc *\fImodalProc\fR;
} \fBTk_ClassProcs\fR;
.CE
The \fIsize\fR field is used to simplify future expansion of the

.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_SetGrid\fR(\fItkwin, reqWidth, reqHeight, widthInc, heightInc\fR)
.sp
\fBTk_UnsetGrid\fR(\fItkwin\fR)

.SH ARGUMENTS
.AS Tk_Window heightInc
.AP Tk_Window tkwin in
Token for window.
.AP int reqWidth in
Width in grid units that corresponds to the pixel dimension \fItkwin\fR
has requested via \fBTk_GeometryRequest\fR.

fields of this record are modified by procedures such as \fBTk_SetOptions\fR
and read by procedures such as \fBTk_GetOptionValue\fR.
.AP Tk_Window tkwin in
For options such as \fBTK_OPTION_COLOR\fR, this argument indicates
the window in which the option will be used.  If \fIoptionTable\fR uses
no window-dependent options, then a NULL value may be supplied for
this argument.
.AP int objc in
Number of values in \fIobjv\fR.
.AP Tcl_Obj "*const *objv" in
Command-line arguments for setting configuring options.
.AP Tk_SavedOptions *savePtr out
If not NULL, the structure pointed to by this argument is filled
in with the old values of any options that were modified and old
values are restored automatically if an error occurs in \fBTk_SetOptions\fR.

.SH "CUSTOM OPTION TYPES"
.PP
Applications can extend the built-in configuration types with
additional configuration types by writing procedures to parse, print,
free, and restore saved copies of the type and creating a structure
pointing to those procedures:
.CS
typedef struct Tk_ObjCustomOption {
    const char *\fIname\fR;
    Tk_CustomOptionSetProc *\fIsetProc\fR;
    Tk_CustomOptionGetProc *\fIgetProc\fR;
    Tk_CustomOptionRestoreProc *\fIrestoreProc\fR;
    Tk_CustomOptionFreeProc *\fIfreeProc\fR;
    void *\fIclientData\fR;
} \fBTk_ObjCustomOption\fR;

Tk_SetWindowVisual \- change visual characteristics of window
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_SetWindowVisual\fR(\fItkwin, visual, depth, colormap\fR)

.SH ARGUMENTS
.AS "Tk_Window int" colormap
.AP Tk_Window tkwin in
Token for window.
.AP Visual *visual in
New visual type to use for \fItkwin\fR.
.AP "int" depth in

The safest thing is to call \fBTk_SetWindowVisual\fR immediately
after calling \fBTk_CreateWindow\fR.
If \fItkwin\fR has already been created before \fBTk_SetWindowVisual\fR
is called then it returns 0 and does not make any changes;  otherwise
it returns 1 to signify that the operation
completed successfully.
.PP
Note:  \fBTk_SetWindowVisual\fR should not be called if you just want
to change a window's colormap without changing its visual or depth;
call \fBTk_SetWindowColormap\fR instead.
.SH KEYWORDS
colormap, depth, visual

Tk_StrictMotif \- Return value of tk_strictMotif variable
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_StrictMotif\fR(\fItkwin\fR)

.SH ARGUMENTS
.AS Tk_Window tkwin
.AP Tk_Window tkwin in
Token for window.
.BE
.SH DESCRIPTION
.PP

.SH NAME
Tk_ComputeTextLayout, Tk_FreeTextLayout, Tk_DrawTextLayout, Tk_UnderlineTextLayout, Tk_PointToChar, Tk_CharBbox, Tk_DistanceToTextLayout, Tk_IntersectTextLayout, Tk_TextLayoutToPostscript \- routines to measure and display single-font, multi-line, justified text.
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Tk_TextLayout
\fBTk_ComputeTextLayout(\fItkfont, string, numChars, wrapLength, justify, flags, widthPtr, heightPtr\fB)\fR
.sp
void
\fBTk_FreeTextLayout(\fIlayout\fB)\fR
.sp
void
\fBTk_DrawTextLayout(\fIdisplay, drawable, gc, layout, x, y, firstChar, lastChar\fB)\fR
.sp
void
\fBTk_UnderlineTextLayout(\fIdisplay, drawable, gc, layout, x, y, underline\fB)\fR
.sp
int
\fBTk_PointToChar(\fIlayout, x, y\fB)\fR
.sp
int
\fBTk_CharBbox(\fIlayout, index, xPtr, yPtr, widthPtr, heightPtr\fB)\fR
.sp
int
\fBTk_DistanceToTextLayout(\fIlayout, x, y\fB)\fR
.sp
int
\fBTk_IntersectTextLayout(\fIlayout, x, y, width, height\fB)\fR
.sp
void
\fBTk_TextLayoutToPostscript(\fIinterp, layout\fB)\fR

.SH ARGUMENTS
.AS Tk_TextLayout "*xPtr, *yPtr"
.AP Tk_Font tkfont in
Font to use when constructing and displaying a text layout.  The
\fItkfont\fR must remain valid for the lifetime of the text layout.  Must
have been returned by a previous call to \fBTk_GetFont\fR.
.AP "const char" *string in

this GC must correspond to the \fItkfont\fR used when constructing the
text layout.
.AP int "x, y" in
Point, in pixels, at which to place the upper-left hand corner of the
text layout when it is being drawn, or the coordinates of a point (with
respect to the upper-left hand corner of the text layout) to check
against the text layout.
.AP int firstChar in
The index of the first character to draw from the given text layout.
The number 0 means to draw from the beginning.
.AP int lastChar in
The index of the last character up to which to draw.  The character
specified by \fIlastChar\fR itself will not be drawn.  A number less
than 0 means to draw all characters in the text layout.
.AP int underline in
Index of the single character to underline in the text layout, or a
negative number counting backwards from the end of the string. Any
out-of-range number (e.g. INT_MIN) means no underline.
.AP int index in
The index of the character whose bounding box is desired.  The bounding
box is computed with respect to the upper-left hand corner of the text layout.
.AP int "*xPtr, *yPtr" out
Filled with the upper-left hand corner, in pixels, of the bounding box
for the character specified by \fIindex\fR.  Either or both \fIxPtr\fR
and \fIyPtr\fR may be NULL, in which case the corresponding value
is not calculated.

Tk_InitStubs \- initialize the Tk stubs mechanism
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
const char *
\fBTk_InitStubs\fR(\fIinterp, version, exact\fR)

.SH ARGUMENTS
.AS Tcl_Interp *interp in
.AP Tcl_Interp *interp in
Tcl interpreter handle.
.AP char *version in
A version string consisting of one or more decimal numbers
separated by dots.

its command-line arguments).
.PP
\fBTk_SafeInit\fR is identical to \fBTk_Init\fR except that it removes
all Tk commands that are considered unsafe.  Those commands and the
reasons for their exclusion are:
.TP
\fBbell\fR

Continuous ringing of the bell is a nuisance.
.TP
\fBclipboard\fR

A malicious script could replace the contents of the clipboard with
the string
.QW "\fBrm \-r *\fR"
and lead to surprises when the contents of the clipboard are pasted.
.TP
\fBgrab\fR

Grab can be used to block the user from using any other applications.
.TP
\fBmenu\fR

Menus can be used to cover the entire screen and to steal input from
the user.
.TP
\fBselection\fR

See clipboard.
.TP
\fBsend\fR

Send can be used to cause unsafe interpreters to execute commands.
.TP
\fBtk\fR

The tk command recreates the send command, which is unsafe.
.TP
\fBtkwait\fR

Tkwait can block the containing process forever
.TP
\fBtoplevel\fR

Toplevels can be used to cover the entire screen and to steal input
from the user.
.TP
\fBwm\fR

If toplevels are ever allowed, wm can be used to remove decorations,
move windows around, etc.
.SH KEYWORDS
safe, application, initialization, load, main window

.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_Main\fR(\fIargc, argv, appInitProc\fR)
.SH ARGUMENTS
.AS Tcl_AppInitProc *appInitProc
.AP int argc in
Number of elements in \fIargv\fR.
.AP char *argv[] in
Array of strings containing command-line arguments. On Windows, when
using -DUNICODE, the parameter type changes to wchar_t *.
.AP Tcl_AppInitProc *appInitProc in
Address of an application-specific initialization procedure.
The value for this argument is usually \fBTcl_AppInit\fR.

.SH NAME
Tk_GetOtherWindow, Tk_MakeContainer, Tk_MakeWindow, Tk_UseWindow \- window utility functions
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Tk_Window
\fBTk_GetOtherWindow(\fItkwin\fB)\fR
.sp
\fBTk_MakeContainer(\fItkwin\fB)\fR
.sp
\fBTk_MakeWindow(\fItkwin, parent\fB)\fR
.sp
int
\fBTk_UseWindow(\fIinterp, tkwin, string\fB)\fR

.SH ARGUMENTS
.AS XSetWindowAttributes borderWidth
.AP Tcl_Interp * interp in
Interpreter associated with the application.
.AP Tk_Window tkwin in
Token for window.
.AP Window parent in

\fBTk_Colormap\fR(\fItkwin\fR)
.sp
Tcl_Interp *
\fBTk_Interp\fR(\fItkwin\fR)
.sp
Tcl_Obj *
\fBTk_NewWindowObj\fR(\fItkwin\fR)

.SH ARGUMENTS
.AS Tk_Window tkwin
.AP Tk_Window tkwin in
Token for window.
.BE
.SH DESCRIPTION
.PP

The width and height information refers to the interior size
of the window, not including any border.  \fBTk_Changes\fR
returns a pointer to a structure containing all of the above
information plus a few other fields.  \fBTk_Attributes\fR
returns a pointer to an XSetWindowAttributes structure describing
all of the attributes of the \fItkwin\fR's window, such as background
pixmap, event mask, and so on (Tk keeps track of all this information
as it is changed by the application).  Note: it is essential that
applications use Tk procedures like \fBTk_ResizeWindow\fR instead
of X procedures like \fBXResizeWindow\fR, so that Tk can keep its
data structures up-to-date.
.PP
\fBTk_IsContainer\fR returns a non-zero value if \fItkwin\fR
is a container, and that some other application may be embedding
itself inside \fItkwin\fR.

times, and also place a time and space requirement on the sequence: for a
sequence of events to match a \fBDouble\fR, \fBTriple\fR or \fBQuadruple\fR
pattern, all of the events must occur close together in time and without
substantial mouse motion in between.  For example, \fB<Double\-Button\-1>\fR
is equivalent to \fB<Button\-1><Button\-1>\fR with the extra time and space
requirement.
.PP
The \fBCommand\fR, \fBOption\fR, \fBNum\fR and \fBFn\fRmodifiers are equivalents

of \fBMod1\fR up to \fBMod4\fR, they correspond to Macintosh-specific modifier keys.
.PP
The \fBExtended\fR modifier is, at present, specific to Windows.  It
appears on events that are associated with the keys on the
.QW "extended keyboard" .
On a US keyboard, the extended keys include the \fBAlt\fR
and \fBControl\fR keys at the right of the keyboard, the cursor keys
in the cluster to the left of the numeric pad, the \fBNumLock\fR key,

appended scripts, is terminated but Tk will continue processing
binding scripts associated with other \fItag\fR's.
If the \fBbreak\fR command is invoked within a binding script,
then that script terminates and no other scripts will be invoked
for the event.
.PP
Within a script called from the binding script, \fBreturn\fR
\fB-code ok\fR may be used to continue processing (including
.QW +
appended scripts), or \fBreturn\fR \fB-code break\fR may be used to
stop processing all other binding scripts.
.PP
If more than one binding matches a particular event and they
have the same \fItag\fR, then the most specific binding
is chosen and its script is evaluated.
The following tests are applied, in order, to determine which of
several matching sequences is more specific:

The \fBbgerror\fR command will be executed at global level
(outside the context of any Tcl procedure).
.SH "EXAMPLES"
.PP
Arrange for a string describing the motion of the mouse to be printed
out when the mouse is double-clicked:
.CS
\fBbind\fR . <Double\-1> {
    puts "hi from (%x,%y)"
}
.CE
.PP
A little GUI that displays what the keysym name of the last key
pressed is:
.CS
set keysym "Press any key"
pack [label .l \-textvariable keysym \-padx 2m \-pady 1m]
\fBbind\fR . <Key> {
    set keysym "You pressed %K"
}
.CE
.SH "SEE ALSO"
bgerror(n), bindtags(n), event(n), focus(n), grab(n), keysyms(n)
.SH KEYWORDS
binding, event
'\" Local Variables:
'\" mode: nroff
'\" End:

'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
bitmap \- Images that display two colors
.SH SYNOPSIS
.nf
\fBimage create bitmap \fR?\fIname\fR? ?\fIoptions\fR?

\fIimageName \fBcget\fR \fIoption\fR
\fIimageName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
.fi
.BE
.SH DESCRIPTION
.PP
A bitmap is an image whose pixels can display either of two colors
or be transparent.

the source data is one and the background color if the source
data is zero.
.SH "CREATING BITMAPS"
.PP
Like all images, bitmaps are created using the \fBimage create\fR
command.
Bitmaps support the following \fIoptions\fR:

.TP
\fB\-background \fIcolor\fR
.
Specifies a background color for the image in any of the standard
ways accepted by Tk.  If this option is set to an empty string
then the background pixels will be transparent.  This effect
is achieved by using the source bitmap as the mask bitmap, ignoring
any \fB\-maskdata\fR or \fB\-maskfile\fR options.

.TP
\fB\-data \fIstring\fR
.
Specifies the contents of the source bitmap as a string.
The string must adhere to X11 bitmap format (e.g., as generated
by the \fBbitmap\fR program).
If both the \fB\-data\fR and \fB\-file\fR options are specified,
the \fB\-data\fR option takes precedence.

.TP
\fB\-file \fIname\fR
.
\fIname\fR gives the name of a file whose contents define the
source bitmap.
The file must adhere to X11 bitmap format (e.g., as generated
by the \fBbitmap\fR program).

.TP
\fB\-foreground \fIcolor\fR
.
Specifies a foreground color for the image in any of the standard
ways accepted by Tk.

.TP
\fB\-maskdata \fIstring\fR
.
Specifies the contents of the mask as a string.
The string must adhere to X11 bitmap format (e.g., as generated
by the \fBbitmap\fR program).
If both the \fB\-maskdata\fR and \fB\-maskfile\fR options are specified,
the \fB\-maskdata\fR option takes precedence.

.TP
\fB\-maskfile \fIname\fR
.
\fIname\fR gives the name of a file whose contents define the
mask.
The file must adhere to X11 bitmap format (e.g., as generated
by the \fBbitmap\fR program).
.SH "IMAGE COMMAND"
.PP
When a bitmap image is created, Tk also creates a new command
whose name is the same as the image.
This command may be used to invoke various operations
on the image.
It has the following general form:
.CS
\fIimageName option \fR?\fIarg ...\fR?
.CE
\fIOption\fR and the \fIarg\fRs
determine the exact behavior of the command.  The following
commands are possible for bitmap images:

.TP
\fIimageName \fBcget\fR \fIoption\fR
.
Returns the current value of the configuration option given
by \fIoption\fR.
\fIOption\fR may have any of the values accepted by the
\fBimage create\fR \fBbitmap\fR command.

.TP
\fIimageName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
.
Query or modify the configuration options for the image.
If no \fIoption\fR is specified, returns a list describing all of
the available options for \fIimageName\fR (see \fBTk_ConfigureInfo\fR for
information on the format of this list).  If \fIoption\fR is specified

.PP
The above example moves the focus from .frame immediately after invoking the
\fBhold\fR so that no keyboard events will be sent to \fB.frame\fR or any of
its descendants. It also makes sure it's not possible to leave button
\fB.cancel\fR using the keyboard.
.SH PORTABILITY
.PP
Note that the \fBtk busy\fR command does not currently have any effect on macOS
when Tk is built using Aqua support.
.SH "SEE ALSO"
grab(n)
.SH KEYWORDS
busy, keyboard events, pointer events, window
'\" Local Variables:
'\" mode: nroff

If the button's state is \fBdisabled\fR then none of the above
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/macOS, 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

.TH canvas n 8.3 Tk "Tk Built-In Commands"
.so man.macros
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
canvas \- Create and manipulate 'canvas' hypergraphics drawing surface widgets
.SH SYNOPSIS
\fBcanvas\fR \fIpathName \fR?\fIoptions\fR?
.SO
\-background	\-borderwidth	\-cursor
\-highlightbackground	\-highlightcolor	\-highlightthickness
\-insertbackground	\-insertborderwidth	\-insertofftime
\-insertontime	\-insertwidth	\-relief
\-selectbackground	\-selectborderwidth	\-selectforeground
\-takefocus	\-xscrollcommand	\-yscrollcommand

support as many of these forms as practical.
Note that it is possible to refer to the character just after
the last one in the text item; this is necessary for such
tasks as inserting new text at the end of the item.
Lines and Polygons do not support the insertion cursor
and the selection. Their indices are supposed to be even
always, because coordinates always appear in pairs.
.TP 10
\fInumber\fR
.
A decimal number giving the position of the desired character
within the text item.
0 refers to the first character, 1 to the next character, and
so on. If indexes are odd for lines and polygons, they will be
automatically decremented by one.
A negative number  is treated as if it were zero, and a
number greater than the length of the text item is treated
as if it were equal to the length of the text item. For
polygons, negative numbers or numbers greater than the length
of the coordinate list will be adjusted by adding or subtracting
the length until the result is between zero and the length,
inclusive.
.TP 10
\fBend\fR
.
Refers to the character or coordinate just after the last one
in the item (same as the number of characters or coordinates
in the item).
.TP 10
\fBinsert\fR
.
Refers to the character just before which the insertion cursor
is drawn in this item. Not valid for lines and polygons.
.TP 10
\fBsel.first\fR
.
Refers to the first selected character in the item.
If the selection is not in this item then this form is illegal.
.TP 10
\fBsel.last\fR
.
Refers to the last selected character in the item.
If the selection is not in this item then this form is illegal.
.TP 10
\fB@\fIx,y\fR
.
Refers to the character or coordinate at the point given by \fIx\fR and
\fIy\fR, where \fIx\fR and \fIy\fR are specified in the coordinate
system of the canvas.
If \fIx\fR and \fIy\fR lie outside the coordinates covered by the
text item, then they refer to the first or last character in the
line that is closest to the given point.
.SH "DASH PATTERNS"

operations on the widget. It has the following general form:
.CS
\fIpathName option \fR?\fIarg ...\fR?
.CE
\fIOption\fR and the \fIarg\fRs
determine the exact behavior of the command.
The following widget commands are possible for canvas widgets:

.TP
\fIpathName \fBaddtag \fItag searchSpec \fR?\fIarg ...\fR?
.
For each item that meets the constraints specified by
\fIsearchSpec\fR and the \fIarg\fRs, add
\fItag\fR to the list of tags associated with the item if it
is not already present on that list.
It is possible that no items will satisfy the constraints
given by \fIsearchSpec\fR and \fIarg\fRs, in which case the
command has no effect.
This command returns an empty string as result.
\fISearchSpec\fR and \fIarg\fR's may take any of the following
forms:
.RS
.TP
\fBabove \fItagOrId\fR
.
Selects the item just after (above) the one given by \fItagOrId\fR
in the display list.
If \fItagOrId\fR denotes more than one item, then the last (topmost)
of these items in the display list is used.
.TP
\fBall\fR
.
Selects all the items in the canvas.
.TP
\fBbelow \fItagOrId\fR
.
Selects the item just before (below) the one given by \fItagOrId\fR
in the display list.
If \fItagOrId\fR denotes more than one item, then the first (lowest)
of these items in the display list is used.
.TP
\fBclosest \fIx y \fR?\fIhalo\fR? ?\fIstart\fR?
.
Selects the item closest to the point given by \fIx\fR and \fIy\fR.
If more than one item is at the same closest distance (e.g. two
items overlap the point), then the top-most of these items (the
last one in the display list) is used.
If \fIhalo\fR is specified, then it must be a non-negative
value.
Any item closer than \fIhalo\fR to the point is considered to
overlap it.
The \fIstart\fR argument may be used to step circularly through
all the closest items.
If \fIstart\fR is specified, it names an item using a tag or id
(if by tag, it selects the first item in the display list with
the given tag).
Instead of selecting the topmost closest item, this form will
select the topmost closest item that is below \fIstart\fR in
the display list; if no such item exists, then the selection
behaves as if the \fIstart\fR argument had not been specified.
.TP
\fBenclosed\fR \fIx1\fR \fIy1\fR \fIx2\fR \fIy2\fR
.
Selects all the items completely enclosed within the rectangular
region given by \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR.
\fIX1\fR must be no greater than \fIx2\fR and \fIy1\fR must be
no greater than \fIy2\fR.
.TP
\fBoverlapping\fR \fIx1\fR \fIy1\fR \fIx2\fR \fIy2\fR
.
Selects all the items that overlap or are enclosed within the
rectangular region given by \fIx1\fR, \fIy1\fR, \fIx2\fR,
and \fIy2\fR.
\fIX1\fR must be no greater than \fIx2\fR and \fIy1\fR must be
no greater than \fIy2\fR.
.TP
\fBwithtag \fItagOrId\fR
.
Selects all the items given by \fItagOrId\fR.
.RE

.TP
\fIpathName \fBbbox \fItagOrId\fR ?\fItagOrId tagOrId ...\fR?
.
Returns a list with four elements giving an approximate bounding box
for all the items named by the \fItagOrId\fR arguments.
The list has the form
.QW "\fIx1 y1 x2 y2\fR"
such that the drawn
areas of all the named elements are within the region bounded by
\fIx1\fR on the left, \fIx2\fR on the right, \fIy1\fR on the top,
and \fIy2\fR on the bottom.
The return value may overestimate the actual bounding box by
a few pixels.
If no items match any of the \fItagOrId\fR arguments or if the
matching items have empty bounding boxes (i.e. they have nothing
to display)
then an empty string is returned.

.TP
\fIpathName \fBbind \fItagOrId\fR ?\fIsequence\fR? ?\fIcommand\fR?
.
This command associates \fIcommand\fR with all the items given by
\fItagOrId\fR such that whenever the event sequence given by
\fIsequence\fR occurs for one of the items the command will
be invoked.

.PP
If bindings have been created for a canvas window using the \fBbind\fR
command, then they are invoked in addition to bindings created for
the canvas's items using the \fBbind\fR widget command.
The bindings for items will be invoked before any of the bindings
for the window as a whole.
.RE

.TP
\fIpathName \fBcanvasx \fIscreenx\fR ?\fIgridspacing\fR?
.
Given a window x-coordinate in the canvas \fIscreenx\fR, this command returns
the canvas x-coordinate that is displayed at that location.
If \fIgridspacing\fR is specified, then the canvas coordinate is
rounded to the nearest multiple of \fIgridspacing\fR units.

.TP
\fIpathName \fBcanvasy \fIscreeny\fR ?\fIgridspacing\fR?
.
Given a window y-coordinate in the canvas \fIscreeny\fR this command returns
the canvas y-coordinate that is displayed at that location.
If \fIgridspacing\fR is specified, then the canvas coordinate is
rounded to the nearest multiple of \fIgridspacing\fR units.

.TP
\fIpathName \fBcget\fR \fIoption\fR
.
Returns the current value of the configuration option given
by \fIoption\fR.
\fIOption\fR may have any of the values accepted by the \fBcanvas\fR
command.

.TP
\fIpathName \fBconfigure ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR?
.
Query or modify the configuration options of the widget.
If no \fIoption\fR is specified, returns a list describing all of
the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for
information on the format of this list). If \fIoption\fR is specified
with no \fIvalue\fR, then the command returns a list describing the
one named option (this list will be identical to the corresponding
sublist of the value returned if no \fIoption\fR is specified). If
one or more \fIoption\-value\fR pairs are specified, then the command
modifies the given widget option(s) to have the given value(s); in
this case the command returns an empty string.
\fIOption\fR may have any of the values accepted by the \fBcanvas\fR
command.

.TP
\fIpathName\fR \fBcoords \fItagOrId \fR?\fIx0 y0 ...\fR?
.TP
\fIpathName\fR \fBcoords \fItagOrId \fR?\fIcoordList\fR?
.
Query or modify the coordinates that define an item.
If no coordinates are specified, this command returns a list
whose elements are the coordinates of the item named by
\fItagOrId\fR.
If coordinates are specified, then they replace the current
coordinates for the named item.
If \fItagOrId\fR refers to multiple items, then
the first one in the display list is used.
.RS
.PP
Note that for rectangles, ovals and arcs the returned list of coordinates
has a fixed order, namely the left, top, right and bottom coordinates,
which may not be the order originally given. Also the coordinates are always
returned in screen units with no units (that is, in pixels). So if the
original coordinates were specified for instance in centimeters or inches,
the returned values will nevertheless be in pixels.
.RE

.TP
\fIpathName \fBcreate \fItype x y \fR?\fIx y ...\fR? ?\fIoption value ...\fR?
.TP
\fIpathName \fBcreate \fItype coordList \fR?\fIoption value ...\fR?
.
Create a new item in \fIpathName\fR of type \fItype\fR.
The exact format of the arguments after \fItype\fR depends
on \fItype\fR, but usually they consist of the coordinates for
one or more points, followed by specifications for zero or
more item options.
See the subsections on individual item types below for more
on the syntax of this command.
This command returns the id for the new item.

.TP
\fIpathName \fBdchars \fItagOrId first \fR?\fIlast\fR?
.
For each item given by \fItagOrId\fR, delete the characters, or coordinates,
in the range given by \fIfirst\fR and \fIlast\fR, inclusive.
If some of the items given by \fItagOrId\fR do not support
indexing operations then they ignore this operation.
Text items interpret \fIfirst\fR and \fIlast\fR as indices to a character,
line and polygon items interpret them as indices to a coordinate (an x,y pair).
Indices are described in \fBINDICES\fR above.
If \fIlast\fR is omitted, it defaults to \fIfirst\fR.
This command returns an empty string.

.TP
\fIpathName \fBdelete \fR?\fItagOrId tagOrId ...\fR?
.
Delete each of the items given by each \fItagOrId\fR, and return
an empty string.

.TP
\fIpathName \fBdtag \fItagOrId \fR?\fItagToDelete\fR?
.
For each of the items given by \fItagOrId\fR, delete the
tag given by \fItagToDelete\fR from the list of those
associated with the item.
If an item does not have the tag \fItagToDelete\fR then
the item is unaffected by the command.
If \fItagToDelete\fR is omitted then it defaults to \fItagOrId\fR.
This command returns an empty string.

.TP
\fIpathName \fBfind \fIsearchCommand \fR?\fIarg ...\fR?
.
This command returns a list consisting of all the items that
meet the constraints specified by \fIsearchCommand\fR and
\fIarg\fR's.
\fISearchCommand\fR and \fIargs\fR have any of the forms
accepted by the \fBaddtag\fR command.
The items are returned in stacking order, with the lowest item first.

.TP
\fIpathName \fBfocus \fR?\fItagOrId\fR?
.
Set the keyboard focus for the canvas widget to the item given by
\fItagOrId\fR.
If \fItagOrId\fR refers to several items, then the focus is set
to the first such item in the display list that supports the

a given item does not actually have the input focus unless (a)
its canvas is the focus window and (b) the item is the focus item
within the canvas.
In most cases it is advisable to follow the \fBfocus\fR widget
command with the \fBfocus\fR command to set the focus window to
the canvas (if it was not there already).
.RE

.TP
\fIpathName \fBgettags\fR \fItagOrId\fR
.
Return a list whose elements are the tags associated with the
item given by \fItagOrId\fR.
If \fItagOrId\fR refers to more than one item, then the tags
are returned from the first such item in the display list.
If \fItagOrId\fR does not refer to any items, or if the item
contains no tags, then an empty string is returned.

.TP
\fIpathName \fBicursor \fItagOrId index\fR
.
Set the position of the insertion cursor for the item(s) given by \fItagOrId\fR
to just before the character whose position is given by \fIindex\fR.
If some or all of the items given by \fItagOrId\fR do not support
an insertion cursor then this command has no effect on them.
See \fBINDICES\fR above for a description of the
legal forms for \fIindex\fR.


Note: the insertion cursor is only displayed in an item if
that item currently has the keyboard focus (see the \fBfocus\fR widget
command, above), but the cursor position may
be set even when the item does not have the focus.

This command returns an empty string.


.TP
\fIpathName \fBimage \fIimagename\fR ?\fIsubsample\fR? ?\fIzoom\fR?
.
Draw the canvas into the Tk photo image named \fIimagename\fR. If a \fB-scrollregion\fR
has been defined then this will be the boundaries of the canvas region drawn and the
final size of the photo image. Otherwise the widget width and height with an origin

of 0,0 will be the size of the canvas region drawn and the final size of the photo
image. Optionally an integer \fIsubsample\fR factor may be given and the photo image



will be reduced in size. In addition to the \fIsubsample\fR an integer \fIzoom\fR
factor can also be given and the photo image will be enlarged. The image background
will be filled with the canvas background colour. The canvas widget does not need to
be mapped for this widget command to work, but at least one of it's ancestors must be
mapped.

This command returns an empty string.


.TP
\fIpathName \fBimove \fItagOrId index x y\fR
.
This command causes the \fIindex\fR'th coordinate of each of the items
indicated by \fItagOrId\fR to be relocated to the location (\fIx\fR,\fIy\fR).
Each item interprets \fIindex\fR independently according to the rules
described in \fBINDICES\fR above. Out of the standard set of items, only line
and polygon items may have their coordinates relocated this way.

.TP
\fIpathName \fBindex \fItagOrId index\fR
.
This command returns a decimal string giving the numerical index
within \fItagOrId\fR corresponding to \fIindex\fR.
\fIIndex\fR gives a textual description of the desired position
as described in \fBINDICES\fR above.
Text items interpret \fIindex\fR as an index to a character,
line and polygon items interpret it as an index to a coordinate (an x,y pair).
The return value is guaranteed to lie between 0 and the number
of characters, or coordinates, within the item, inclusive.
If \fItagOrId\fR refers to multiple items, then the index
is processed in the first of these items that supports indexing
operations (in display list order).

.TP
\fIpathName \fBinsert \fItagOrId beforeThis string\fR
.
For each of the items given by \fItagOrId\fR, if the item supports
text or coordinate, insertion then \fIstring\fR is inserted into the item's
text just before the character, or coordinate, whose index is \fIbeforeThis\fR.
Text items interpret \fIbeforeThis\fR as an index to a character,
line and polygon items interpret it as an index to a coordinate (an x,y pair).
For lines and polygons the \fIstring\fR must be a valid coordinate
sequence.


See \fBINDICES\fR above for information about the forms allowed
for \fIbeforeThis\fR.

This command returns an empty string.


.TP
\fIpathName \fBitemcget\fR \fItagOrId\fR \fIoption\fR
.
Returns the current value of the configuration option for the
item given by \fItagOrId\fR whose name is \fIoption\fR.
This command is similar to the \fBcget\fR widget command except that
it applies to a particular item rather than the widget as a whole.
\fIOption\fR may have any of the values accepted by the \fBcreate\fR
widget command when the item was created.
If \fItagOrId\fR is a tag that refers to more than one item,
the first (lowest) such item is used.

.TP
\fIpathName \fBitemconfigure \fItagOrId\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR?
.
This command is similar to the \fBconfigure\fR widget command except
that it modifies item-specific options for the items given by
\fItagOrId\fR instead of modifying options for the overall
canvas widget.

modifies the given widget option(s) to have the given value(s) in
each of the items given by \fItagOrId\fR; in
this case the command returns an empty string.
The \fIoption\fRs and \fIvalue\fRs are the same as those permissible
in the \fBcreate\fR widget command when the item(s) were created;
see the sections describing individual item types below for details
on the legal options.

.TP
\fIpathName \fBlower \fItagOrId \fR?\fIbelowThis\fR?
.
Move all of the items given by \fItagOrId\fR to a new position
in the display list just before the item given by \fIbelowThis\fR.
If \fItagOrId\fR refers to more than one item then all are moved
but the relative order of the moved items will not be changed.
\fIBelowThis\fR is a tag or id; if it refers to more than one
item then the first (lowest) of these items in the display list is used
as the destination location for the moved items.
Note: this command has no effect on window items. Window items always
obscure other item types, and the stacking order of window items is
determined by the \fBraise\fR command and \fBlower\fR command, not the
\fBraise\fR widget command and \fBlower\fR widget command for canvases.
This command returns an empty string.

.TP
\fIpathName \fBmove \fItagOrId xAmount yAmount\fR
.
Move each of the items given by \fItagOrId\fR in the canvas coordinate
space by adding \fIxAmount\fR to the x-coordinate of each point
associated with the item and \fIyAmount\fR to the y-coordinate of
each point associated with the item.
This command returns an empty string.

.TP
\fIpathName \fBmoveto \fItagOrId xPos yPos\fR
.
Move the items given by \fItagOrId\fR in the canvas coordinate
space so that the first coordinate pair (the upper-left corner of the
bounding box) of the first item (the lowest in the display list) with
tag \fItagOrId\fR is located at
position (\fIxPos\fR,\fIyPos\fR). \fIxPos\fR and \fIyPos\fR may be
the empty string, in which case the corresponding coordinate
will be unchanged. All items matching
\fItagOrId\fR remain in the same positions relative to each other.
This command returns an empty string.

.TP
\fIpathName \fBpostscript \fR?\fIoption value option value ...\fR?
.
Generate a Postscript representation for part or all of the canvas.
If the \fB\-file\fR option is specified then the Postscript is written
to a file and an empty string is returned; otherwise the Postscript
is returned as the result of the command.

either invoke the \fBupdate\fR command to wait for the canvas window
to reach its final size, or else use the \fB\-width\fR and \fB\-height\fR
options to specify the area of the canvas to print.
The \fIoption\fR\-\fIvalue\fR argument pairs provide additional
information to control the generation of Postscript. The following
options are supported:
.RS

.TP
\fB\-channel \fIchannelName\fR
.
Specifies the name of the channel to which to write the Postscript.
If this option and the \fB\-file\fR option are
not specified then the Postscript is returned as the
result of the command.

.TP
\fB\-colormap \fIvarName\fR
.
\fIVarName\fR must be the name of an array variable
that specifies a color mapping to use in the Postscript.
Each element of \fIvarName\fR must consist of Postscript
code to set a particular color value (e.g.
.QW "\fB1.0 1.0 0.0 setrgbcolor\fR" ).
When outputting color information in the Postscript, Tk checks
to see if there is an element of \fIvarName\fR with the same
name as the color.
If so, Tk uses the value of the element as the Postscript command
to set the color.


If this option has not been specified, or if there is no entry
in \fIvarName\fR for a given color, then Tk uses the red, green,
and blue intensities from the X color.


.TP
\fB\-colormode \fImode\fR
.
Specifies how to output color information. \fIMode\fR must be either
\fBcolor\fR (for full color output), \fBgray\fR (convert all colors
to their gray-scale equivalents) or \fBmono\fR (convert all colors
to black or white).

.TP
\fB\-file \fIfileName\fR
.
Specifies the name of the file in which to write the Postscript.
If this option and the \fB\-channel\fR option are
not specified then the Postscript is returned as the
result of the command.

.TP
\fB\-fontmap \fIvarName\fR
.
\fIVarName\fR must be the name of an array variable
that specifies a font mapping to use in the Postscript.
Each element of \fIvarName\fR must consist of a Tcl list with
two elements, which are the name and point size of a Postscript font.
When outputting Postscript commands for a particular font, Tk
checks to see if \fIvarName\fR contains an element with the same
name as the font.
If there is such an element, then the font information contained in
that element is used in the Postscript.
Otherwise Tk attempts to guess what Postscript font to use.
Tk's guesses generally only work for well-known fonts such as
Times and Helvetica and Courier, and only if the X font name does not
omit any dashes up through the point size.


For example, \fB\-*\-Courier\-Bold\-R\-Normal\-\-*\-120\-*\fR will work but
\fB*Courier\-Bold\-R\-Normal*120*\fR will not; Tk needs the dashes to
parse the font name).


.TP
\fB\-height \fIsize\fR
.
Specifies the height of the area of the canvas to print.
Defaults to the height of the canvas window.

.TP
\fB\-pageanchor \fIanchor\fR
.
Specifies which point of the printed area of the canvas should appear over
the positioning point on the page (which is given by the \fB\-pagex\fR
and \fB\-pagey\fR options).


For example, \fB\-pageanchor n\fR means that the top center of the
area of the canvas being printed (as it appears in the canvas window)
should be over the positioning point. Defaults to \fBcenter\fR.


.TP
\fB\-pageheight \fIsize\fR
.
Specifies that the Postscript should be scaled in both x and y so
that the printed area is \fIsize\fR high on the Postscript page.
\fISize\fR consists of a floating-point number followed by
\fBc\fR for centimeters, \fBi\fR for inches, \fBm\fR for millimeters,
or \fBp\fR or nothing for printer's points (1/72 inch).
Defaults to the height of the printed area on the screen.
If both \fB\-pageheight\fR and \fB\-pagewidth\fR are specified then
the scale factor from \fB\-pagewidth\fR is used (non-uniform scaling
is not implemented).

.TP
\fB\-pagewidth \fIsize\fR
.
Specifies that the Postscript should be scaled in both x and y so
that the printed area is \fIsize\fR wide on the Postscript page.
\fISize\fR has the same form as for \fB\-pageheight\fR.
Defaults to the width of the printed area on the screen.
If both \fB\-pageheight\fR and \fB\-pagewidth\fR are specified then
the scale factor from \fB\-pagewidth\fR is used (non-uniform scaling
is not implemented).

.TP
\fB\-pagex \fIposition\fR
.
\fIPosition\fR gives the x-coordinate of the positioning point on
the Postscript page, using any of the forms allowed for \fB\-pageheight\fR.
Used in conjunction with the \fB\-pagey\fR and \fB\-pageanchor\fR options
to determine where the printed area appears on the Postscript page.
Defaults to the center of the page.

.TP
\fB\-pagey \fIposition\fR
.
\fIPosition\fR gives the y-coordinate of the positioning point on
the Postscript page, using any of the forms allowed for \fB\-pageheight\fR.
Used in conjunction with the \fB\-pagex\fR and \fB\-pageanchor\fR options
to determine where the printed area appears on the Postscript page.
Defaults to the center of the page.

.TP
\fB\-rotate \fIboolean\fR
.
\fIBoolean\fR specifies whether the printed area is to be rotated 90
degrees.
In non-rotated output the x-axis of the printed area runs along
the short dimension of the page
.PQ portrait " orientation" ;
in rotated output the x-axis runs along the long dimension of the page
.PQ landscape " orientation" .
Defaults to non-rotated.

.TP
\fB\-width \fIsize\fR
.
Specifies the width of the area of the canvas to print.
Defaults to the width of the canvas window.

.TP
\fB\-x \fIposition\fR
.
Specifies the x-coordinate of the left edge of the area of the
canvas that is to be printed, in canvas coordinates, not window
coordinates.
Defaults to the coordinate of the left edge of the window.

.TP
\fB\-y \fIposition\fR
.
Specifies the y-coordinate of the top edge of the area of the
canvas that is to be printed, in canvas coordinates, not window
coordinates.
Defaults to the coordinate of the top edge of the window.
.RE

.TP
\fIpathName \fBraise \fItagOrId \fR?\fIaboveThis\fR?
.
Move all of the items given by \fItagOrId\fR to a new position
in the display list just after the item given by \fIaboveThis\fR.
If \fItagOrId\fR refers to more than one item then all are moved
but the relative order of the moved items will not be changed.
\fIAboveThis\fR is a tag or id; if it refers to more than one
item then the last (topmost) of these items in the display list is used
as the destination location for the moved items.
This command returns an empty string.
.RS
.PP
Note: this command has no effect on window items. Window items always
obscure other item types, and the stacking order of window items is
determined by the \fBraise\fR command and \fBlower\fR command, not the
\fBraise\fR widget command and \fBlower\fR widget command for canvases.
.RE

.TP
\fIpathName \fBrchars \fItagOrId first last string\fR
.
This command causes the text or coordinates between \fIfirst\fR and \fIlast\fR
for each of the items indicated by \fItagOrId\fR to be replaced by
\fIstring\fR. Each item interprets \fIfirst\fR and \fIlast\fR independently
according to the rules described in \fBINDICES\fR above. Out of the standard
set of items, text items support this operation by altering their text as
directed, and line and polygon items support this operation by altering their
coordinate list (in which case \fIstring\fR should be a list of coordinates to
use as a replacement). The other items ignore this operation.

.TP
\fIpathName \fBrotate \fItagOrId xOrigin yOrigin angle\fR
.VS "8.7, TIP164"
Rotate the coordinates of all of the items given by \fItagOrId\fR in canvas
coordinate space.
\fIXOrigin\fR and \fIyOrigin\fR identify the origin for the rotation
operation and \fIangle\fR identifies the amount to rotate the coordinates

points, and the \fBarc\fR, \fBoval\fR and \fBrectangle\fR types rotate about a
computed center point instead of moving the bounding box coordinates directly.
.PP
Some items (currently \fBarc\fR and\fB text\fR) have angles in their options;
this command \fIdoes not\fR affect those options.
.RE
.VE "8.7, TIP164"

.TP
\fIpathName \fBscale \fItagOrId xOrigin yOrigin xScale yScale\fR
.
Rescale the coordinates of all of the items given by \fItagOrId\fR in canvas
coordinate space.
\fIXOrigin\fR and \fIyOrigin\fR identify the origin for the scaling
operation and \fIxScale\fR and \fIyScale\fR identify the scale

This command returns an empty string.
.RS
.PP
Note that some items have only a single pair of coordinates (e.g., text,
images and windows) and so scaling of them by this command can only move them
around.
.RE

.TP
\fIpathName \fBscan\fR \fIoption args\fR
.
This command is used to implement scanning on canvases. It has
two forms, depending on \fIoption\fR:
.RS
.TP
\fIpathName \fBscan mark \fIx y\fR
.

It then adjusts the view by \fIgain\fR times the
difference in coordinates, where \fIgain\fR defaults to 10.
This command is typically associated
with mouse motion events in the widget, to produce the effect of
dragging the canvas at high speed through its window. The return
value is an empty string.
.RE

.TP
\fIpathName \fBselect \fIoption\fR ?\fItagOrId arg\fR?
.
Manipulates the selection in one of several ways, depending on
\fIoption\fR.
The command may take any of the forms described below.
In all of the descriptions below, \fItagOrId\fR must refer to

The anchor point is determined by the most recent \fBselect adjust\fR
or \fBselect from\fR command for this widget.
If the selection anchor point for the widget is not currently in
\fItagOrId\fR, then it is set to the same character given
by \fIindex\fR.
Returns an empty string.
.RE

.TP
\fIpathName \fBtype\fI tagOrId\fR
.
Returns the type of the item given by \fItagOrId\fR, such as
\fBrectangle\fR or \fBtext\fR.
If \fItagOrId\fR refers to more than one item, then the type
of the first item in the display list is returned.
If \fItagOrId\fR does not refer to any items at all then
an empty string is returned.

.TP
\fIpathName \fBxview \fR?\fIargs\fR?
.
This command is used to query and change the horizontal position of the
information displayed in the canvas's window.
It can take any of the following forms:
.RS

If \fInumber\fR is negative then information farther to the left
becomes visible; if it is positive then information farther to the right
becomes visible.
If \fIwhat\fR is \fBunits\fR, the view adjusts left or right in units
of the \fBxScrollIncrement\fR option, if it is greater than zero,
or in units of one-tenth the window's width otherwise.
.RE

.TP
\fIpathName \fByview ?\fIargs\fR?
.
This command is used to query and change the vertical position of the
information displayed in the canvas's window.
It can take any of the following forms:
.RS

At present, text, line and polygon items provide this support.
For lines and polygons the indexing facility is used to manipulate
the coordinates of the item.
.SS "COMMON ITEM OPTIONS"
.PP
Many items share a common set of options. These options are
explained here, and then referred to be each widget type for brevity.

.TP
\fB\-anchor \fIanchorPos\fR
.
\fIAnchorPos\fR tells how to position the item relative to the
positioning point for the item; it may have any of the forms
accepted by \fBTk_GetAnchor\fR. For example, if \fIanchorPos\fR
is \fBcenter\fR then the item is centered on the point; if
\fIanchorPos\fR is \fBn\fR then the item will be drawn so that
its top center point is at the positioning point.
This option defaults to \fBcenter\fR.

.TP
\fB\-dash \fIpattern\fR

.TP
\fB\-activedash \fIpattern\fR

.TP
\fB\-disableddash \fIpattern\fR
.
This option specifies dash patterns for the normal, active
state, and disabled state of an item.
\fIpattern\fR may have any of the forms accepted by \fBTk_GetDash\fR.
If the dash options are omitted then the default is a solid outline.
See \fBDASH PATTERNS\fR for more information.

.TP
\fB\-dashoffset \fIoffset\fR
.
The starting \fIoffset\fR in pixels into the pattern provided by the
\fB\-dash\fR option. \fB\-dashoffset\fR is ignored if there is no
\fB\-dash\fR pattern. The \fIoffset\fR may have any of the forms described
in the \fBCOORDINATES\fR section above.

.TP
\fB\-fill \fIcolor\fR

.TP
\fB\-activefill \fIcolor\fR

.TP
\fB\-disabledfill \fIcolor\fR
.
Specifies the color to be used to fill item's area.
in its normal, active, and disabled states.
The even-odd fill rule is used.
\fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR.
For the line item, it specifies the color of the line drawn.
For the text item, it specifies the foreground color of the text.
If \fIcolor\fR is an empty string (the default for all canvas items
except line and text), then the item will not be filled.

.TP
\fB\-outline \fIcolor\fR

.TP
\fB\-activeoutline \fIcolor\fR

.TP
\fB\-disabledoutline \fIcolor\fR
.
This option specifies the color that should be used to draw the
outline of the item in its normal, active and disabled states.
\fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR.
If \fIcolor\fR is specified as an empty string then no outline is drawn
for the item.

.TP
\fB\-offset \fIoffset\fR
.
Specifies the offset of stipples. The offset value can be of the form
\fBx,y\fR or \fIside\fR, where side can be \fBn\fR, \fBne\fR, \fBe\fR,
\fBse\fR, \fBs\fR, \fBsw\fR, \fBw\fR, \fBnw\fR, or \fBcenter\fR. In the
first case the origin is the origin of the toplevel of the current window.
For the canvas itself and canvas objects the origin is the canvas origin,
but putting \fB#\fR in front of the coordinate pair indicates using the
toplevel origin instead. For canvas objects, the \fB\-offset\fR option is
used for stippling as well. For the line and polygon canvas items you can
also specify an index as argument, which connects the stipple origin to one
of the coordinate points of the line/polygon. Note that stipple offsets are
\fIonly supported on X11\fR; they are silently ignored on other platforms.

.TP
\fB\-outlinestipple \fIbitmap\fR

.TP
\fB\-activeoutlinestipple \fIbitmap\fR

.TP
\fB\-disabledoutlinestipple \fIbitmap\fR
.
This option specifies stipple patterns that should be used to draw the
outline of the item in its normal, active and disabled states.
Indicates that the outline for the item should be drawn with a stipple pattern;
\fIbitmap\fR specifies the stipple pattern to use, in any of the
forms accepted by \fBTk_GetBitmap\fR.
If the \fB\-outline\fR option has not been specified then this option
has no effect.
If \fIbitmap\fR is an empty string (the default), then the outline is drawn
in a solid fashion.
\fINote that stipples are not well supported on platforms that do not
use X11 as their drawing API.\fR

.TP
\fB\-outlineoffset \fIoffset\fR
.
Specifies the offset of the stipple pattern used for outlines, in the same way
that the \fB\-outline\fR option controls fill stipples. (See the
\fB\-outline\fR option for a description of the syntax of \fIoffset\fR.)

.TP
\fB\-stipple \fIbitmap\fR

.TP
\fB\-activestipple \fIbitmap\fR

.TP
\fB\-disabledstipple \fIbitmap\fR
.
This option specifies stipple patterns that should be used to fill
the item in its normal, active and disabled states.
\fIbitmap\fR specifies the stipple pattern to use, in any of the
forms accepted by \fBTk_GetBitmap\fR.
If the \fB\-fill\fR option has not been specified then this option
has no effect.
If \fIbitmap\fR is an empty string (the default), then filling is done
in a solid fashion.
For the text item, it affects the actual text.
\fINote that stipples are not well supported on platforms that do not
use X11 as their drawing API.\fR

.TP
\fB\-state \fIstate\fR
.
This allows an item to override the canvas widget's global \fIstate\fR
option. It takes the same values:
\fInormal\fR, \fIdisabled\fR or \fIhidden\fR.

.TP
\fB\-tags \fItagList\fR
.
Specifies a set of tags to apply to the item.
\fITagList\fR consists of a list of tag names, which replace any
existing tags for the item. \fITagList\fR may be an empty list.

.TP
\fB\-width \fIoutlineWidth\fR

.TP
\fB\-activewidth \fIoutlineWidth\fR

.TP
\fB\-disabledwidth \fIoutlineWidth\fR
.
Specifies the width of the outline to be drawn around
the item's region, in its normal, active and disabled states.
\fIoutlineWidth\fR may be in any of the forms described in the
\fBCOORDINATES\fR section above.
If the \fB\-outline\fR option has been specified as an empty string then
this option has no effect. This option defaults to 1.0.
For arcs, wide outlines will be drawn centered on the edges of the
arc's region.
.SH "STANDARD ITEM TYPES"
.SS "ARC ITEMS"
.PP
Items of type \fBarc\fR appear on the display as arc-shaped regions.
An arc is a section of an oval delimited by two angles (specified
by either the \fB\-start\fR and \fB\-extent\fR options or the \fB\-height\fR option)
and displayed in one of several ways (specified by the \fB\-style\fR option).

Arcs are created with widget commands of the following form:
.CS
\fIpathName \fBcreate arc \fIx1 y1 x2 y2 \fR?\fIoption value ...\fR?
\fIpathName \fBcreate arc \fIcoordList\fR ?\fIoption value ...\fR?
.CE
The arguments \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR or \fIcoordList\fR give
the coordinates of two diagonally opposite corners of a

\fB\-disabledoutlinestipple\fR	\fB\-stipple\fR
\fB\-activestipple\fR	\fB\-disabledstipple\fR
\fB\-state\fR	\fB\-tags\fR
\fB\-width\fR	\fB\-activewidth\fR
\fB\-disabledwidth\fR
.DE
The following extra options are supported for arcs:

.TP
\fB\-extent \fIdegrees\fR

Specifies the size of the angular range occupied by the arc.
The arc's range extends for \fIdegrees\fR degrees counter-clockwise
from the starting angle given by the \fB\-start\fR option.
\fIDegrees\fR may be negative.
If it is greater than 360 or less than \-360, then \fIdegrees\fR
modulo 360 is used as the extent.

.TP
\fB\-start \fIdegrees\fR

Specifies the beginning of the angular range occupied by the
arc.
\fIDegrees\fR is given in units of degrees measured counter-clockwise
from the 3-o'clock position; it may be either positive or negative.

.TP
\fB\-height \fIdistance\fR

Provides a shortcut for creating a circular arc segment by defining the
distance of the mid-point of the arc from its chord. When this option
is used the coordinates are interpreted as the start and end coordinates
of the chord, and the options \fB\-start\fR and \fB-extent\fR are ignored.
The value of \fIdistance\fR has the following meaning:
.RS
.PP
.RS
\fIdistance\fR > 0 creates a clockwise arc
.br
\fIdistance\fR < 0 creates an counter-clockwise arc

.RE
.PP
choosing the minus sign for the minor arc and the plus sign for the major arc.
.PP
Note that \fBitemcget \-height\fR always returns 0 so that introspection code
can be kept simple.
.RE

.TP
\fB\-style \fItype\fR

Specifies how to draw the arc. If \fItype\fR is \fBpieslice\fR
(the default) then the arc's region is defined by a section
of the oval's perimeter plus two line segments, one between the center
of the oval and each end of the perimeter section.
If \fItype\fR is \fBchord\fR then the arc's region is defined
by a section of the oval's perimeter plus a single line segment
connecting the two end points of the perimeter section.

The following standard options are supported by bitmaps:
.DS
.ta 3i
\fB\-anchor\fR	\fB\-state\fR
\fB\-tags\fR
.DE
The following extra options are supported for bitmaps:

.TP
\fB\-background \fIcolor\fR

.TP
\fB\-activebackground \fIcolor\fR

.TP
\fB\-disabledbackground \fIcolor\fR

Specifies the color to use for each of the bitmap's
.QW 0
valued pixels in its normal, active and disabled states.
\fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR.
If this option is not specified, or if it is specified as an empty
string, then nothing is displayed where the bitmap pixels are 0; this
produces a transparent effect.

.TP
\fB\-bitmap \fIbitmap\fR

.TP
\fB\-activebitmap \fIbitmap\fR

.TP
\fB\-disabledbitmap \fIbitmap\fR

Specifies the bitmaps to display in the item in its normal, active and
disabled states.
\fIBitmap\fR may have any of the forms accepted by \fBTk_GetBitmap\fR.

.TP
\fB\-foreground \fIcolor\fR

.TP
\fB\-activeforeground \fIcolor\fR

.TP
\fB\-disabledforeground \fIcolor\fR

Specifies the color to use for each of the bitmap's
.QW 1
valued pixels in its normal, active and disabled states.
\fIColor\fR may have any of the forms accepted by \fBTk_GetColor\fR.
.SS "IMAGE ITEMS"
.PP
Items of type \fBimage\fR are used to display images on a
canvas.

The following standard options are supported by images:
.DS
.ta 3i
\fB\-anchor\fR	\fB\-state\fR
\fB\-tags\fR
.DE
The following extra options are supported for images:

.TP
\fB\-image \fIname\fR

.TP
\fB\-activeimage \fIname\fR

.TP
\fB\-disabledimage \fIname\fR

Specifies the name of the images to display in the item in is normal,
active and disabled states.
This image must have been created previously with the
\fBimage create\fR command.
.SS "LINE ITEMS"
.PP
Items of type \fBline\fR appear on the display as one or more connected

\fB\-disabledfill\fR	\fB\-stipple\fR
\fB\-activestipple\fR	\fB\-disabledstipple\fR
\fB\-state\fR	\fB\-tags\fR
\fB\-width\fR	\fB\-activewidth\fR
\fB\-disabledwidth\fR
.DE
The following extra options are supported for lines:

.TP
\fB\-arrow \fIwhere\fR

Indicates whether or not arrowheads are to be drawn at one or both
ends of the line.
\fIWhere\fR must have one of the values \fBnone\fR (for no arrowheads),
\fBfirst\fR (for an arrowhead at the first point of the line),
\fBlast\fR (for an arrowhead at the last point of the line), or
\fBboth\fR (for arrowheads at both ends).
This option defaults to \fBnone\fR.
When requested to draw an arrowhead, Tk internally adjusts the corresponding
line end point so that the rendered line ends at the neck of the arrowhead
rather than at its tip so that the line doesn't extend past the edge of the
arrowhead. This may trigger a \fBLeave\fR event if the mouse is hovering this
line end. Conversely, when removing an arrowhead Tk adjusts the corresponding
line point the other way round, which may trigger an \fBEnter\fR event.

.TP
\fB\-arrowshape \fIshape\fR

This option indicates how to draw arrowheads.
The \fIshape\fR argument must be a list with three elements, each
specifying a distance in any of the forms described in
the \fBCOORDINATES\fR section above.
The first element of the list gives the distance along the line
from the neck of the arrowhead to its tip.
The second element gives the distance along the line from the
trailing points of the arrowhead to the tip, and the third
element gives the distance from the outside edge of the line to the
trailing points.
If this option is not specified then Tk picks a
.QW reasonable
shape.

.TP
\fB\-capstyle \fIstyle\fR

Specifies the ways in which caps are to be drawn at the endpoints
of the line.
\fIStyle\fR may have any of the forms accepted by \fBTk_GetCapStyle\fR
(\fBbutt\fR, \fBprojecting\fR, or \fBround\fR).
If this option is not specified then it defaults to \fBbutt\fR.
Where arrowheads are drawn the cap style is ignored.

.TP
\fB\-joinstyle \fIstyle\fR

Specifies the ways in which joints are to be drawn at the vertices
of the line.
\fIStyle\fR may have any of the forms accepted by \fBTk_GetJoinStyle\fR
(\fBbevel\fR, \fBmiter\fR, or \fBround\fR).
If this option is not specified then it defaults to \fBround\fR.
If the line only contains two points then this option is
irrelevant.

.TP
\fB\-smooth \fIsmoothMethod\fR

\fIsmoothMethod\fR must have one of the forms accepted by
\fBTcl_GetBoolean\fR or a line smoothing method.
Only \fBtrue\fR and \fBraw\fR are
supported in the core (with \fBbezier\fR being an alias for \fBtrue\fR), but more can be added at runtime. If a boolean

false value or empty string is given, no smoothing is applied. A boolean
truth value assumes \fBtrue\fR smoothing.
If the smoothing method is \fBtrue\fR, this indicates that the line
should be drawn as a curve, rendered as a set of quadratic splines: one spline
is drawn for the first and second line segments, one for the second
and third, and so on. Straight-line segments can be generated within
a curve by duplicating the end-points of the desired line segment.
If the smoothing method is \fBraw\fR, this indicates that the line
should also be drawn as a curve but where the list of coordinates is
such that the first coordinate pair (and every third coordinate pair
thereafter) is a knot point on a cubic Bezier curve, and the other
coordinates are control points on the cubic Bezier curve. Straight
line segments can be generated within a curve by making control points
equal to their neighbouring knot points. If the last point is a
control point and not a knot point, the point is repeated (one or two
times) so that it also becomes a knot point.

.TP
\fB\-splinesteps \fInumber\fR

Specifies the degree of smoothness desired for curves: each spline
will be approximated with \fInumber\fR line segments. This
option is ignored unless the \fB\-smooth\fR option is true or \fBraw\fR.
.SS "OVAL ITEMS"
.PP
Items of type \fBoval\fR appear as circular or oval regions on
the display. Each oval may have an outline, a fill, or

Polygon items support coordinate indexing operations using the \fBdchars\fR,
\fBindex\fR and \fBinsert\fR widget commands.
Polygons are created with widget commands of the following form:
.CS
\fIpathName \fBcreate polygon \fIx1 y1 ... xn yn \fR?\fIoption value ...\fR?
\fIpathName \fBcreate polygon \fIcoordList\fR ?\fIoption value ...\fR?
.CE
The arguments \fIx1\fR through \fIyn\fR or \fIcoordList\fR specify the coordinates for
three or more points that define a polygon.
The first point should not be repeated as the last to
close the shape; Tk will automatically close the periphery between
the first and last points.
After the coordinates there may be any number of \fIoption\fR\-\fIvalue\fR
pairs, each of which sets one of the configuration options
for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be
used in \fBitemconfigure\fR widget commands to change the item's

\fB\-disabledoutlinestipple\fR	\fB\-stipple\fR
\fB\-activestipple\fR	\fB\-disabledstipple\fR
\fB\-state\fR	\fB\-tags\fR
\fB\-width\fR	\fB\-activewidth\fR
\fB\-disabledwidth\fR
.DE
The following extra options are supported for polygons:

.TP
\fB\-joinstyle \fIstyle\fR

Specifies the ways in which joints are to be drawn at the vertices
of the outline.
\fIStyle\fR may have any of the forms accepted by \fBTk_GetJoinStyle\fR
(\fBbevel\fR, \fBmiter\fR, or \fBround\fR).
If this option is not specified then it defaults to \fBround\fR.

.TP
\fB\-smooth \fIboolean\fR

\fIBoolean\fR must have one of the forms accepted by \fBTcl_GetBoolean\fR
or a line smoothing method. Only \fBtrue\fR and \fBraw\fR are
supported in the core (with \fBbezier\fR being an alias for \fBtrue\fR), but more can be added at runtime. If a boolean

false value or empty string is given, no smoothing is applied. A boolean
truth value assumes \fBtrue\fR smoothing.
If the smoothing method is \fBtrue\fR, this indicates that the polygon
should be drawn as a curve, rendered as a set of quadratic splines: one spline
is drawn for the first and second line segments, one for the second
and third, and so on. Straight-line segments can be generated within
a curve by duplicating the end-points of the desired line segment.
If the smoothing method is \fBraw\fR, this indicates that the polygon
should also be drawn as a curve but where the list of coordinates is
such that the first coordinate pair (and every third coordinate pair
thereafter) is a knot point on a cubic Bezier curve, and the other
coordinates are control points on the cubic Bezier curve. Straight
line segments can be generated within a curve by making control points
equal to their neighbouring knot points. If the last point is not the
second point of a pair of control points, the point is repeated (one or two
times) so that it also becomes the second point of a pair of control
points (the associated knot point will be the first control point).

.TP
\fB\-splinesteps \fInumber\fR

Specifies the degree of smoothness desired for curves: each spline
will be approximated with \fInumber\fR line segments. This
option is ignored unless the \fB\-smooth\fR option is true or \fBraw\fR.
.PP
Polygon items are different from other items such as rectangles, ovals
and arcs in that interior points are considered to be
.QW inside

\fB\-anchor\fR	\fB\-fill\fR
\fB\-activefill\fR	\fB\-disabledfill\fR
\fB\-stipple\fR	\fB\-activestipple\fR
\fB\-disabledstipple\fR	\fB\-state\fR
\fB\-tags\fR
.DE
The following extra options are supported for text items:

.TP
\fB\-angle \fIrotationDegrees\fR
.
\fIRotationDegrees\fR tells how many degrees to rotate the text anticlockwise
about the positioning point for the text; it may have any floating-point value
from 0.0 to 360.0. For example, if \fIrotationDegrees\fR is \fB90\fR, then the
text will be drawn vertically from bottom to top.
This option defaults to \fB0.0\fR.

.TP
\fB\-font \fIfontName\fR

Specifies the font to use for the text item.
\fIFontName\fR may be any string acceptable to \fBTk_GetFont\fR.
If this option is not specified, it defaults to a system-dependent
font.

.TP
\fB\-justify \fIhow\fR

Specifies how to justify the text within its bounding region.
\fIHow\fR must be one of the values \fBleft\fR, \fBright\fR,
or \fBcenter\fR.
This option will only matter if the text is displayed as multiple
lines.
If the option is omitted, it defaults to \fBleft\fR.

.TP
\fB\-text \fIstring\fR

\fIString\fR specifies the characters to be displayed in the text item.
Newline characters cause line breaks.
The characters in the item may also be changed with the
\fBinsert\fR and \fBdelete\fR widget commands.
This option defaults to an empty string.

.TP
\fB\-underline \fI\fR

Specifies the integer index of a character within the text to be
underlined. 0 corresponds to the first character of the text
displayed, 1 to the next character, and so on. \-1 means that no
underline should be drawn (if the whole text item is to be underlined,
the appropriate font should be used instead).

.TP
\fB\-width \fIlineLength\fR

Specifies a maximum line length for the text, in any of the forms
described in the \fBCOORDINATES\fR section above.
If this option is zero (the default) the text is broken into
lines only at newline characters.
However, if this option is non-zero then any line that would
be longer than \fIlineLength\fR is broken just before a space
character to make the line shorter than \fIlineLength\fR; the

The following standard options are supported by window items:
.DS
.ta 3i
\fB\-anchor\fR	\fB\-state\fR
\fB\-tags\fR
.DE
The following extra options are supported for window items:

.TP
\fB\-height \fIpixels\fR
.
Specifies the height to assign to the item's window.
\fIPixels\fR may have any of the
forms described in the \fBCOORDINATES\fR section above.
If this option is not specified, or if it is specified as zero,
then the window is given whatever height it requests internally.

.TP
\fB\-width \fIpixels\fR
.
Specifies the width to assign to the item's window.
\fIPixels\fR may have any of the
forms described in the \fBCOORDINATES\fR section above.
If this option is not specified, or if it is specified as zero,
then the window is given whatever width it requests internally.

.TP
\fB\-window \fIpathName\fR
.
Specifies the window to associate with this item.
The window specified by \fIpathName\fR must either be a child of
the canvas widget or a child of some ancestor of the canvas widget.
\fIPathName\fR may not refer to a top-level window.
.PP
Note: due to restrictions in the ways that windows are managed, it is not
possible to draw other graphical items (such as lines and images) on top
of window items. A window item always obscures any graphics that
overlap it, regardless of their order in the display list. Also note that
window items, unlike other canvas items, are not clipped for display by their
containing canvas's border, and are instead clipped by the parent widget of
the window specified by the \fB\-window\fR option; when the parent widget is
the canvas, this means that the window item can overlap the canvas's border.

operations on the widget.  It has the following general form:
.CS
\fIpathName option \fR?\fIarg ...\fR?
.CE
\fIOption\fR and the \fIarg\fRs
determine the exact behavior of the command.  The following
commands are possible for checkbutton widgets:

.TP
\fIpathName \fBcget\fR \fIoption\fR

Returns the current value of the configuration option given
by \fIoption\fR.
\fIOption\fR may have any of the values accepted by the \fBcheckbutton\fR
command.

.TP
\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?

Query or modify the configuration options of the widget.
If no \fIoption\fR is specified, returns a list describing all of
the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for
information on the format of this list).  If \fIoption\fR is specified
with no \fIvalue\fR, then the command returns a list describing the
one named option (this list will be identical to the corresponding
sublist of the value returned if no \fIoption\fR is specified).  If
one or more \fIoption\-value\fR pairs are specified, then the command
modifies the given widget option(s) to have the given value(s);  in
this case the command returns an empty string.
\fIOption\fR may have any of the values accepted by the \fBcheckbutton\fR
command.

.TP
\fIpathName \fBdeselect\fR

Deselects the checkbutton and sets the associated variable to its
.QW off
value.

.TP
\fIpathName \fBflash\fR

Flashes the checkbutton.  This is accomplished by redisplaying the checkbutton
several times, alternating between active and normal colors.  At
the end of the flash the checkbutton is left in the same normal/active
state as when the command was invoked.
This command is ignored if the checkbutton's state is \fBdisabled\fR.

.TP
\fIpathName \fBinvoke\fR

Does just what would have happened if the user invoked the checkbutton
with the mouse: toggle the selection state of the button and invoke
the Tcl command associated with the checkbutton, if there is one.
The return value is the return value from the Tcl command, or an
empty string if there is no command associated with the checkbutton.
This command is ignored if the checkbutton's state is \fBdisabled\fR.

.TP
\fIpathName \fBselect\fR

Selects the checkbutton and sets the associated variable to its
.QW on
value.

.TP
\fIpathName \fBtoggle\fR

Toggles the selection state of the button, redisplaying it and
modifying its associated variable to reflect the new state.
.SH BINDINGS
.PP
Tk automatically creates class bindings for checkbuttons that give them
the following default behavior:
.IP [1]

The behavior of checkbuttons can be changed by defining new bindings for
individual widgets or by redefining the class bindings.
.SH EXAMPLE
.PP
This example shows a group of uncoupled checkbuttons.
.PP
.CS
labelframe .lbl \-text "Steps:"
\fBcheckbutton\fR .c1 \-text Lights  \-variable lights
\fBcheckbutton\fR .c2 \-text Cameras \-variable cameras
\fBcheckbutton\fR .c3 \-text Action! \-variable action
pack .c1 .c2 .c3 \-in .lbl
pack .lbl
.CE
.SH "SEE ALSO"
button(n), options(n), radiobutton(n), ttk::checkbutton(n)
.SH KEYWORDS
checkbutton, widget
'\" Local Variables:
'\" mode: nroff
'\" End:

\fBtk_chooseColor \fR?\fIoption value ...\fR?
.BE
.SH DESCRIPTION
.PP
The procedure \fBtk_chooseColor\fR pops up a dialog box for the
user to select a color. The following \fIoption\-value\fR pairs are
possible as command line arguments:

.TP
\fB\-initialcolor\fR \fIcolor\fR

Specifies the color to display in the color dialog when it pops
up. \fIcolor\fR must be in a form acceptable to the \fBTk_GetColor\fR
function.

.TP
\fB\-parent\fR \fIwindow\fR

Makes \fIwindow\fR the logical parent of the color dialog. The color
dialog is displayed on top of its parent window.

.TP
\fB\-title\fR \fItitleString\fR

Specifies a string to display as the title of the dialog box. If this
option is not specified, then a default title will be displayed.
.LP
If the user selects a color, \fBtk_chooseColor\fR will return the
name of the color in a form acceptable to \fBTk_GetColor\fR.  If the
user cancels the operation, both commands will return the empty
string.
.SH EXAMPLE
.PP
.CS
button .b \-bg [tk_chooseColor \-initialcolor gray \-title "Choose color"]
.CE
.SH KEYWORDS
color, color selection, dialog
'\" Local Variables:
'\" mode: nroff
'\" End:

.TP
\fB\-command\fI string\fR
.
Specifies the prefix of a Tcl command to invoke when the user closes the
dialog after having selected an item. This callback is not called if the
user cancelled the dialog. The actual command consists of \fIstring\fR
followed by a space and the value selected by the user in the dialog. This
is only available on macOS.
.\" OPTION: -initialdir
.TP
\fB\-initialdir\fI dirname\fR
.
Specifies that the directories in \fIdirectory\fR should be displayed
when the dialog pops up. If this parameter is not specified,
the initial directory defaults to the current working directory
on non-Windows systems and on Windows systems prior to Vista.
On Vista and later systems, the initial directory defaults to the last
user-selected directory for the application. If the
parameter specifies a relative path, the return value will convert the
relative path to an absolute path.
.\" OPTION: -message
.TP
\fB\-message\fI string\fR
.
Specifies a message to include in the client area of the dialog.
This is only available on macOS.
.\" OPTION: -mustexist
.TP
\fB\-mustexist\fI boolean\fR
.
Specifies whether the user may specify non-existent directories.  If
this parameter is true, then the user may only select directories that
already exist.  The default value is \fIfalse\fR.
.\" OPTION: -parent
.TP
\fB\-parent\fI window\fR
.
Makes \fIwindow\fR the logical parent of the dialog. The dialog
is displayed on top of its parent window. On macOS, this
turns the file dialog into a sheet attached to the parent window.
.\" OPTION: -title
.TP
\fB\-title\fI titleString\fR
.
Specifies a string to display as the title of the dialog box. If this
option is not specified, then a default title will be displayed.

be called, followed by a sequence of one or more calls to \fBclipboard
append\fR.  To ensure that the clipboard is updated atomically, all
appends should be completed before returning to the event loop.
.PP
The first argument to \fBclipboard\fR determines the format of the
rest of the arguments and the behavior of the command.  The following
forms are currently supported:

.TP
\fBclipboard append\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-format\fR \fIformat\fR? ?\fB\-type\fR \fItype\fR? ?\fB\-\|\-\fR? \fIdata\fR
.
Appends \fIdata\fR to the clipboard on \fIwindow\fR's
display in the form given by \fItype\fR with the representation given
by \fIformat\fR and claims ownership of the clipboard on \fIwindow\fR's
display.
.RS
.PP

irrelevant.
.PP
A \fB\-\|\-\fR argument may be specified to mark the end of options:  the
next argument will always be used as \fIdata\fR.
This feature may be convenient if, for example, \fIdata\fR starts
with a \fB\-\fR.
.RE

.TP
\fBclipboard clear\fR ?\fB\-displayof\fR \fIwindow\fR?
.
Claims ownership of the clipboard on \fIwindow\fR's display and removes
any previous contents.  \fIWindow\fR defaults to
.QW . .
Returns an empty string.

.TP
\fBclipboard get\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-type\fR \fItype\fR?
.
Retrieve data from the clipboard on \fIwindow\fR's display.
\fIWindow\fR defaults to
.QW . .
\fIType\fR specifies the form in which
the data is to be returned and should be an atom name such as \fBSTRING\fR
or \fBFILE_NAME\fR.  \fIType\fR defaults to \fBSTRING\fR.  This command is

# it produces a script that recreates the item(s) when executed
proc getItemConfig {canvas tag} {
   set script {}
   foreach item [$canvas find withtag $tag] {
      append script {$canvas create } [$canvas type $item]
      append script { } [$canvas coords $item] { }
      foreach config [$canvas itemconf $item] {
         lassign $config name \- \- \- value
         append script [list $name $value] { }
      }
      append script \en
   }
   return [string trim $script]
}

# Set up a binding on a canvas to cut and paste an item
set c [canvas .c]
pack $c
$c create text 150 30 \-text "cut and paste me"
bind $c <<Cut>> {
   \fBclipboard clear\fR
   \fBclipboard append \-type\fR TkCanvasItem \e
         [getItemConfig %W current]
   # Delete because this is cut, not copy.
   %W delete current
}
bind $c <<Paste>> {
   catch {
      set canvas %W
      eval [\fBclipboard get \-type\fR TkCanvasItem]
   }
}
.CE
.SH "SEE ALSO"
interp(n), selection(n)
.SH KEYWORDS
clear, format, clipboard, append, selection, type
'\" Local Variables:
'\" mode: nroff
'\" End:

yellow2	238	238 	0
yellow3	205	205 	0
yellow4	139	139 	0
YellowGreen	154	205 	50
.DE
.SH "PORTABILITY ISSUES"
.TP
\fBmacOS\fR
.
On macOS, the following additional system colors are available.  This
first group contains all of the HIBrush colors available in the
HIToolbox library. Note that on macOS 10.14 (Mojave) and later these
colors are unlikely to match the color actually used for the purpose
suggested by the color name.
.RS

systemWhite
systemWindowBody
.DE
.RE
.
Tk supports all of the NSColors in the macOS System ColorList.  The
convention for naming these colors is that the Tk name is generated by
capitalizing the macOS name and adding the prefix "system".  On macOS
10.14 (Mojave) and later many of these "semantic" colors will appear
differently depending on whether the NSWindow in which they are used has
the Aqua or DarkAqua appearance.  The System ColorList differs between
releases of macOS and some colors, such as systemLinkColor and
systemControlAccentColor, are simulated on older systems which did not
provide them.  All of the colors below are available on all supported
macOS releases, but newer systems will support additional colors.

'\"
'\" Copyright (c) 2001 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 console n 8.4 Tk "Tk Built-In Commands"
.so man.macros
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
console \- Control the console on systems without a real console
.SH SYNOPSIS
\fBconsole\fR \fIsubcommand\fR ?\fIarg ...\fR?
.BE
.SH DESCRIPTION
.PP
The console window is a replacement for a real console to allow input
and output on the standard I/O channels on platforms that do not have
a real console.  It is implemented as a separate interpreter with the
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 disabled when there is a startup script
and stdin is \fB/dev/null\fR (as is the case e.g. when a bundled application
embedding Tk is started by the macOS Launcher).  To enable the command
in that case, define the environment variable \fBTK_CONSOLE\fR.  This can be
done by modifying the Info.plist file by adding the LSEnvironment key
to the main dict and setting its value to be a dict with the key \fBTK_CONSOLE\fR.

.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
\fBconsoleinterp\fR command in the console interpreter.

.TP
\fBconsole hide\fR

Hide the console window from view.  Precisely equivalent to
withdrawing the \fB.\fR window in the console interpreter.

.TP
\fBconsole show\fR

Display the console window.  Precisely equivalent to deiconifying the
\fB.\fR window in the console interpreter.

.TP
\fBconsole title \fR?\fIstring\fR?

Query or modify the title of the console window.  If \fIstring\fR is
not specified, queries the title of the console window, and sets the
title of the console window to \fIstring\fR otherwise.  Precisely
equivalent to using the \fBwm title\fR command in the console
interpreter.
.SH "ACCESS TO THE MAIN INTERPRETER"
.PP
The \fBconsoleinterp\fR command in the console interpreter allows
scripts to be evaluated in the main interpreter.  It supports two
subcommands: \fBeval\fR and \fBrecord\fR.
.PP

.TP
\fBconsoleinterp eval \fIscript\fR

Evaluates \fIscript\fR as a Tcl script at the global level in the main
interpreter.

.TP
\fBconsoleinterp record \fIscript\fR

Records and evaluates \fIscript\fR as a Tcl script at the global level
in the main interpreter as if \fIscript\fR had been typed in at the
console.
.SH "ADDITIONAL TRAP CALLS"
.PP
There are several additional commands in the console interpreter that
are called in response to activity in the main interpreter.

size_nw_se
size_we
uparrow
wait
.CE
.RE
.TP
\fBmacOS\fR
.
On macOS, the following cursors are mapped to native cursors:
.RS
.CS
arrow
top_left_arrow
left_ptr
cross
crosshair